Index: openacs-4/packages/acs-core-docs/www/docbook-primer.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/docbook-primer.adp,v diff -u -r1.6.2.13 -r1.6.2.14 --- openacs-4/packages/acs-core-docs/www/docbook-primer.adp 2 Sep 2024 09:40:21 -0000 1.6.2.13 +++ openacs-4/packages/acs-core-docs/www/docbook-primer.adp 3 Sep 2024 08:43:02 -0000 1.6.2.14 @@ -413,7 +413,7 @@ tools will be marked up to conform to the <a class="ulink" href="http://docbook.org/xml/index.html" target="_top">DocBook XML DTD</a>. The remaining discussion is about publishing using Docbook.</p><p> -<a class="indexterm" name="id12857" id="id12857"></a> is a +<a class="indexterm" name="id12864" id="id12864"></a> is a publishing standard based on XML with similar goals to the OpenACS Documentation project. Some specific reasons why we are using DocBook:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"> @@ -454,7 +454,7 @@ of elements</a> and use more exotic features in your documents. The list is made up of SGML-elements but basically the same elements are valid in the XML DTD <span class="strong"><strong>as long as -you remember to</strong></span>: <a class="indexterm" name="id12897" id="id12897"></a> +you remember to</strong></span>: <a class="indexterm" name="id12904" id="id12904"></a> </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"> <li class="listitem"><p>Always close your tags with corresponding end-tags and to <span class="strong"><strong>not use other tag @@ -495,7 +495,7 @@ <div class="titlepage"><div><div><h3 class="title"> <a name="dbprimer-structure" id="dbprimer-structure"></a>Document Structure</h3></div></div></div><p>The documentation for each package will make up a little "book" that is structured like this - examples are -<span class="emphasis"><em>emphasized</em></span>: <a class="indexterm" name="id12936" id="id12936"></a> +<span class="emphasis"><em>emphasized</em></span>: <a class="indexterm" name="id12943" id="id12943"></a> </p><pre class="programlisting"> book : <span class="strong"><strong>Docs for one package</strong></span> - <span class="emphasis"><em>templating</em></span> | @@ -520,19 +520,19 @@ </div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="dbprimer-sections" id="dbprimer-sections"></a>Headlines, Sections</h3></div></div></div><p> -<a class="indexterm" name="id12957" id="id12957"></a> Given that +<a class="indexterm" name="id12964" id="id12964"></a> Given that your job starts at the <code class="computeroutput">sect1</code>-level, all your documents should open with a <a class="ulink" href="http://docbook.org/tdg/en/html/sect1.html" target="_top"><code class="computeroutput"><sect1></code></a>-tag and end with the corresponding <code class="computeroutput"></sect1></code>.</p><p> -<a class="indexterm" name="id12965" id="id12965"></a> You need +<a class="indexterm" name="id12972" id="id12972"></a> You need to feed every <code class="computeroutput"><sect1></code> two attributes. The first attribute, <code class="computeroutput">id</code>, is standard and can be used with all elements. It comes in very handy when interlinking between documents (more about this when talking about links in <a class="xref" href="docbook-primer" title="Links">the section called “Links”</a>). The value of <code class="computeroutput">id</code> has to be unique throughout the book you're making since the <code class="computeroutput">id</code>'s in your <code class="computeroutput">sect1</code>'s will turn into filenames when the book is parsed into HTML.</p><p> -<a class="indexterm" name="id12974" id="id12974"></a> The other +<a class="indexterm" name="id12981" id="id12981"></a> The other attribute is <code class="computeroutput">xreflabel</code>. The value of this is the text that will appear as the link when referring to this <code class="computeroutput">sect1</code>.</p><p>Right after the opening tag you put the title of the document - @@ -545,7 +545,7 @@ </sect1> </pre><p> -<a class="indexterm" name="id12982" id="id12982"></a> Inside +<a class="indexterm" name="id12989" id="id12989"></a> Inside this container your document will be split up into <a class="ulink" href="http://docbook.org/tdg/en/html/sect2.html" target="_top"><code class="computeroutput"><sect2></code></a>'s, each with the same requirements - <code class="computeroutput">id</code> and <code class="computeroutput">xreflabel</code> attributes, and a <code class="computeroutput"><title></code>-tag inside. Actually, the <code class="computeroutput">xreflabel</code> is never required in @@ -555,7 +555,7 @@ </div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="dbprimer-code" id="dbprimer-code"></a>Code</h3></div></div></div><p> -<a class="indexterm" name="id12998" id="id12998"></a> For +<a class="indexterm" name="id13005" id="id13005"></a> For displaying a snippet of code, a filename or anything else you just want to appear as a part of a sentence, we use <a class="ulink" href="http://docbook.org/tdg/en/html/computeroutput.html" target="_top"><code class="computeroutput"><computeroutput></code></a> and <a class="ulink" href="http://docbook.org/tdg/en/html/code.html" target="_top"><code class="code"><code></code></a> tags. These replace the HTML-tag <code class="code"><code></code> tag, @@ -569,7 +569,7 @@ </div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="dbprimer-links" id="dbprimer-links"></a>Links</h3></div></div></div><p> -<a class="indexterm" name="id13019" id="id13019"></a> Linking +<a class="indexterm" name="id13026" id="id13026"></a> Linking falls into two different categories: inside the book you're making and outside:</p><div class="variablelist"><dl class="variablelist"> <dt><span class="term"><span class="strong"><strong>1. Inside @@ -578,7 +578,7 @@ <p>By having unique <code class="computeroutput">id</code>'s you can cross-reference any part of your book with a simple tag, regardless of where that part is.</p><p> -<a class="indexterm" name="id13029" id="id13029"></a>Check out +<a class="indexterm" name="id13036" id="id13036"></a>Check out how I link to a subsection of the Developer's Guide:</p><p>Put this in your XML:</p><pre class="programlisting"> - Find information about creating a package in <xref linkend="packages-making-a-package"></xref>. @@ -602,7 +602,7 @@ </dd><dt><span class="term"><span class="strong"><strong>2. Linking outside the documentation</strong></span></span></dt><dd> <p> -<a class="indexterm" name="id13060" id="id13060"></a> If +<a class="indexterm" name="id13067" id="id13067"></a> If you're hyper-linking out of the documentation, it works almost the same way as HTML - the tag is just a little different (<a class="ulink" href="http://docbook.org/tdg/en/html/ulink.html" target="_top"><code class="computeroutput"><ulink></code></a>):</p><pre class="programlisting"><ulink url="http://www.oracle.com/">Oracle Corporation</ulink></pre><p>....will create a hyper-link to Oracle in the HTML-version of @@ -620,7 +620,7 @@ <span class="strong"><strong>Note:</strong></span> The graphics guidelines are not written in stone. Use another valid approach if it works better for you.</em></span></p><p> -<a class="indexterm" name="id13076" id="id13076"></a> To insert +<a class="indexterm" name="id13083" id="id13083"></a> To insert a graphic we use the elements <a class="ulink" href="http://docbook.org/tdg/en/html/mediaobject.html" target="_top"><code class="computeroutput"><mediaobject></code></a>, <a class="ulink" href="http://docbook.org/tdg/en/html/imageobject.html" target="_top"><code class="computeroutput"><imageobject></code></a>, <a class="ulink" href="http://docbook.org/tdg/en/html/imagedata.html" target="_top"><code class="computeroutput"><imagedata></code></a>, @@ -645,7 +645,7 @@ </div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="dbprimer-lists" id="dbprimer-lists"></a>Lists</h3></div></div></div><p> -<a class="indexterm" name="id13092" id="id13092"></a> Here's +<a class="indexterm" name="id13099" id="id13099"></a> Here's how you make the DocBook equivalent of the three usual HTML-lists:</p><div class="variablelist"><dl class="variablelist"> <dt><span class="term"><span class="strong"><strong>1. How to make @@ -699,7 +699,7 @@ </div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="dbprimer-tables" id="dbprimer-tables"></a>Tables</h3></div></div></div><p> -<a class="indexterm" name="id13133" id="id13133"></a> DocBook +<a class="indexterm" name="id13140" id="id13140"></a> DocBook supports several types of tables, but in most cases, the <a class="ulink" href="http://docbook.org/tdg/en/html/informaltable.html" target="_top"><code class="computeroutput"><informaltable></code></a> is enough:</p><pre class="programlisting"> <informaltable frame="all"> <tgroup cols="3"> @@ -745,7 +745,7 @@ </div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="dbprimer-emphasis" id="dbprimer-emphasis"></a>Emphasis</h3></div></div></div><p> -<a class="indexterm" name="id13161" id="id13161"></a> Our +<a class="indexterm" name="id13168" id="id13168"></a> Our documentation uses two flavors of emphasis - italics and bold type. DocBook uses one - <a class="ulink" href="http://docbook.org/tdg/en/html/emphasis.html" target="_top"><code class="computeroutput"><emphasis></code></a>.</p><p>The <code class="computeroutput"><emphasis></code> tag defaults to italics when parsed. If you're looking for