Skip site navigation (1)Skip section navigation (2)
Date:      Tue, 21 Aug 2012 01:14:06 +0200
From:      Gabor Kovesdan <gabor@FreeBSD.org>
To:        Warren Block <wblock@wonkity.com>
Cc:        doceng@freebsd.org, doc@freebsd.org, www@freebsd.org
Subject:   Re: [CALL FOR REVIEW] doc and www converted to XML
Message-ID:  <5032C4BE.5080209@FreeBSD.org>
In-Reply-To: <alpine.BSF.2.00.1208201640430.84148@wonkity.com>
References:  <50326A70.5020009@FreeBSD.org> <alpine.BSF.2.00.1208201640430.84148@wonkity.com>

next in thread | previous in thread | raw e-mail | index | archive | help
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.

The translation support would be interesting but first we should
evaluate if such a method is appropriate for us (having a small demo
would be nice with a sample source and a sample translation file) and if
so, we can very well "extract" the way it is done in Publican without
having to adopt the whole system with the complexities and lots of
dependencies. [2]

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



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?5032C4BE.5080209>