docbook-apps

  • 1.  validating and transforming a simple docbook5 file in fedora linux

    Posted 11-24-2009 12:30

    as a followup to my earlier post, to get started with both docbook5
    and relaxng, i wanted to figure out the basic commands to do that
    validation and transformation on my fedora 12 box using
    yum-installable f12 packages, so anyone is free to tell me if i'm
    making this more difficult than it has to be.

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

    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?

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

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

    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.

    $ xmlto html test.db5
    xmlto: /home/rpjday/docbook/test.db5 does not validate (status 3)
    xmlto: Fix document syntax or use --skip-validation option
    validity error : no DTD found!
    Document /home/rpjday/docbook/test.db5 does not validate

    $ xmlto --skip-validation html test.db5
    Note: namesp. cut : stripped namespace before processing My book title
    WARNING: cannot add @xml:base to node set root element. Relative paths may not work.
    Note: namesp. cut : processing stripped document My book title
    Writing index.html for book

    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.

    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?

    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.

    any comments on the above? simplifications? blatant oversights?

    rday

    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.

    --

    ========================================================================
    Robert P. J. Day Waterloo, Ontario, CANADA

    Linux Consulting, Training and Kernel Pedantry.

    Web page: http://crashcourse.ca
    Twitter: http://twitter.com/rpjday
    ========================================================================



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

    Posted 11-24-2009 14:10
    Am Dienstag, den 24.11.2009, 07:30 -0500 schrieb Robert P. J. Day:

    [..]
    > 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?

    Correct. However, please always use --noent (and maybe you want to use
    --noout). Otherwise you might miss bugs in entities. But that's just
    BTW.

    > $ xmllint --relaxng /usr/share/xml/docbook5/schema/rng/5.0/docbook.rng test.db5

    One word about xmllint here: Although I love it, it is not very useful
    for debugging RELAX NG schema based XML files. The error messages
    sometimes differ for the same issue depending on where the issue appears
    in the file. Sometimes the error messages are misleading or wrong - e.g.
    complaining about the attribute near to the buggy attribute. And there
    are some more issues.

    *IMHO* jing is much better for validation here and it outputs meaningful
    error messages.

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

    That is not correct. xmlto calls xmllint with --postvalid. This requires
    the presence of a DTD. You stumbled over a limitation of the xmlto
    script.

    > $ xmlto --skip-validation html test.db5
    > Note: namesp. cut : stripped namespace before processing My book title
    > WARNING: cannot add @xml:base to node set root element. Relative paths may not work.
    > Note: namesp. cut : processing stripped document My book title
    > Writing index.html for book

    Another limitation of xmlto. It hardcodes the path to the
    namespace-stripped stylesheets (docbook-xsl), which slows down the
    processing. To be honest: you can easily directly use xsltproc instead
    of xmlto. You can even add the stylesheet to the XML file:



    Regards, Daniel