Nested <!ENTITY> Tags?

Discussion in 'XML' started by Ed Dennison, Sep 11, 2003.

  1. Ed Dennison

    Ed Dennison Guest

    I'm starting to look at DocBook-XML (not SGML) for producing a large
    documentation set. The hierarchy of DocBook elements for organizing
    the content is (more or less);

    set
    book
    part
    chapter
    sect1
    sect2
    ....

    Most of the examples and documentation for DocBook-XML describe using
    <!ENTITY> tags within a DOCTYPE element to break up a book into
    multiple chapter files, like this:

    <!DOCTYPE book
    PUBLIC "-//OASIS//DTD DocBook XML V4.1//EN"
    "file:///c:\home\db\dtd\docbookx.dtd"
    [
    <!ENTITY preface SYSTEM "userguide.preface.xml" >
    <!ENTITY ch1 SYSTEM "userguide.ch1.xml" >
    <!ENTITY ch2 SYSTEM "userguide.ch2.xml" >
    ]
    >


    <book>
    &preface;
    &ch1;
    &ch2;
    </book>

    This works fine. But suppose I would like to include my books within a
    set. If I do something similar in a set container file:

    <!DOCTYPE set
    PUBLIC "-//OASIS//DTD DocBook XML V4.1//EN"
    "file:///c:\home\db\dtd\docbookx.dtd"
    [
    <!ENTITY userguide SYSTEM "userguide.book.xml" >
    <!ENTITY reference SYSTEM "reference.book.xml" >
    ]
    >


    <set>
    &userguide;
    &reference;
    </set>

    This does not work fine -- attempting to parse the set file generates
    errors because of multiple DOCTYPE elements in a single file (the
    DOCTYPE elements in the included book XML files).

    As far as I can tell, this means that if I want to use the set
    element, each of my DocBook books must be implemented as a single XML
    file. This is not practical for large books (such as N. Walsh's
    example of an aircraft maintenance manual).

    I am interested in what kinds of approaches people take when using
    DocBook-XML to work with large documentation sets? Do you eschew the
    use of the set element? Use some kind of mechanical means to merge the
    parts of a book before processing?

    Thanks,

    Ed Dennison
    Cognex Corporation

    e-mail ed at the obvious domain.
    Ed Dennison, Sep 11, 2003
    #1
    1. Advertising

  2. In article <>,
    Ed Dennison <> wrote:

    ><!DOCTYPE book
    > PUBLIC "-//OASIS//DTD DocBook XML V4.1//EN"
    > "file:///c:\home\db\dtd\docbookx.dtd"
    > [
    > <!ENTITY preface SYSTEM "userguide.preface.xml" >
    > <!ENTITY ch1 SYSTEM "userguide.ch1.xml" >
    > <!ENTITY ch2 SYSTEM "userguide.ch2.xml" >
    > ]
    > >

    >
    ><book>
    > &preface;
    > &ch1;
    > &ch2;
    ></book>


    First of all, note that you could have split out the chapter entity
    definitions into an external parameter entity, and used another
    external entity to package up all the chapters:

    userguide-defs.pe:

    <!ENTITY preface SYSTEM "userguide.preface.xml" >
    <!ENTITY ch1 SYSTEM "userguide.ch1.xml" >
    <!ENTITY ch2 SYSTEM "userguide.ch2.xml" >
    <!ENTITY userguide-chapters SYSTEM "userguide-chapters.xml">

    userguide-chapters.xml:

    &preface;
    &ch1;
    &ch2;

    userguide.xml:

    <!DOCTYPE book
    PUBLIC "-//OASIS//DTD DocBook XML V4.1//EN"
    "file:///c:\home\db\dtd\docbookx.dtd"
    [
    <!ENTITY % userguide-defs SYSTEM "userguide-defs.pe" >
    %userguide-defs;
    ]
    >

    <book>
    &userguide-chapters;
    </book>

    Then you could do this:

    <!DOCTYPE set
    PUBLIC "-//OASIS//DTD DocBook XML V4.1//EN"
    "file:///c:\home\db\dtd\docbookx.dtd"
    [
    <!ENTITY % userguide-defs SYSTEM "userguide-defs.pe" >
    %userguide-defs;
    <!ENTITY % reference-defs SYSTEM "reference-defs.pe" >
    %reference-defs;
    ]
    >


    <set>
    <book>
    &userguide-chapters;
    </book>
    <book>
    &reference-chapters;
    </book>
    </set>

    Still rather more overhead than is desirable, but maybe good enough.

    (NB you will have to choose different entity names for the chapters
    in each book.)

    -- Richard
    --
    Spam filter: to mail me from a .com/.net site, put my surname in the headers.

    FreeBSD rules!
    Richard Tobin, Sep 12, 2003
    #2
    1. Advertising

  3. "Ed Dennison" <> wrote in message
    news:...


    --snip--


    > I am interested in what kinds of approaches people take when using
    > DocBook-XML to work with large documentation sets? Do you eschew the
    > use of the set element? Use some kind of mechanical means to merge the
    > parts of a book before processing?



    --snip--

    Chapter 19 [http://www.sagehill.net/docbookxsl/ModularDoc.html] in 'DocBook
    XSL: The Complete Guide' [http://www.sagehill.net/docbookxsl/] has some
    pretty good advice for working with modular DocBook files. Assuming you are
    processing your sources with N. Walsh's styulesheets.


    // Magnus
    Magnus Henriksson, Sep 17, 2003
    #3
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Dean H. Saxe
    Replies:
    0
    Views:
    1,023
    Dean H. Saxe
    Jan 3, 2004
  2. Ed Dennison
    Replies:
    0
    Views:
    460
    Ed Dennison
    Sep 12, 2003
  3. Samuel van Laere

    Entity Name or Entity Number?

    Samuel van Laere, Feb 24, 2007, in forum: HTML
    Replies:
    4
    Views:
    1,617
    Jukka K. Korpela
    Feb 24, 2007
  4. markla
    Replies:
    1
    Views:
    540
    Steven Cheng
    Oct 6, 2008
  5. Norm
    Replies:
    3
    Views:
    2,699
Loading...

Share This Page