RFC: Dealing with version-specific docs

[Hiroki Sato]

Gabor Kovesdan <gabor at freebsd.org> wrote
  in <51065CFC.5090803 at FreeBSD.org>:

ga> Hi,
ga>
ga> as you may know, the printed edition of FreeBSD Handbook is being
ga> worked. In our current Handbook version, we have version-specific
ga> information for different major releases, while the printed edition
ga> shall concentrate on 9.X. We cannot just drop the parts that detail
ga> older releases since they haven't yet reached EOL and there are people
ga> out there still using these. So we have to deal somehow with this
ga> situation. Fortunately, DocBook provides a mechanism, called
ga> profiling, which we could use. It would also be beneficial for later
ga> cleanup work since finding outdated information that has to do with
ga> unsupported releases always requires big effort. I've made a draft
ga> about how it could be done in a practical way:
ga> https://wiki.freebsd.org/VersionSpecificDocs
ga>
ga> Please read it and if you have doubts, concerns or better suggestions,
ga> please share them.

 I have no objection to use @os (or some other attrs) for conditional
 text, but it may need an attention that profiling feature of DocBook
 XSLT is exclusive, IIRC.  What I mean by "exclusive" is that it works
 for elements for each version like this:

 <para os="freebsd8" >8.X specific</para>
 <para os="freebsd9" >9.X specific</para>
 <para os="freebsd10">10.X specific</para>

 but we cannot write the common part like this:

 <para os="freebsd8 freebsd9">8.X and 9.X specific</para>
 <para os="freebsd10">10.X specific</para>

 In a past, I created and used a patch (for another project) to
 support multiple keywords and negation (condition="!print" for
 ignoring it only in printable formats) in an attr for profiling
 because some more flexibility was needed.  However, in this case
 there is another drawback that validation is not possible and a typo
 in the profiling attr, "freedsb8" for example, is silently ignored.

 There is no problem with marking a part of documents by using attrs
 as long as it is in a consistent way.

-- Hiroki
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 196 bytes
Desc: not available
URL: <http://lists.freebsd.org/pipermail/freebsd-doc/attachments/20130131/60ed5f89/attachment.sig>