docbook-apps

Re: [docbook-apps] validating and transforming a simple docbook5 file in fedora linux

  • 1.  Re: [docbook-apps] validating and transforming a simple docbook5 file in fedora linux

    Posted 11-24-2009 13:40
    Hi Robert,

    > [... intro pruned ...]
    >
    > first, here's my incredibly trivial test.db5:
    >
    >
    > <book xmlns="http://docbook.org/ns/docbook" version="5.0">
    > <info>
    >
    > <subtitle>My subtitle</subtitle>
    > </info>
    > </book>
    >
    > so far, so good?

    It seems valid. :-)


    > and, based on my reading so far (just getting
    > started), there's nothing i can add to associate that file with a
    > particular relaxng schema is there? equivalent to a DTD
    > specification?

    Right, there is no DOCTYPE, namespace, or anything similar for
    RELAX NG.
    Some tools insert a processing instruction (like the oXygen XML
    editor) but as far as I know, it is not a common procedure.


    > next, i can dig into my docbook5-schemas package to see the files:
    > ...
    > /usr/share/xml/docbook5/schema/rng
    > /usr/share/xml/docbook5/schema/rng/5.0
    > /usr/share/xml/docbook5/schema/rng/5.0/catalog.xml
    > /usr/share/xml/docbook5/schema/rng/5.0/docbook.rnc
    > /usr/share/xml/docbook5/schema/rng/5.0/docbook.rng
    > /usr/share/xml/docbook5/schema/rng/5.0/docbookxi.rnc
    > /usr/share/xml/docbook5/schema/rng/5.0/docbookxi.rng
    > ...
    >
    > if i just want to validate that file against the relaxng schema with
    > xmllint, i have to *explicitly* list the schema file as follows,
    > correct?

    Yes, that's correct.


    > $ xmllint --relaxng /usr/share/xml/docbook5/schema/rng/5.0/docbook.rng test.db5
    >
    > <book xmlns="http://docbook.org/ns/docbook" version="5.0">
    > <info>
    >
    > <subtitle>My subtitle</subtitle>
    > </info>
    > </book>
    > test.db5 validates

    I'm not sure about the RELAX NG support in xmllint. Last time I
    tried to validate a DocBook5 document with xmllint I had some
    problems. Maybe your file is a very simple case for xmllint.

    For this reason, check your documents with Jing too.


    > any shortcuts for that? as in (like i asked before) incorporating a
    > reference to the schema in the file itself?

    Not that I'm aware of any. (Of course, you can always "invent" some
    magic with processing instruction or the like, but I skip this.)


    > and finally, to generate the HTML, i can use the handy-dandy "xmlto"
    > utility but i have to explicitly skip validation since the underlying
    > xsltproc program that will be called can't validate relaxng.
    >
    > [...]

    I would call/run xsltproc directly.


    > and that seems to work. so, to summarize (and let me know if i'm
    > out to lunch here):
    >
    > 1) my test.db5 file is an adequate example of docbook5 input.

    Yes, it's correct.


    > 2) if i want to validate against a relaxng schema with xmllint, i
    > *must* explicitly do it as i did above, since db5 doesn't support(?)
    > adding an internal reference to that kind of schema, correct?

    It is not DocBook5, it is a "concept" from RELAX NG.


    > 3) at this time, actual processing utilities may not have relaxng
    > support so it's wise to separate the validation step from the
    > processing step, as i did above.

    With "processing step" you mean transformation?
    In that case, it is not a matter of wise or not. Normally you do
    (or should do) always validation and after this step, you transform
    your document. A tool could combine these steps (and some actually do),
    but internally, it works this way (first validation, second transformation).


    > any comments on the above? simplifications? blatant oversights?

    It makes sense. :) I would recommend to write a Makefile to simplify
    your tasks. Normally this makes it easier: you don't have to memorize
    all the command line tools and options. ;)


    > p.s. for no good reason, i want to clarify these steps so i can write
    > a one-page wiki entry on how to get started playing with docbook5 on
    > fedora linux.

    Sounds good. :-)


    Tom