docbook-apps

  • 1.  using xpointer with modular DocBook

    Posted 04-14-2013 18:08
    Hello,

    I'm trying to refactor a DocBook document a little, moving certain
    sections into an external document and xi:including them subsequently
    using xpointers.

    The document I want to refactor is a software API specification, where
    each definition contains a small section I'd like to move out into a
    separate ("meta-model") document. The resulting API document will thus
    contain hundrets of references to always the same external document,
    pulling in different nodes for the different definitions.

    The xinclude syntax I use right now looks like this:

    <variablelist>
    <xi:include href="../vsip/signal.xml"

    xpointer="xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:varlistentry[@xml:id='foo'])"/>
    ...
    </variablelist>

    This works well, but introduces a lot of redundancy as for each chunk
    I'd like to include I have to redefine the namespace used in the xpath
    expression. Is there a way to avoid that, by making this the default in
    some way ? If I just leave out the xmlns() I get an error as the
    xpointer can't be resolved.
    (I'm using xsltproc to process the DB documents.)

    Thanks for any help with this,

    Stefan

    --

    ...ich hab' noch einen Koffer in Berlin...




  • 2.  Re: [docbook-apps] using xpointer with modular DocBook

    Posted 04-14-2013 18:56
    Hello Stefan,

    Am Sonntag, 14. April 2013, 14:08:03 schrieb Stefan Seefeld:
    > [...]
    > <variablelist>
    > <xi:include href="../vsip/signal.xml"
    >
    > xpointer="xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:varlistentry[
    > @xml:id='foo'])"/> ...
    > </variablelist>

    If I'm not mistaken, you can simplify the above xpointer expression as

    xpointer(id(foo))

    Not sure if this scheme is supported, but it maybe worth a try. Maybe you need
    quotes for id(...) so try both notations.


    > This works well, but introduces a lot of redundancy as for each chunk
    > I'd like to include I have to redefine the namespace used in the xpath
    > expression. Is there a way to avoid that, by making this the default in
    > some way ? If I just leave out the xmlns() I get an error as the
    > xpointer can't be resolved.
    > (I'm using xsltproc to process the DB documents.)

    I don't think you can avoid the namespace. Have you tried entities? You could
    define a entity (let's say "dbxmlns") inside the internal subset of the DTD:

    [

    ]>

    and use it like this:

    <xi:include href="../vsip/signal.xml"
    xpointer="&dbxmlns;xpointer(id(foo))"/>

    Entites are resolved before any xinclude processing is done. If this works, I
    think this should be compact enough. ;)


    --
    Gruß/Regards
    Thomas Schraitle




  • 3.  Re: [docbook-apps] using xpointer with modular DocBook

    Posted 04-14-2013 19:09
    Hello Thomas,

    On 04/14/2013 02:56 PM, Thomas Schraitle wrote:
    > Hello Stefan,
    >
    > Am Sonntag, 14. April 2013, 14:08:03 schrieb Stefan Seefeld:
    >> [...]
    >> <variablelist>
    >> <xi:include href="../vsip/signal.xml"
    >>
    >> xpointer="xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:varlistentry[
    >> @xml:id='foo'])"/> ...
    >> </variablelist>
    > If I'm not mistaken, you can simplify the above xpointer expression as
    >
    > xpointer(id(foo))
    >
    > Not sure if this scheme is supported, but it maybe worth a try. Maybe you need
    > quotes for id(...) so try both notations.

    Yes, that works indeed. Unfortunately my real references are a little
    more complex, as they don't have (explicit) ids. So I typically need to
    refer to things such as "the first varlistentry child of the node with
    id <ID>".

    >> This works well, but introduces a lot of redundancy as for each chunk
    >> I'd like to include I have to redefine the namespace used in the xpath
    >> expression. Is there a way to avoid that, by making this the default in
    >> some way ? If I just leave out the xmlns() I get an error as the
    >> xpointer can't be resolved.
    >> (I'm using xsltproc to process the DB documents.)
    > I don't think you can avoid the namespace. Have you tried entities? You could
    > define a entity (let's say "dbxmlns") inside the internal subset of the DTD:
    >
    > > [
    >
    > ]>
    >
    > and use it like this:
    >
    > <xi:include href="../vsip/signal.xml"
    > xpointer="&dbxmlns;xpointer(id(foo))"/>
    >
    > Entites are resolved before any xinclude processing is done. If this works, I
    > think this should be compact enough. ;)

    Indeed, that works. Thanks for the tip !
    However, I'd rather prefer to avoid entities. The document will be
    edited with XML editors such as XMLMind's XXE, which would discard
    (substitute) the entities.
    (Of course, if everyone used such editors it wouldn't matter, but since
    some use normal text-based editors, I'm looking for a solution that
    works everywhere.

    Thanks again for your help,
    Stefan


    --

    ...ich hab' noch einen Koffer in Berlin...




  • 4.  Re: [docbook-apps] using xpointer with modular DocBook

    Posted 04-14-2013 19:25
    Hi Stefan,

    Am Sonntag, 14. April 2013, 15:09:07 schrieb Stefan Seefeld:
    > [...]
    > > If I'm not mistaken, you can simplify the above xpointer expression as
    > >
    > > xpointer(id(foo))
    > >
    > > Not sure if this scheme is supported, but it maybe worth a try. Maybe you
    > > need quotes for id(...) so try both notations.
    >
    > Yes, that works indeed. Unfortunately my real references are a little
    > more complex, as they don't have (explicit) ids. So I typically need to
    > refer to things such as "the first varlistentry child of the node with
    > id <ID>".

    I think that's also possible by just appending an XPath expression. If your
    variablelist has the ID "foo" and you want to refer to the first varlistentry
    you can write:

    xmlns(db=http://docbook.org/ns/docbook)xpointer(id(foo)/db:varlistentry[1])


    > > [... using entities ...]
    >
    > Indeed, that works. Thanks for the tip !
    > However, I'd rather prefer to avoid entities. The document will be
    > edited with XML editors such as XMLMind's XXE, which would discard
    > (substitute) the entities.

    That's true.


    > (Of course, if everyone used such editors it wouldn't matter, but since
    > some use normal text-based editors, I'm looking for a solution that
    > works everywhere.

    I don't think there is a general solution where you define somewhere the
    namespace and just refer to it. It seems, you need to add the namespace
    xmlns() scheme every time.

    Maybe you add the xmlns() XPointer scheme before passing it to your XML
    parser. You could (theoretically) apply an XSLT transformation step and add
    the xmlns() scheme. That way you could avoid entities, however, you add an
    additional step (which may not be useful).



    --
    Gruß/Regards
    Thomas Schraitle




  • 5.  Re: [docbook-apps] using xpointer with modular DocBook

    Posted 04-15-2013 00:07
    On 04/14/2013 03:24 PM, Thomas Schraitle wrote:
    > If your variablelist has the ID "foo" and you want to refer to the
    > first varlistentry you can write:
    > xmlns(db=http://docbook.org/ns/docbook)xpointer(id(foo)/db:varlistentry[1])


    Right, but that doesn't solve my problem of having to repeat the
    namespace declaration. :-)

    >> (Of course, if everyone used such editors it wouldn't matter, but since
    >> some use normal text-based editors, I'm looking for a solution that
    >> works everywhere.
    > I don't think there is a general solution where you define somewhere the
    > namespace and just refer to it. It seems, you need to add the namespace
    > xmlns() scheme every time.

    That's unfortunate. I was hoping there was a mechanism such as
    xmlns-local() to export the namespaces from the current document into
    the xpointer context.

    > Maybe you add the xmlns() XPointer scheme before passing it to your XML
    > parser. You could (theoretically) apply an XSLT transformation step and add
    > the xmlns() scheme. That way you could avoid entities, however, you add an
    > additional step (which may not be useful).

    I wouldn't mind the additional step, but I don't like the idea that the
    unprocessed document isn't valid any longer.

    Thanks,
    Stefan

    --

    ...ich hab' noch einen Koffer in Berlin...




  • 6.  Re: [docbook-apps] using xpointer with modular DocBook

    Posted 04-15-2013 07:14
    Hi Stefan,

    On Sun, 14 Apr 2013 20:06:45 -0400
    Stefan Seefeld <stefan@seefeld.name> wrote:

    > On 04/14/2013 03:24 PM, Thomas Schraitle wrote:
    > > If your variablelist has the ID "foo" and you want to refer to the
    > > first varlistentry you can write:
    > > xmlns(db=http://docbook.org/ns/docbook)xpointer(id(foo)/db:varlistentry[1])
    >
    > Right, but that doesn't solve my problem of having to repeat the
    > namespace declaration. :-)

    That's true. :-) I had mainly speed and simplification in mind than
    solving the namespace declaration. It could be slightly faster than
    using the descendant axis with //db:variablelist -- if supported by
    your favorite XML parser.


    > [...]
    > > I don't think there is a general solution where you define
    > > somewhere the namespace and just refer to it. It seems, you need to
    > > add the namespace xmlns() scheme every time.
    >
    > That's unfortunate. I was hoping there was a mechanism such as
    > xmlns-local() to export the namespaces from the current document into
    > the xpointer context.

    I could be wrong, but I haven't seen that. As some of the XPointer
    specification never reached recommendation status, I would doubt there
    is something like a xmlns-local().


    > > Maybe you add the xmlns() XPointer scheme before passing it to your
    > > XML parser. You could (theoretically) apply an XSLT transformation
    > > step and add the xmlns() scheme. That way you could avoid entities,
    > > however, you add an additional step (which may not be useful).
    >
    > I wouldn't mind the additional step, but I don't like the idea that
    > the unprocessed document isn't valid any longer.

    Right, that's unfortunate.

    Anyway, that reminds me of DocBook assemblies:

    http://docbook.org/tdg51/en/html/ch06.html

    It is a pretty new method of splitting your document into modules and
    referring to with a "map file" (named assembly). It may not help to
    solve your current situation, but it would be something for the future.
    As DocBook 5 is (or should be) the future, I think, this would be an
    interesting topic.

    However, it seems, the current implementation doesn't support
    "XML fragments" like referring to a certain element inside a XML file
    or using an XPath to select specific elements. It might be worth to
    bring this to the DocBook committee what they recommend in this case.

    I've opened a new thread on the docbook mailinglist (subject: "DocBook
    5 Assemblies and XML Fragments"). This is something I would like to
    know too. :))


    --
    Gruß/Regards,
    Thomas Schraitle