[CALL FOR REVIEW] doc and www converted to XML

[Warren Block]

On Tue, 21 Aug 2012, Gabor Kovesdan wrote:

> Em 21-08-2012 00:46, Warren Block escreveu:
>> First, a question: will the .sgml filenames be changed to .xml?
>
> Yes but maintaining a branch with full of renamed files is more messy
> than later renaming them in head. Probably we'll lock the tree for a
> very short time and do a bunch rename.
>
>> Second, a note on related software: a couple of days ago, Steve Wills
>> was gracious enough to make a port of Publican.  Publican is the RedHat
>> doc tool, which takes XML DocBook 4.5 and renders them to HTML or PDF or
>> other formats.  It has support for .po and .pot translation files.  I
>> have not given it a serious test, but it may be useful now that we have
>> XML files.
>
> What benefits does it give us over directly calling the underlying
> tools? I see it uses XSLT to render HTML and it relies on FOP for PDF.
> This can be done with slight modifications of our Makefiles. Is it worth
> adding one more layer? It would mean more vendor dependency and
> performance penalty. From the documentation, my first impression is that
> it also introduces lots of proprietary things: directory layout, config
> files, commands and command-line parameters. [1] I think you can achieve
> the same things by our simple Makefile macros and direct editing of the
> XML files, which is not a high expectation towards doc committers but
> requiring to learn a totally proprietary system may not be that welcome.

Agreed.  I think the primary benefit would be taking advantage of a 
toolchain that someone else maintains.  I don't know how well it would 
work for us.  The nice thing is that with DocBook XML, the choice 
becomes available.

> Anyway, FOP is the best free renderer out for PDF but it depends on
> Java. Publican also uses FOP. Personally, I think we should get a
> compromise and depend on Java or otherwise we never will have modern
> features and outlook in our PDF documents.

With OpenJDK, Java is a lot less of a hassle than previously.

> But some people will object so if we want quality we will have to 
> convince them whether we use Publican or not.
>
> [1]
> http://jfearn.fedorapeople.org/en-US/Publican/2.7/html/Users_Guide/chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Files_in_the_book_directory
>
> [2] https://fedorahosted.org/publican/wiki/Installing
>
> Gabor
>