LDP
/
LDP
mirror of https://github.com/tLDP/LDP
0
1
Fork 0
Code Releases Activity

Added some emails from -discuss on why <section> and <sectN> are 

different. I have notified the authors of hte original emails that
their emails have been included in the Author Guide. They have been
given credit in the section of the document as well.
This commit is contained in:
emmajane 2003-12-07 23:16:44 +00:00
parent aa6642061c
commit 14fe593873
1 changed files with 399 additions and 358 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

757
LDP/guide/docbook/LDP-Author-Guide/using-docbook.xml
View File

@ -455,84 +455,148 @@ class="starttag">xref linkend="secao" /</sgmltag> for more information.</program
</section>
<section id="section">
<title>section and sectN: what's the difference?</title>
<note><para>
These notes were provided by:
<ulink url="http://geekhavoc.com">John Daily</ulink> and
Saqib Ali (<email>saqib@seagate.com</email>).
</para></note>
<para>
<sgmltag>section</sgmltag> vs <sgmltag>sectN</sgmltag> is largely a
question of flexibility. The stylesheets can make a
<sgmltag>section</sgmltag> in a <sgmltag>section</sgmltag> look just
like a <sgmltag>sect2</sgmltag> within a <sgmltag>sect1</sgmltag>, so there's no output advantage.
</para>
<para>
But, a <sgmltag>section</sgmltag> within a
<sgmltag>section</sgmltag> can be extracted into its own
top-level section, nested even more deeply, or moved to an
entirely different part of the document, without it and its own
<sgmltag>section</sgmltag> children being renamed. That is not true of the
numbered section tags, which are very sensitive to
rearrangements. This can be easier for authors who are new to
DocBook than using <sgmltag>sectN</sgmltag>.
</para>
<para>
The main idea behind creating structured data is that should be easy
to access and query. One should be able to retrieve a subsection of any
structured data, by using querying languages for XML (XPath and XQuery).
<sgmltag>sectN</sgmltag> are useful when traversing a document using XPath/XQuery.
<sgmltag>sectN</sgmltag> gives more flexibility, and control while writting a XPath
expression.
</para>
<para>
A well-defined, valid and well-structured documents make it easier for
one to write XPath/Query to retreive "specific" data from a document.
For example you can use XPath to retrieve information in the
<sgmltag>sect3</sgmltag> block with certain attributes.
However if you just used <sgmltag>section</sgmltag> for all subsection,
it becomes harder to retrieve the block of information that you need.
</para>
<para>
So which one should you use? The one you feel most
comfortable with is a good place to start. This document
is written with <sgmltag>section</sgmltag>s. You may,
or may not, think this is a good idea. :)
</para>
</section> <!-- section and sectN -->
<section id="encoding-index">
<title>Encoding Indexes</title>
<indexterm zone="encoding-index">
<primary>edition</primary>
<secondary>index</secondary>
<indexterm zone="encoding-index">
<primary>edition</primary> <secondary>index</secondary>
</indexterm>
<para>The generation of indexes depends on the markups inserted in
the text.</para>
<para>Such markups will be processed afterwords by an external tool and
will generate the index. An example of such a tool is the
<filename>collateindex.pl</filename> script (see <xref
linkend="tools-compile"/>). Details about the process used to generate
these indexes are shown in <xref linkend="automatic-indexes"/>.</para>
<para>Such markups will be processed afterwords by an external
tool and will generate the index. An example of such a
tool is the <filename>collateindex.pl</filename> script
(see <xref linkend="tools-compile"/>). Details about the
process used to generate these indexes are shown in <xref
linkend="automatic-indexes"/>.</para>
<para>The indexes have nesting levels. The markup of an index is done by the
code <xref
linkend="example-code-index"/>.</para>
<para>The indexes have nesting levels. The markup of an index is
done by the code <xref linkend="example-code-index"/>.</para>
<example id="example-code-index">
<title>Code for the generation of an index</title>
<programlisting>
<title>Code for the generation of an index</title> <programlisting>
<sgmltag class="starttag">indexterm</sgmltag>
<sgmltag class="starttag">primary</sgmltag>Main level<sgmltag class="endtag">primary</sgmltag>
<sgmltag class="starttag">secondary</sgmltag>Second level<sgmltag class="endtag">secondary</sgmltag>
<sgmltag class="starttag">tertiary</sgmltag>Third level<sgmltag class="endtag">tertiary</sgmltag>
<sgmltag class="starttag">primary</sgmltag>Main
level<sgmltag class="endtag">primary</sgmltag>
<sgmltag class="starttag">secondary</sgmltag>Second
level<sgmltag class="endtag">secondary</sgmltag> <sgmltag
class="starttag">tertiary</sgmltag>Third level<sgmltag
class="endtag">tertiary</sgmltag>
<sgmltag class="endtag">indexterm</sgmltag>
</programlisting>
</example>
<para>It is possible to refer to chapters, sections, and other parts
of the document using the <glossterm>attribute</glossterm> <sgmltag
class="attribute">zone</sgmltag>.</para>
<para>It is possible to refer to chapters, sections, and other
parts of the document using the <glossterm>attribute</glossterm>
<sgmltag class="attribute">zone</sgmltag>.</para>
<example id="index-zone">
<title>Use of the attribute <sgmltag class="attribute">zone</sgmltag></title>
<programlisting>
<title>Use of the attribute <sgmltag
class="attribute">zone</sgmltag></title> <programlisting>
<sgmltag class="starttag">section id="encoding-index"</sgmltag>
<sgmltag class="starttag">title</sgmltag>Encoding Indexes<sgmltag class="endtag">title</sgmltag>
<sgmltag class="starttag">title</sgmltag>Encoding Indexes<sgmltag
class="endtag">title</sgmltag>
<sgmltag class="starttag">indexterm zone="encoding-index"</sgmltag>
<sgmltag class="starttag">primary</sgmltag>edition<sgmltag class="endtag">primary</sgmltag>
<sgmltag class="starttag">secondary</sgmltag>index<sgmltag class="endtag">secondary</sgmltag>
<sgmltag class="starttag">primary</sgmltag>edition<sgmltag
class="endtag">primary</sgmltag> <sgmltag
class="starttag">secondary</sgmltag>index<sgmltag
class="endtag">secondary</sgmltag>
<sgmltag class="endtag">indexterm</sgmltag>
<sgmltag class="starttag">para</sgmltag>The generation of indexes depend on the inserted markups on the text. <sgmltag class="endtag">para</sgmltag>
<sgmltag class="starttag">para</sgmltag>The generation of
indexes depend on the inserted markups on the text. <sgmltag
class="endtag">para</sgmltag>
</programlisting>
</example>
<para>The <xref linkend="index-zone"/> has the code used to generate the
entry of this edition on the index. In fact, since the attribute
<sgmltag class="attribute">zone</sgmltag> is used, the index statement
could be located anywhere in the document or even in a separate file.
</para>
<para>The <xref linkend="index-zone"/> has the code used to
generate the entry of this edition on the index. In fact, since
the attribute <sgmltag class="attribute">zone</sgmltag> is used,
the index statement could be located anywhere in the document or
even in a separate file. </para>
<para>However, to facilitate maintenance the entries for the index were all
placed after the text to which it refers.
</para>
<para>However, to facilitate maintenance the entries for the index
were all placed after the text to which it refers. </para>
<example>
<title>Usage of values <sgmltag class="attvalue">startofrange</sgmltag> and
<sgmltag class="attvalue">endofrange</sgmltag> on the attribute<sgmltag
class="attribute">class</sgmltag></title>
<programlisting>
<sgmltag class="starttag">para</sgmltag>Typing the text normally sometimes there's the need of
<sgmltag class="starttag">indexterm class="startofrange" id="example-band-index"</sgmltag>
<sgmltag class="starttag">primary</sgmltag>examples<sgmltag class="endtag">primary</sgmltag>
<sgmltag class="starttag">secondary</sgmltag>index<sgmltag class="endtag">secondary</sgmltag>
<sgmltag class="endtag">indexterm</sgmltag>
mark large amounts of text.<sgmltag class="endtag">para</sgmltag>
<title>Usage of values <sgmltag
class="attvalue">startofrange</sgmltag> and <sgmltag
class="attvalue">endofrange</sgmltag> on the attribute<sgmltag
class="attribute">class</sgmltag></title> <programlisting>
<sgmltag class="starttag">para</sgmltag>Typing the text normally
sometimes there's the need of
<sgmltag class="starttag">indexterm class="startofrange"
id="example-band-index"</sgmltag>
<sgmltag class="starttag">primary</sgmltag>examples<sgmltag
class="endtag">primary</sgmltag> <sgmltag
class="starttag">secondary</sgmltag>index<sgmltag
class="endtag">secondary</sgmltag>
<sgmltag class="endtag">indexterm</sgmltag> mark large amounts of
text.<sgmltag class="endtag">para</sgmltag>
<sgmltag class="starttag">para</sgmltag>Keep inserting the paragraphs normally.<sgmltag class="endtag">para</sgmltag>
<sgmltag class="starttag">para</sgmltag>Keep inserting the paragraphs
normally.<sgmltag class="endtag">para</sgmltag>
<sgmltag class="starttag">para</sgmltag>Until the end of the section intended
to be indexed.
<sgmltag class="starttag">indexterm startref="example-band-index" class="endofrange"</sgmltag>.
<sgmltag class="starttag">para</sgmltag>Until the end of the section
intended to be indexed. <sgmltag class="starttag">indexterm
startref="example-band-index" class="endofrange"</sgmltag>.
<sgmltag class="endtag">para</sgmltag></programlisting>
</example>
@ -542,13 +606,10 @@ class="starttag">xref linkend="secao" /</sgmltag> for more information.</program
<title>Inserting Pictures</title>
<indexterm zone="inserting-pictures">
<primary>graphics</primary>
<secondary>inserting</secondary>
<primary>graphics</primary> <secondary>inserting</secondary>
<tertiary><sgmltag class="starttag">graphic</sgmltag></tertiary>
</indexterm>
<indexterm zone="inserting-pictures">
<primary>figures</primary>
<secondary>inserting</secondary>
</indexterm> <indexterm zone="inserting-pictures">
<primary>figures</primary> <secondary>inserting</secondary>
<tertiary><sgmltag class="starttag">figure</sgmltag></tertiary>
</indexterm>
@ -556,146 +617,138 @@ class="starttag">xref linkend="secao" /</sgmltag> for more information.</program
<para>It is necessary to insert pictures for all media the
document will be published for.</para>
<para>If you use the TeX format you'll need the images as a
PostScript file. For on-line publishing you can use any kind of
common image file, such as <acronym>JPG</acronym>,
<acronym>GIF</acronym> or <acronym>PNG</acronym>.</para>
<para>If you use the TeX format you'll need the images as
a PostScript file. For on-line publishing you can use any
kind of common image file, such as <acronym>JPG</acronym>,
<acronym>GIF</acronym> or <acronym>PNG</acronym>.</para>
<para>
The easiest way to insert pictures is to use the
<sgmltag class="attribute">fileref</sgmltag> attribute. Usually
pictures are generated
in <acronym>JPG</acronym> and in PostScript (PS or EPS).
The easiest way to insert pictures is to use the <sgmltag
class="attribute">fileref</sgmltag> attribute. Usually pictures are
generated in <acronym>JPG</acronym> and in PostScript (PS or EPS).
</para>
<example id="ex-picture-fileref">
<title>Inserting a picture</title>
<programlisting>
<title>Inserting a picture</title> <programlisting>
<sgmltag class="starttag">figure</sgmltag>
<sgmltag class="starttag">title</sgmltag>Picture's Title<sgmltag class="endtag">title</sgmltag>
<sgmltag class="starttag">graphic fileref="images/file"</sgmltag><sgmltag class="endtag">graphic</sgmltag>
<sgmltag class="endtag">figure</sgmltag>
</programlisting>
<sgmltag class="starttag">title</sgmltag>Picture's
Title<sgmltag class="endtag">title</sgmltag> <sgmltag
class="starttag">graphic fileref="images/file"</sgmltag><sgmltag
class="endtag">graphic</sgmltag>
<sgmltag class="endtag">figure</sgmltag> </programlisting>
</example>
<para>Replacing <sgmltag class="starttag">figure</sgmltag> by
<sgmltag class="starttag">informalfigure</sgmltag> eliminates the need to
insert a title for the picture.</para>
<sgmltag class="starttag">informalfigure</sgmltag> eliminates the
need to insert a title for the picture.</para>
<para>There's still the <sgmltag class="attribute">float</sgmltag>
attribute on which the value <literal>0</literal> indicates that the
picture should be placed exactly where the tag appears. The
value <literal>1</literal> allows the picture to be moved to a more
convenient location (this location can be described on the style
sheet used or even can be controlled by the application being
used).</para>
attribute on which the value <literal>0</literal> indicates that
the picture should be placed exactly where the tag appears. The
value <literal>1</literal> allows the picture to be moved to a
more convenient location (this location can be described on the
style sheet used or even can be controlled by the application
being used).</para>
<section id="acceptedgfx">
<title>Graphics formats</title>
<para> When submitting graphics to the LDP, please submit one
set of graphics in <filename>.eps</filename>, and another in
<filename moreinfo="none">.gif</filename>, <filename
moreinfo="none">.jpg</filename> or <filename moreinfo="none">
.png</filename>. The preferred format is <filename moreinfo="none">
.png</filename> or <filename moreinfo="none">.jpg</filename> due to
patent problems with <filename moreinfo="none">.gif</filename>.
</para>
<para>
<title>Graphics formats</title> <para> When
submitting graphics to the LDP, please submit one
set of graphics in <filename>.eps</filename>, and
another in <filename moreinfo="none">.gif</filename>,
<filename moreinfo="none">.jpg</filename> or <filename
moreinfo="none"> .png</filename>. The preferred format is
<filename moreinfo="none"> .png</filename> or <filename
moreinfo="none">.jpg</filename> due to patent problems with
<filename moreinfo="none">.gif</filename>. </para> <para>
You can use <filename moreinfo="none">.jpg</filename> file for
continuous-tone images such as photos or images with gradual
changes in color. Use <filename moreinfo="none">.png</filename>
for simple images like diagrams, some screen shots, and images
with a low number of colors.
</para>
with a low number of colors. </para>
</section>
<section id="inserting-figures-mediaobject">
<title>Alternative Methods</title>
<indexterm zone="inserting-figures-mediaobject">
<primary>graphics</primary>
<secondary>inserting</secondary>
<tertiary><sgmltag class="starttag">mediaobject</sgmltag></tertiary>
</indexterm>
<indexterm zone="inserting-figures-mediaobject">
<primary>figures</primary>
<secondary>inserting</secondary>
<tertiary><sgmltag class="starttag">mediaobject</sgmltag></tertiary>
<primary>graphics</primary>
<secondary>inserting</secondary> <tertiary><sgmltag
class="starttag">mediaobject</sgmltag></tertiary>
</indexterm> <indexterm zone="inserting-figures-mediaobject">
<primary>figures</primary>
<secondary>inserting</secondary> <tertiary><sgmltag
class="starttag">mediaobject</sgmltag></tertiary>
</indexterm>
<para>The first alternative to <xref linkend="ex-picture-fileref"/> is
to eliminate the <sgmltag class="starttag">figure</sgmltag> or
<para>The first alternative to <xref linkend="ex-picture-fileref"/>
is to eliminate the <sgmltag class="starttag">figure</sgmltag> or
<sgmltag class="starttag">informalfigure</sgmltag> elements.</para>
<para>Another interesting alternative when you have decided to publish
the text on media where pictures are not accepted, is the use of a
wrapper, <sgmltag class="starttag">imageobject</sgmltag>.</para>
<para>Another interesting alternative when you have
decided to publish the text on media where pictures
are not accepted, is the use of a wrapper, <sgmltag
class="starttag">imageobject</sgmltag>.</para>
<example id="former-figure-imageobject">
<title>Using <sgmltag class="starttag">imageobject</sgmltag></title>
<programlisting>
<title>Using <sgmltag
class="starttag">imageobject</sgmltag></title> <programlisting>
<sgmltag class="starttag">figure</sgmltag>
<sgmltag class="starttag">title</sgmltag>Title<sgmltag class="endtag">title</sgmltag>
<sgmltag class="starttag">mediaobject</sgmltag>
<sgmltag class="starttag">title</sgmltag>Title<sgmltag
class="endtag">title</sgmltag> <sgmltag
class="starttag">mediaobject</sgmltag>
<sgmltag class="starttag">imageobject</sgmltag>
<sgmltag class="starttag">imagedata fileref="images/file.eps" format="eps"</sgmltag>
<sgmltag class="endtag">imageobject</sgmltag>
<sgmltag class="starttag">imageobject</sgmltag>
<sgmltag class="starttag">imagedata fileref="images/file.jpg" format="jpg"</sgmltag>
<sgmltag class="endtag">imageobject</sgmltag>
<sgmltag class="starttag">textobject</sgmltag>
<sgmltag class="starttag">phrase</sgmltag>Here there's an image of this example<sgmltag class="endtag">phrase</sgmltag>
<sgmltag class="endtag">textobject</sgmltag>
<sgmltag class="starttag">caption</sgmltag><sgmltag class="starttag">para</sgmltag>Image Description. Optional. <sgmltag class="endtag">para</sgmltag><sgmltag class="endtag">caption</sgmltag>
<sgmltag class="starttag">imagedata fileref="images/file.eps"
format="eps"</sgmltag>
<sgmltag class="endtag">imageobject</sgmltag> <sgmltag
class="starttag">imageobject</sgmltag>
<sgmltag class="starttag">imagedata fileref="images/file.jpg"
format="jpg"</sgmltag>
<sgmltag class="endtag">imageobject</sgmltag> <sgmltag
class="starttag">textobject</sgmltag>
<sgmltag class="starttag">phrase</sgmltag>Here there's an
image of this example<sgmltag class="endtag">phrase</sgmltag>
<sgmltag class="endtag">textobject</sgmltag> <sgmltag
class="starttag">caption</sgmltag><sgmltag
class="starttag">para</sgmltag>Image
Description. Optional. <sgmltag
class="endtag">para</sgmltag><sgmltag
class="endtag">caption</sgmltag>
<sgmltag class="endtag">mediaobject</sgmltag>
<sgmltag class="endtag">figure</sgmltag>
</programlisting>
<sgmltag class="endtag">figure</sgmltag> </programlisting>
</example>
<para>Files using the following formats are available <simplelist type="inline">
<member>BMP</member>
<member>CGM-BINARY</member>
<member>CGM-CHAR</member>
<member>CGM-CLEAR</member>
<member>DITROFF</member>
<member>DVI</member>
<member>EPS</member>
<member>EQN</member>
<member>FAX</member>
<member>GIF</member>
<member>GIF87A</member>
<member>GIF89A</member>
<member>IGES</member>
<member>JPEG</member>
<member>JPG</member>
<member>LINESPECIFIC</member>
<member>PCX</member>
<member>PIC</member>
<member>PS</member>
<member>SGML</member>
<member>TBL</member>
<member>TEX</member>
<member>TIFF</member>
<member>WMF</member>
<member>WPG</member>
<para>Files using the following formats are available <simplelist
type="inline">
<member>BMP</member> <member>CGM-BINARY</member>
<member>CGM-CHAR</member> <member>CGM-CLEAR</member>
<member>DITROFF</member> <member>DVI</member>
<member>EPS</member> <member>EQN</member> <member>FAX</member>
<member>GIF</member> <member>GIF87A</member>
<member>GIF89A</member> <member>IGES</member>
<member>JPEG</member> <member>JPG</member>
<member>LINESPECIFIC</member> <member>PCX</member>
<member>PIC</member> <member>PS</member> <member>SGML</member>
<member>TBL</member> <member>TEX</member> <member>TIFF</member>
<member>WMF</member> <member>WPG</member>
</simplelist>.</para>
<para>This method presents an advantage: a better control of the
application. The elements <sgmltag class="starttag">imageobject</sgmltag>
are consecutively tested until one of them is accepted. If the
output format does not support images the <sgmltag
class="starttag">textobject</sgmltag> element will be used. However, the biggest
advantage in usage of the format <xref
linkend="former-figure-imageobject"/> is that in DocBook
<literal>5.0</literal>, the <sgmltag
class="starttag">graphic</sgmltag> element will cease to exist.</para>
<para>This method presents an advantage: a better
control of the application. The elements <sgmltag
class="starttag">imageobject</sgmltag> are consecutively tested
until one of them is accepted. If the output format does not
support images the <sgmltag class="starttag">textobject</sgmltag>
element will be used. However, the biggest advantage in usage
of the format <xref linkend="former-figure-imageobject"/>
is that in DocBook <literal>5.0</literal>, the <sgmltag
class="starttag">graphic</sgmltag> element will cease to
exist.</para>
<para>As a disadvantage, there is the need for more than one representation
code of the same information. It is up to the author to decide which
method to implement illustrations and pictures on the document, but
for compatibility with future versions <emphasis>I
recommend</emphasis> the use of this method for pictures and
graphics.</para>
<para>As a disadvantage, there is the need for more than one
representation code of the same information. It is up to the
author to decide which method to implement illustrations and
pictures on the document, but for compatibility with future
versions <emphasis>I recommend</emphasis> the use of this method
for pictures and graphics.</para>
</section>
@ -705,58 +758,59 @@ class="starttag">xref linkend="secao" /</sgmltag> for more information.</program
<title>Listings and program codes</title>
<indexterm zone="listings">
<primary>listings</primary>
<secondary>inserting</secondary>
<primary>listings</primary> <secondary>inserting</secondary>
</indexterm>
<para>
This feature allows authors to show parts of code. It also
lets allows the author to insert comments within the code using
call-outs.
</para>
<para>This was used to demonstrate how a catalog
file is configured (see <xref linkend="making-catalogs"/>).
That code is shown below. If the call-out feature
is not needed, it is possible to eliminate the areas between
</para>
<para>This was used to demonstrate how a catalog file
is configured (see <xref linkend="making-catalogs"/>).
That code is shown below. If the call-out feature is not
needed, it is possible to eliminate the areas between
<sgmltag class="starttag">areaspec</sgmltag> and <sgmltag
class="starttag">calloutlist</sgmltag>.</para>
<programlisting id="ex-listing">
&lt;example id="sample-catalog"&gt;
&lt;title&gt;Catalog Sample&lt;/title&gt;
&lt;programlistingco&gt;
&lt;title&gt;Catalog Sample&lt;/title&gt; &lt;programlistingco&gt;
&lt;areaspec&gt;
&lt;area coords="1" id="ex.catalog.comment"&gt;
&lt;area coords="5" id="ex.catalog.definition"&gt;
&lt;area coords="11" id="ex.catalog.eof"&gt;
&lt;area coords="1" id="ex.catalog.comment"&gt; &lt;area
coords="5" id="ex.catalog.definition"&gt; &lt;area coords="11"
id="ex.catalog.eof"&gt;
&lt;/areaspec&gt;
&lt;programlisting&gt;
&lt;programlisting&gt;
-- Catalogs for the Conectiva S.A. Style --
OVERRIDE YES
PUBLIC "-//Conectiva SA//DTD books V1.0//EN" "/home/ldp/estilos/livros.dtd"
PUBLIC "-//Conectiva SA//DTD books V1.0//EN"
"/home/ldp/estilos/livros.dtd"
DELEGATE "-//OASIS" "/home/ldp/SGML/dtds/catalog.dtd"
DOCTYPE BOOK /home/ldp/SGML/dtds/docbook/db31/docbook.dtd
-- EOF --
&lt;/programlisting&gt;
-- EOF --
&lt;/programlisting&gt;
&lt;calloutlist&gt;
&lt;callout arearefs="ex.catalog.comment"&gt;
&lt;to&gt; Comment. Comments begin with &lt;quote&gt;--&lt;/quote&gt;
and follows to the end of the line. &lt;/to&gt;
&lt;/callout&gt;
&lt;callout arearefs="ex.catalog.definition"&gt;
&lt;to&gt; The public type association
&lt;parameter class="option"&gt;"-//Conectiva SA//DTD books V1.0//EN"&lt;/parameter&gt;
with the file &lt;filename&gt;books.dtd&lt;/filename&gt; on the directory
&lt;filename class="directory"&gt;/home/ldp/estilos&lt;/filename&gt;. &lt;/para&gt;
&lt;/callout&gt;
&lt;callout arearefs="ex.catalog.eof"&gt;
&lt;para&gt; Comment informing the end of the file. &lt;/para&gt;
&lt;to&gt; Comment. Comments begin with
&lt;quote&gt;--&lt;/quote&gt; and follows to the end of the
line. &lt;/to&gt;
&lt;/callout&gt; &lt;callout arearefs="ex.catalog.definition"&gt;
&lt;to&gt; The public type association
&lt;parameter class="option"&gt;"-//Conectiva SA//DTD
books V1.0//EN"&lt;/parameter&gt; with the file
&lt;filename&gt;books.dtd&lt;/filename&gt;
on the directory &lt;filename
class="directory"&gt;/home/ldp/estilos&lt;/filename&gt;.
&lt;/para&gt;
&lt;/callout&gt; &lt;callout arearefs="ex.catalog.eof"&gt;
&lt;para&gt; Comment informing the end of the file. &lt;/para&gt;
&lt;/callout&gt;
&lt;/calloutlist&gt;
&lt;/programlistingco&gt;
@ -764,109 +818,109 @@ DOCTYPE BOOK /home/ldp/SGML/dtds/docbook/db31/docbook.dtd
</programlisting>
<indexterm zone="ex-listing">
<primary>listings</primary>
<secondary>inserting</secondary>
<primary>listings</primary> <secondary>inserting</secondary>
<tertiary>example</tertiary>
</indexterm>
<para>The listings can be directly inserted in the document's body without
the need of the <sgmltag class="starttag">example</sgmltag>
<para>The listings can be directly inserted in the document's body
without the need of the <sgmltag class="starttag">example</sgmltag>
or <sgmltag class="starttag">para</sgmltag> elements.</para>
<para>The calling coordinates' specifications are done with reference to the
code line which will be commented upon.</para>
<para>The calling coordinates' specifications are done with reference
to the code line which will be commented upon.</para>
</section>
<section id="metadata-markup">
<title>Markup for Metadata</title>
<section id="metadata-markup"> <title>Markup for Metadata</title>
<section id="crediting">
<title>Crediting Translators, Converters and Co-authors</title>
<para>There are several ways that these folks, as well as other
contributors to your document, can be given some recognition for the
help they've given you.</para>
contributors to your document, can be given some recognition for
the help they've given you.</para>
<section id="crediting-othercredit">
<title><sgmltag class="starttag">othercredit</sgmltag></title>
<section id="crediting-othercredit"> <title><sgmltag
class="starttag">othercredit</sgmltag></title>
<para>All translators, converters and co-authors
<para>All translators, converters and co-authors
should be credited with an
<sgmltag class="starttag">othercredit</sgmltag> tag entry.
To properly credit a translator or converter, use the
<sgmltag class="starttag">othercredit</sgmltag> tag with
To properly credit a translator or converter, use the <sgmltag
class="starttag">othercredit</sgmltag> tag with
the <sgmltag class="starttag">role</sgmltag>
attribute set to <quote>converter</quote> or
attribute set to <quote>converter</quote> or
<quote>translator</quote>,
as indicated in the example below:</para>
<programlisting>
<sgmltag class="starttag">othercredit role='converter'</sgmltag>
<sgmltag class="starttag">firstname</sgmltag>David<sgmltag class="endtag">firstname</sgmltag>
<sgmltag class="starttag">surname</sgmltag>Merrill<sgmltag class="endtag">surname</sgmltag>
<sgmltag class="starttag">contrib</sgmltag>Conversion from HTML to DocBook v3.1 (SGML).<sgmltag class="endtag">contrib</sgmltag>
<sgmltag class="starttag">firstname</sgmltag>David<sgmltag
class="endtag">firstname</sgmltag> <sgmltag
class="starttag">surname</sgmltag>Merrill<sgmltag
class="endtag">surname</sgmltag> <sgmltag
class="starttag">contrib</sgmltag>Conversion from HTML to DocBook v3.1
(SGML).<sgmltag class="endtag">contrib</sgmltag>
<sgmltag class="endtag">othercredit</sgmltag></programlisting>
</section>
<section id="crediting-version">
<title><sgmltag class="starttag">revremark</sgmltag>s</title>
<para>Within the <sgmltag class="starttag">revision</sgmltag>
tag hierarchy is a tag called <sgmltag
<para>Within the <sgmltag class="starttag">revision</sgmltag>
tag hierarchy is a tag called <sgmltag
class="starttag">revremark</sgmltag>. Within this tag,
you can make any brief notes you wish about each
you can make any brief notes you wish about each
particular revision of your document.</para>
</section>
</section>
<section id="acceptedrev">
<title> Revision History </title>
<para> The <sgmltag class="starttag">revhistory</sgmltag> tag should be
used to denote the various revisions of the document. Specify the
date, revision number and comments regarding what has changed.</para>
<para>
<title> Revision History </title> <para> The <sgmltag
class="starttag">revhistory</sgmltag> tag should be used to denote
the various revisions of the document. Specify the date, revision
number and comments regarding what has changed.</para> <para>
Revisions should be listed with the most-recent version at the
top (list in descending order).
</para>
</section>
<section id="accepteddates">
<title> Date formats </title>
<para> The <sgmltag class="starttag">pubdate</sgmltag> tag in
your header should list the publication date of this particular
version of the document (coincide with the revision date).
It should be in the following format: </para>
<programlisting format="linespecific"><sgmltag class="starttag">pubdate</sgmltag>2002-04-25<sgmltag class="endtag">pubdat
<title> Date formats </title> <para> The <sgmltag
class="starttag">pubdate</sgmltag> tag in your header should list
the publication date of this particular version of the document
(coincide with the revision date). It should be in the following
format: </para> <programlisting format="linespecific"><sgmltag
class="starttag">pubdate</sgmltag>2002-04-25<sgmltag
class="endtag">pubdat
e</sgmltag></programlisting>
<para>
The date is in the format YYYY-MM-DD, which is one of the
<ulink url="http://www.w3.org/TR/NOTE-datetime">ISO 8601</ulink> standard
formats for representing dates. For you Yanks out there (me too),
think of it as going from the largest unit of time to
the smallest.
The date is in the format YYYY-MM-DD, which is one of the <ulink
url="http://www.w3.org/TR/NOTE-datetime">ISO 8601</ulink>
standard formats for representing dates. For you Yanks out
there (me too), think of it as going from the largest unit of
time to the smallest.
</para>
</section>
<section id="sampleai">
<title> Sample Article (or Book) Information Element </title>
<para> Here is a sample of a complete DocBook (SGML or XML)
<sgmltag class="starttag">articleinfo</sgmltag>
element which contains some of the items and constructs previously
described. </para>
<programlisting format="linespecific">
<sgmltag class="starttag">articleinfo</sgmltag> element
which contains some of the items and constructs previously
described. </para> <programlisting format="linespecific">
&lt;articleinfo&gt;
&lt;!-- Use "HOWTO", "mini HOWTO", "FAQ" in title, if appropriate --&gt;
&lt;title&gt;Sample HOWTO&lt;/title&gt;
&lt;!-- Use "HOWTO", "mini HOWTO", "FAQ" in title, if appropriate
--&gt; &lt;title&gt;Sample HOWTO&lt;/title&gt;
&lt;author&gt;
&lt;firstname&gt;your_firstname&lt;/firstname&gt;
&lt;surname&gt;your_surname&lt;/surname&gt;
&lt;affiliation&gt;
&lt;!-- Valid email...spamblock/scramble if so desired --&gt;
&lt;address&gt;&lt;email&gt;xxx (at) xxx.xxx&lt;/email&gt;&lt;/address&gt;
&lt;surname&gt;your_surname&lt;/surname&gt; &lt;affiliation&gt;
&lt;!-- Valid email...spamblock/scramble if so
desired --&gt; &lt;address&gt;&lt;email&gt;xxx (at)
xxx.xxx&lt;/email&gt;&lt;/address&gt;
&lt;/affiliation&gt;
&lt;/author&gt;
@ -874,21 +928,20 @@ e</sgmltag></programlisting>
&lt;revhistory&gt;
&lt;revision&gt;
&lt;revnumber&gt;1.0&lt;/revnumber&gt;
&lt;date&gt;2002-04-25&lt;/date&gt;
&lt;authorinitials&gt;xx&lt;/authorinitials&gt;
&lt;revremark&gt;first official release&lt;/revremark&gt;
&lt;/revision&gt;
&lt;revision&gt;
&lt;revnumber&gt;0.9&lt;/revnumber&gt;
&lt;date&gt;2002-04-15&lt;/date&gt;
&lt;authorinitials&gt;xx&lt;/authorinitials&gt;
&lt;revremark&gt;first draft&lt;/revremark&gt;
&lt;revnumber&gt;1.0&lt;/revnumber&gt;
&lt;date&gt;2002-04-25&lt;/date&gt;
&lt;authorinitials&gt;xx&lt;/authorinitials&gt;
&lt;revremark&gt;first official release&lt;/revremark&gt;
&lt;/revision&gt; &lt;revision&gt;
&lt;revnumber&gt;0.9&lt;/revnumber&gt;
&lt;date&gt;2002-04-15&lt;/date&gt;
&lt;authorinitials&gt;xx&lt;/authorinitials&gt;
&lt;revremark&gt;first draft&lt;/revremark&gt;
&lt;/revision&gt;
&lt;/revhistory&gt;
&lt;!-- Provide a good abstract; a couple of sentences is sufficient --&gt;
&lt;abstract&gt;
&lt;!-- Provide a good abstract; a couple of sentences is sufficient
--&gt; &lt;abstract&gt;
&lt;para&gt;
This is a sample DocBook (SGML or XML) HOWTO which has been
constructed to serve as a template.
@ -899,144 +952,132 @@ e</sgmltag></programlisting>
</section>
</section> <!-- end of metadata-markup -->
<section id="tools-entities">
<title>Entities (shortcuts, text macros and re-usable text)</title>
<section id="tools-entities"> <title>Entities (shortcuts,
text macros and re-usable text)</title>
<indexterm zone="tools-writing">
<primary>entities</primary>
<secondary>parameters</secondary>
<tertiary>usage</tertiary>
<primary>entities</primary> <secondary>parameters</secondary>
<tertiary>usage</tertiary>
</indexterm>
<para>
There may be some segments of text, or markup that you want
to use over and over again. Instead of typing it up multiple
times (and then having to edit it multiple times if you want
to make a change) you can use <glossterm>external
entities</glossterm>. Entities can give you a short cut to:
re-using whole documents, text snippets, and special markup.
Some common ways to use an entity would be for:
There may be some segments of text, or markup
that you want to use over and over again. Instead
of typing it up multiple times (and then having
to edit it multiple times if you want to make
a change) you can use <glossterm>external
entities</glossterm>. Entities can give you a short
cut to:
re-using whole documents, text snippets, and
special markup. Some common ways to use an
entity would be for:
</para>
<itemizedlist>
<listitem><formalpara>
<title>text macros for markup</title>
<para>e.g. a company URL. By using a parameter entity you
could refer simply to &amp;my-company-url; instead of typing
out the full &lt;ulink
url="http://foo.bar"&gt;Foo.bar&lt;/ulink&gt; each time.
</para>
<listitem><formalpara> <title>text macros
for markup</title> <para>e.g. a company
URL. By using a parameter entity you
could refer simply to &amp;my-company-url;
instead of typing out the full &lt;ulink
url="http://foo.bar"&gt;Foo.bar&lt;/ulink&gt;
each time. </para> </formalpara></listitem>
<listitem><formalpara> <title>software
license</title> <para>e.g. the GNU Free
Documentation License. It's long. And must
be included in full in each document. By
leaving the license in a separate file you can
easily include it in many documents without
having to redo the markup each time. </para>
</formalpara></listitem>
<listitem><formalpara>
<title>software license</title>
<para>e.g. the GNU Free Documentation License. It's long. And
must be included in full in each document. By leaving the
license in a separate file you can easily include it in many
documents without having to redo the markup each time.
</para>
</formalpara></listitem>
<listitem><formalpara>
<title>repeated text</title>
<para>e.g. an introduction to a topic which is included both
as a summary in one section and as an introduction to the
full information in another. Saves on editing time if you
need to make changes to both sets of text.
</para>
</formalpara>
</listitem>
<listitem><formalpara> <title>repeated
text</title> <para>e.g. an introduction to a
topic which is included both as a summary in
one section and as an introduction to the full
information in another. Saves on editing time if
you need to make changes to both sets of text.
</para> </formalpara> </listitem>
</itemizedlist>
<example id="entities-simple">
<title>Adding Entities</title>
<screen>
<example id="entities-simple"> <title>Adding
Entities</title> <screen>
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
&lt;-- I can add comments here --&gt;
&lt;!ENTITY shortcut "Replace 'shortcut' with this text."&gt;
&lt;!ENTITY sc-to-a-file SYSTEM "anotherfile.xml"&gt;
&lt;-- note: the square bracket on the third line is closed on the next line--&gt;
]&gt;
</screen>
</example>
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ &lt;-- I can
add comments here --&gt; &lt;!ENTITY shortcut "Replace 'shortcut' with
this text."&gt; &lt;!ENTITY sc-to-a-file SYSTEM "anotherfile.xml"&gt;
&lt;-- note: the square bracket on the third line is closed on the next
line--&gt; ]&gt;
</screen> </example>
<para>
To use these entities simply insert the name you gave the
entity between a &amp; and a ;. For example: &amp;shortcut;
would expand into Replace 'shortcut' with this text;
&amp;sc-to-a-file; would include the full contents of
whatever was in anotherfile.xml.
To use these entities simply insert the name
you gave the entity between a &amp; and a ;. For
example: &amp;shortcut; would expand into Replace
'shortcut' with this text; &amp;sc-to-a-file;
would include the full contents of whatever
was in anotherfile.xml.
</para>
<para>An important feature while writing a text is the ability
to check whether or not it will be presented in the final
draft. It's common to have several parts of the text marked as
draft, especially when updating an already existing
document.</para>
<para>With the use of parameter entities, you can include or eliminate
these drafts by altering only one line at the beginning of a
document.</para>
<para>An important feature while writing a text is the ability to
check whether or not it will be presented in the final draft. It's
common to have several parts of the text marked as draft,
especially when updating an already existing document.</para>
<para>With the use of parameter entities, you can include or
eliminate these drafts by altering only one line at the beginning
of a document.</para>
<example id="ex-entity-parameters">
<title>Use of parameter entities</title>
<programlisting>
<sgmltag class="starttag">!entity % review "INCLUDE"</sgmltag>
...
<sgmltag class="starttag">![%review;[
&lt;para&gt;This paragraph will be included on the draft when the entity
"review" is defined with the value "INCLUDE". &lt;/para&gt;
]]</sgmltag>
</programlisting>
<title>Use of parameter entities</title> <programlisting>
<sgmltag class="starttag">!entity % review "INCLUDE"</sgmltag> ...
<sgmltag class="starttag">![%review;[ &lt;para&gt;This paragraph will
be included on the draft when the entity "review" is defined with the
value "INCLUDE". &lt;/para&gt; ]]</sgmltag>
</programlisting>
</example>
<indexterm zone="ex-entity-parameters">
<primary>entities</primary>
<secondary>parameters</secondary>
<tertiary>example</tertiary>
<primary>entities</primary> <secondary>parameters</secondary>
<tertiary>example</tertiary>
</indexterm>
<para>The entity <literal>review</literal> might have several
texts defined, as in <xref linkend="ex-entity-parameters"/>. When
the changes to the text are considered final, you need
only to remove parts of the text between the
3<superscript>rd.</superscript> and
6<superscript>th.</superscript> lines.</para>
<para>The entity <literal>review</literal> might have several texts
defined, as in <xref linkend="ex-entity-parameters"/>. When the
changes to the text are considered final, you need only to remove
parts of the text between the 3<superscript>rd.</superscript>
and 6<superscript>th.</superscript> lines.</para>
<para>To keep the draft definitions and hide the text in
the final draft, just alter the specification of the entity from
<literal>INCLUDE</literal> to <literal>IGNORE</literal>.</para>
<para>To keep the draft definitions and hide the text in the
final draft, just alter the specification of the entity from
<literal>INCLUDE</literal> to <literal>IGNORE</literal>.</para>
</section>
<section id="namedfiles">
<title>Customizing the HTML file names</title>
<para>By default, when separate HTML files are made, the SGML
processor will assign arbitrary names to the resulting files.
This can be confusing to readers who may bookmark a page only to
have it change. Whatever
your reasoning, here's how to make separate files named the way
you want:</para>
<para>In your first <sgmltag class="starttag">article</sgmltag>
tag (which should be the only one) include an id parameter and
call it index. This will make your tag look like this:</para>
<title>Customizing the HTML file names</title> <para>By default,
when separate HTML files are made, the SGML processor will assign
arbitrary names to the resulting files. This can be confusing
to readers who may bookmark a page only to have it change.
Whatever your reasoning, here's how to make separate files
named the way you want:</para> <para>In your first <sgmltag
class="starttag">article</sgmltag> tag (which should be the only
one) include an id parameter and call it index. This will make
your tag look like this:</para>
<programlisting format="linespecific">
<sgmltag class="starttag">article id="index"</sgmltag>
</programlisting>
<sgmltag class="starttag">article id="index"</sgmltag> </programlisting>
<para>Do not modify the first
<para>Do not modify the first
<sgmltag class="starttag">chapter</sgmltag>
tag, as it's usually an introduction and you
want that on the first page. For each other <sgmltag
class="starttag">section</sgmltag> tag, include the id parameter
and name it. A name should include only alphanumeric characters,
and it should be short enough to understand what it is.</para>
tag, as it's usually an introduction and you want that on the first
page. For each other <sgmltag class="starttag">section</sgmltag>
tag, include the id parameter and name it. A name should include
only alphanumeric characters, and it should be short enough to
understand what it is.</para>
<programlisting format="linespecific">
<sgmltag class="starttag">chapter id="tips"</sgmltag>
</programlisting>
<programlisting format="linespecific"> <sgmltag class="starttag">chapter
id="tips"</sgmltag> </programlisting>
</section>