RFC: Dealing with version-specific docs

[Warren Block]

On Mon, 28 Jan 2013, Gabor Kovesdan 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.

Conceptually, it's like an ifdef that defaults to on...

The redundancy between the os property and the text is a concern.  Is it 
possible to have the rendering handle that?

In other words:

<para os="freebsd8">To do foobar, type bar.</para>
<para os="freebsd9">To do foobar, type baz.</para>

Could render as:

   FreeBSD 8.X:
   +-------------------------+
   | To do foobar, type bar. |
   +-------------------------+

   FreeBSD 9.X:
   +-------------------------+
   | To do foobar, type baz. |
   +-------------------------+

Those could be in boxes or some other kind of visible mark, or maybe 
just in indented sections with titles.  If it is not necessary to repeat 
the version information in two forms, then it can't be out of sync.

Are there other projects that have done this and whose experience could 
be useful?