RFC: Dealing with version-specific docs

[Gabor Kovesdan]

Em 04-02-2013 05:17, Giorgos Keramidas escreveu:
> 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?
Theoretically, we could render the marked sections differently and then 
it would not require duplicated information. But in practice, this 
requires heavy customization of our build process. We have to customize 
different things:

- The XSLT stylesheets used for XHTML output. This is quite easy, I can 
do it without problems.
- Either we keep using Jade for PS/PDF generation and then we have to 
customize the DSSSL stylesheets. DSSSL is a dead and badly documented 
standard and I practically don't know anything about it so we need to 
find someone, who is willing to do it. It is not easy because it never 
became widely used and there is no free reference or documentation about 
it. It also raises the question whether it is worth investing time and 
effort in something that is so outdated.
- Or we allow Java dependency just for the printed output formats (XHTML 
would still be generated without Java) and then we need to do the 
customizations in XSLT/XSL FO, which is much easier and I can do it myself.

I mentioned these problems at EuroBSDCon but people were quite reluctant 
about the Java dependency even though the XHTML part would still work 
without Java. I think that I have to raise this issue again. I've been 
working on improving the doc tree to use up to date and better standards 
than the earlier ones and now I have a branch with some important 
updates. I've maintained compatibility with Jade but sooner or later 
we'll have to move away from it. The trivial way is using Fop (a 
Java-based XSL FO renderer), which all other open source projects do 
that use XML-based documentation. Some people suggested generating PDF 
from XHTML which imho is a bad option since XHTML is not a 
paper-oriented markup so we loose features in that way, so I don't 
believe in its success and I'm not really willing to work on botches. 
Now I'll bring the tree technologically up to date until the point where 
we can avoid Java but then we will have to choose how to go beyond.

Gabor