RFC: Dealing with version-specific docs

[Giorgos Keramidas]

On 2013-02-04 10:25, Gabor Kovesdan <gabor at FreeBSD.org> wrote:
>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 think it's a worthy goal to avoid the huge size of Java dependency for
a while, and I've seen that there are efforts to write alternatives to
tools like Saxon.  For example there was a time that I saw even xmlroff
being discussed for PDF output.  I don't recall right now if it was you,
Gabor, that brought xmlroff to my attention.

Modernizing the entire toolchain behind textproc/docproj is a large
project though.  It may require a great upfront investment of time and
effort.  So I'm not sure if it makes sense to gate other work on this
being completed first.

If we can do our work with the current tools, even if it means we have a
bit of duplication like the one you proposed, I think we should go for
this instead of going the Java way.  Then if we can find a PDF output
toolchain better than DSSSL (for values of 'better' like 'more modern',
'easier to grok', 'faster' or some other possibility) we can adapt the
tools later.

> 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.

XHTML is definitely a very bad option as an intermediate format for PDF
output.  PDF has all these typographically appealing capabilities that
we instantly lose just by going through XHTML.  It would make more sense
to transform docbook-xml to some other intermediate format, e.g. even
plain LaTeX, or even to explore the possibility of using ConTeXt for
XML->PDF output:

    http://wiki.contextgarden.net/XML

I admit I have only done very simple things with ConTeXt and XML, so
it's probably a wild idea.  I'm just mentioning it as a more
output-quality oriented way of producing PDF output, instead of losing
pretty much everything in an XHTML temporary stage.