docbook: Thread: making an entity

I have a "note" that I'd like to appear in several different places. I
know how to refer to the note (&note-name;) but I'm not sure where I
"store" the contents of the note.

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):

<note>
<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>
</note>

So should my text have:
	<note>&note-name;</note>
or
	&note-name;

thanks :)

-- 
Emma Jane Hogbin
[[ 416 417 2868 ][ www.xtrinsic.com ]]

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 (&note-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&apos;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 &apos; 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>&note-name;</note>
 : or
 : 	&note-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

On Mon, Jun 16, 2003 at 04:15:58PM -0500, Martin A. Brown wrote:
> How are you liking DocBook so far?

It's very verbose. :) On the one hand I love it because the markup exactly
describes what I'm doing with the text. But I also hate it because I have
to figure out what the appropriate tags are for *everything*.

> Internal Subset:

I've used this one for now. As far as I know there's only the only block of
text that is repeated more than once. Plus this method is much easier to
wrap my head around. ;) I adjusted the url="" to be url='' and then 
changed the text apostrophe to an entity.

> this), you should include any ending tags for tags you begin
> inside any general entity.

Yup.

> *  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.

Ok. I doubt I'll try to validate it before I have that text re-written.
I'm still trying to figure out where that text ought to go. It's currently
at the end of the document and I'm about 1/3 of the way through.

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

Since both instances are notes, I've decided to include the <note> as part
of the entity. If I ever have something that could be a note or a warning
(for example) then I might do things differently.

> I would also recommend the sagehill documentation on DocBook and XSLT [2],
> if you haven't already found it.

I had but I'd glossed over it since it seemed to be entirely about
converting files once the SGML file is finished.

thanks for your help :)

emma

-- 
Emma Jane Hogbin
[[ 416 417 2868 ][ www.xtrinsic.com ]]