[PATCH xorg-docs 2/2] Replace XMLTO with XSLTPROC, XMLLINT and W3M tools

[Gaetan Nadon]

On Tue, 2011-03-22 at 14:25 -0700, Dan Nicholson wrote:

> If you pass -x to xmlto instead of -m, you can use a full stylesheet
> instead of a fragment. Moving to xsltproc means you have to duplicate
> the internal smarts of xmlto.
> 

I have verified -x works as described. This removes one issue with
xmlto. I would be happy with it if we were simply generating docs. But
other issues remain.

Generating target dbs. It is more difficult with xmlto. It resolves
around the fact that we just need an xsl for html and one for fo. Xmlto
runs 4 times, one for each format. The html xsl is used for html and
text while the fo xsl is used for pdf and ps.

If I generate the target dbs while generating the doc, I end up with too
may files, incorrect extensions and dealing with one tool producing
multiple outpouts.

If I generate the target dbs on their own, I end up with an extra pdf
file which overwrites the previously generated pdf for the fo format.
Xmlto fails when collect.xref.targets="only" as it expects the doc
in /tmp to be there.

As for the "internal smarts" of xmlto, this is it:

        case "$1" in
        stylesheet)
          if [ "$VERBOSE" -ge 1 ]
          then
            echo >&2 "Convert to HTML (no chunks)"
          fi
          echo "http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl"
          ;;
        post-process)
          ${GCP_PATH:-cp} -R -P -p -- "$XSLT_PROCESSED" "$OUTPUT_DIR/$(basename "${XSLT_PROCESSED%.*}").html"
          ;;
        esac



I have implemented all permutations of using xmlto/xsltproc for docs and
target dbs with docs and standalone. Xmlto is convenient for a vanilla
scenario and more so if you have to deal with multiple backends
xsltproc/xerces/xalan or passivetex/fop. For what I remember, xerces and
xalan don't support xinclude, and passivetex never worked. I am under
the impression that all platforms we support have xsltproc and fop.

That leaves the text format. The w3m tool is available on all platforms
we support. If any distro has a reason not to use this tool, they should
speak up. If a distro does not have this tool, links/lynx could be used.
A macro to select the tool can be written as we do for lint.

I looked at the Apache docs and their build tools which are "ant" based.
They use xsltproc directly and they have no text format. They use olonk
and target dbs.

My choice is xsltproc due to target dbs. Otherwise xmlto would be fine.
If there is a backend issue (say no xsltproc), then the whole exercise
of external references would be have to be dropped.


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.x.org/archives/xorg-devel/attachments/20110323/8cef08d6/attachment.htm>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 197 bytes
Desc: This is a digitally signed message part
URL: <http://lists.x.org/archives/xorg-devel/attachments/20110323/8cef08d6/attachment.pgp>