Date: Mon, 4 Feb 2013 05:17:18 +0100 From: Giorgos Keramidas <keramida@FreeBSD.org> To: Gabor Kovesdan <gabor@FreeBSD.org> Cc: doc@FreeBSD.org Subject: Re: RFC: Dealing with version-specific docs Message-ID: <20130204041717.GA68155@kobe> In-Reply-To: <51065CFC.5090803@FreeBSD.org> References: <51065CFC.5090803@FreeBSD.org>
next in thread | previous in thread | raw e-mail | index | archive | help
On 2013-01-28 12:11, Gabor Kovesdan <gabor@FreeBSD.org> wrote: > Hi, > > as you may know, the printed edition of FreeBSD Handbook is being > worked. In our current Handbook version, we have version-specific > information for different major releases, while the printed edition > shall concentrate on 9.X. We cannot just drop the parts that detail > older releases since they haven't yet reached EOL and there are > people out there still using these. So we have to deal somehow with > this situation. Fortunately, DocBook provides a mechanism, called > profiling, which we could use. It would also be beneficial for later > cleanup work since finding outdated information that has to do with > unsupported releases always requires big effort. I've made a draft > about how it could be done in a practical way: > https://wiki.freebsd.org/VersionSpecificDocs > > Please read it and if you have doubts, concerns or better > suggestions, please share them. I like the use of os= attributes, but I feel a bit at odds with the requirement to duplicate version information in the XML attribute *and* the contained text, e.g.: <para os="freebsd8">To do foobar on &os; 8.X, type bar.</para> <para os="freebsd9">To do foobar on &os; 9.X, type baz.</para> We are typing version numbers twice here, and this introduces both the possibility for error and the chance for missing important mismatches in XML attributes vs. actual text. Is there any way we can avoid typing the version numbers twice?
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20130204041717.GA68155>