docbook: making an entity
Subject:
Re: making an entity
From:
"Martin A. Brown" ####@####.####
Date:
16 Jun 2003 21:15:38 -0000
Message-Id: <Pine.LNX.4.55.0306161544350.25980@enclitic.wonderfrog.net>
Hi there Emma,
How are you liking DocBook so far?
: I have a "note" that I'd like to appear in several different
: places. I know how to refer to the note (¬e-name;) but I'm not
: sure where I "store" the contents of the note.
There are two ways.
Internal Subset:
- - - - - - - - - - - - - - - - - - - -
You can create the entity as part of the internal document subset.
This is pretty easy, and looks like this:
<!DOCTYPE book PUBLIC
"-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY text "use this text instead" >
]>
And, of course, now you can use &text; in the content body anywhere.
I recommend using the second method if you intend on adding more
than a few entities, since it allows you to modularize the
documentation and entities into separate files.
External Subset:
- - - - - - - - - - - - - - - - - - - -
See my document source if you wish to see how I use parameter
entities to manage the content.....I define the parameter entity
%linux-ip-entities; [1], which I then include. This defines other
parameter entities and includes them....here's a snippet. This
means that you'd use multiple files--convenient for management and
collaboration.
<!DOCTYPE book PUBLIC
"-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY % linux-ip-entities SYSTEM "linux-ip.ent" >
%linux-ip-entities;
]>
: Also: is it considered good form to store only the text in the
: SGML entity, or should the entity also contain formatting. My
: note looks like this (the text itself is incomplete):
I don't think it's necessary to do this. I believe it is
necessary (although I don't know if XML/SGML parsers check for
this), you should include any ending tags for tags you begin
inside any general entity.
You can nest entities, too, which makes the following quite simple:
<!ENTITY kcompile
'<title>Additional kernel compiling information</title>
<para>For non-Debian instructions on how to compile your kernel
see <ulink url="">*another section</ulink>.
For more information on how to compile the kernel The Debian
Way please read <ulink
url="http://newbiedoc.sourceforge.net/system/kernel-pkg.html">Creating
custom kernels with Debian's** kernel-package system</ulink></para>'
>
* Some xslt processors (xsltproc, for example) will not see this ulink
tag as improper markup, although it's missing a required attribute, so
if you are using xsltproc, be prepared to watch it dump core unless you
have an URL in the url attribute.
** Note the use of ' in the word "Debian's". This prevents the ' from
being interpreted as the end of the quoted string.
<!ENTITY note-kcompile '<note>&kcompile;</note>' >
: So should my text have:
: <note>¬e-name;</note>
: or
: ¬e-name;
It's entirely up to you to decide which one seems more natural for you. I
generally try to include markup in the entity itself, especially since I am
essentially using the entities as macros.
I would also recommend the sagehill documentation on DocBook and XSLT [2],
if you haven't already found it.
[1] http://cvsview.tldp.org/index.cgi/LDP/guide/docbook/linux-ip/
http://cvsview.tldp.org/index.cgi/LDP/guide/docbook/linux-ip/linux-ip.xml?rev=1.11&content-type=text/vnd.viewcvs-markup
http://cvsview.tldp.org/index.cgi/LDP/guide/docbook/linux-ip/linux-ip.ent?rev=1.2&content-type=text/vnd.viewcvs-markup
[2] http://www.sagehill.net/xml/docbookxsl/ModularDoc.html#ModularEntities
