Date: Mon, 27 Sep 1999 10:48:31 +0200 From: Jeroen Ruigrok/Asmodai <asmodai@wxs.nl> To: Nik Clayton <nik@freebsd.org> Cc: doc@freebsd.org Subject: Re: FreeBSD versions in the docs Message-ID: <19990927104831.E16203@daemon.ninth-circle.org> In-Reply-To: <19990925224206.A25199@kilt.nothing-going-on.org> References: <19990925224206.A25199@kilt.nothing-going-on.org>
next in thread | previous in thread | raw e-mail | index | archive | help
Nik, -doc, * Nik Clayton (nik@freebsd.org) [990926 04:46]: >The question has arisen as to how best to handle this. Do we want the >documentation to be targetted at one specific version of FreeBSD (and if >we did, which version -- -stable, I imagine)? Or do we want to be able >to document as many versions as we can? I'm conscious of the fact that >as we update the docs for new versions we're obliterating information >that's probably useful to people who have older systems. Yes, they can >pull the information about of the CVS repository as necessary, but it's >not a particularly user friendly thing to force them to do. The problem is that the interfaces/applications/whole system [pick yon poison] tends to change dramatically in CURRENT, diverging a lot from STABLE. The other problem we have is that should we document only STABLE, we are in for a good laugh when we migrate STABLE to 4.x and make 5.x CURRENT. I mean, then we need to update the handbook/faq on the double. Another aside, if you document CURRENT you are going to confuse people who follow STABLE. We don't want people to just start using CURRENT for the fun of it, it should be a concious choice. I think that the best way is to make a CURRENT/STABLE split of doc. I see no other easier way at this point. I would gladly hear ideas saying otherwise of course. >n Wed, Apr 21, 1999 at 11:36:35AM +0530, A Joseph Koshy wrote: >> Docbook has some features to handle versioning of text (using one of >> the common attributes of all the elements if I remember right). > >Do you mean the OS attribute? The DTD says > > --OS: Operating system to which element applies; no default-- > >which is the closest match I can think of. I thought there was another >one that was more appropriate but a quick scan through the DTD doesn't >show anything promising (of course, we could always add one). > >> There are a couple of places where version specific text would be >> really useful: e.g., the Handbook currently refers to disks by their >> pre-3.x names `sd[0-9]', while post 3.1 disks are named `da[0-9]' >> (see PR docs/11215). >> >> Can/should we use Docbook's facilities to handle version specific >> documentation? If so (or if not), do you have any guidelines on >> writing version specific text? > >[Having said that,] I'm not convinced as to the best way to do it. A number >of possible approaches spring to mind. [snip proposal 1, note's] I don't think you want something like that. It should be managable and yet easily to be looked over >2. You can use the OS attribute, and duplicate elements with different > values for this attribute. Perhaps > > <para os="RELENG_22">Disk devices look like > <devicename>sd<replaceable/nn/s<replaceable/n/</devicename>.</para> > > <para os="RELENG_3">Disk devices look like > <devicename>da<replaceable/nn/s<replaceable/n/</devicename>.</para> > > Or even > > <para>Disk devices look like > <devicename os="RELENG_22"/sd<replaceable/nn/s<replaceable/n// > <devicename os="RELENG_3"/da<replaceable/nn/s<replaceable/n//.</para> > > A pre-processor would go through the SGML, leaving only those elements > that either have no OS attribute, or have a specific value in it. You mean write something like a lex grammar for this task? >3. Use parameter entities; > > <!DOCTYPE book .... [ > <!ENTITY % releng.22 "IGNORE"> > <!ENTITY % releng.30 "IGNORE"> > <!ENTITY % releng.31 "IGNORE"> > ]> > > ... > > <![ %releng.22 [ > <para>Disk devices look like <devicename/sd/.</para> > ]]> > > <![ %releng.30 [ > <para>Disk devices look like <devicename/da/.</para> > ]]> > > <![ %releng.31 [ > <para>Disk devices look like <devicename/da/.</para> > ]]> > > and so on. Still quite cumbersome, but doesn't need a pre-processor > to strip out elements with the wrong OS attribute value. Why not? How does DocBook know where to get the appropriate OS version from then? >4. Use general entities and parameter entities > > <!DOCTYPE book ... [ > <!ENTITY % releng.22 "IGNORE"> > <!ENTITY % releng.30 "IGNORE"> > <!ENTITY % releng.31 "IGNORE"> > > <![ %releng.22 [ > <!ENTITY disk.device "sd"> > ]]> > > <![ %releng.30 [ > <!ENTITY disk.device "da"> > ]]> > > <![ %releng.31 [ > <!ENTITY disk.device "da"> > ]]> > ]> > > ... > > <para>Disk devices look like <devicename/&disk.device;/.</para> > > This would also work, but would quickly lead to a profusion of general > entities, which is probably over confusing. > >Incidentally, none of these tackle an important issue -- some changes might >only affect certain releases before being superceded. [snip rc.conf example] >There were 10 releases between 2.0 and 2.2.5, and 3 between 2.2.6 and 2.2.8. >We need some way of either saying > > (a) This content applies to all these versions > >or > > (b) This content applies to all versions between these two values > >Whichever way we do this, a third application is going to need to parse >this information out of the document, as I don't think this can be done in >SGML. >Perhaps we should extend the DocBook DTD and add two new attributes, >OSVersionMin and OSVersionMax for the minmum and maximum FreeBSD versions >that the element applies to? Could you propose this to Norman? I think this is an excellent extension to the current DTD. I just wonder if it will be in either 3.x, 4.x or I hope not in 5.x. >As you can see, I don't have any quick answers to this problem. I do not think easy answers are easily come by in this matter. Just take a look at every commercial related Operating System out there. They all have handbooks and other documents which evidently describe only the version you just bought/acquired. Of course it may have something akin to a migration guide [which might be a good idea for us as well btw] but otherwise they don't document the different versions all in one document. Then again, we have the luxury of chosing which version we want to use. -- Jeroen Ruigrok van der Werven/Asmodai asmodai(at)wxs.nl The BSD Programmer's Documentation Project <http://home.wxs.nl/~asmodai>; Network/Security Specialist BSD: Technical excellence at its best There is no greater sorrow than to recall, in misery, the time when we were happy. To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19990927104831.E16203>