]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | <?xml version="1.0" encoding="utf-8"?> |
2 | <!-- | |
3 | Copyright (c) 2002 Douglas Gregor <doug.gregor -at- gmail.com> | |
4 | ||
5 | Distributed under the Boost Software License, Version 1.0. | |
6 | (See accompanying file LICENSE_1_0.txt or copy at | |
7 | http://www.boost.org/LICENSE_1_0.txt) | |
8 | --> | |
9 | <!DOCTYPE chapter PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" | |
10 | "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd"> | |
11 | <chapter xmlns:xi="http://www.w3.org/2001/XInclude" id="boostbook.documenting" | |
12 | last-revision="$Date$"> | |
13 | <title>Documenting libraries</title> | |
14 | ||
15 | <para>BoostBook is an extension to <ulink | |
16 | url="http://www.docbook.org">DocBook</ulink>, an XML format for | |
17 | representing documentation. BoostBook inherits much of its | |
18 | functionality and many elements from DocBook that are not | |
19 | redocumented here. When writing BoostBook documentation, please | |
20 | refer also to <ulink | |
21 | url="http://docbook.org/tdg/en/index.html">DocBook: The Definitive | |
22 | Guide</ulink>.</para> | |
23 | ||
24 | <section id="boostbook.defining"> | |
25 | <title>Defining a BoostBook library</title> | |
26 | ||
27 | <para>BoostBook library documentation is contained entirely within | |
28 | a <library> XML element. To create a skeletal library, we | |
29 | need to create a new XML document (call it <code>any.xml</code>) | |
30 | that contains basic information about the library. The following | |
31 | <link linkend="boostbook.documenting.skeletal">BoostBook XML | |
32 | example</link> describes basic information about the <ulink | |
33 | url="http://www.boost.org/libs/any/index.html">Boost.Any</ulink> | |
34 | library:</para> | |
35 | ||
36 | <example id="boostbook.documenting.skeletal"> | |
37 | <title>A Skeletal BoostBook Library</title> | |
38 | <programlisting> | |
39 | <?xml version="1.0" encoding="utf-8"?> | |
40 | <!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" | |
41 | "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd"> | |
42 | <library name="Any" dirname="any" xmlns:xi="http://www.w3.org/2001/XInclude" | |
43 | id="any" last-revision="$Date$"> | |
44 | <libraryinfo> | |
45 | <author> | |
46 | <firstname>Kevlin</firstname> | |
47 | <surname>Henney</surname> | |
48 | </author> | |
49 | <librarypurpose> | |
50 | Safe, generic container for single values of different value types | |
51 | </librarypurpose> | |
52 | <librarycategory name="category:data-structures"/> | |
53 | </libraryinfo> | |
54 | </library> | |
55 | </programlisting> | |
56 | </example> | |
57 | ||
58 | <para>The first three lines identify this document as a BoostBook | |
59 | <ulink url="http://www.w3.org/XML/">XML</ulink> document. The | |
60 | DOCTYPE line states that the document conforms to the BoostBook | |
61 | DTD, and that the top-level element is a BoostBook | |
62 | <library>.</para> | |
63 | ||
64 | <para>The <library> element actually describes the aspects | |
65 | of BoostBook library documentation. The attributes for the | |
66 | <library> element are:</para> | |
67 | ||
68 | <variablelist> | |
69 | <title>Attributes for the <library> element</title> | |
70 | <varlistentry> | |
71 | <term><code>name</code></term> | |
72 | <listitem> | |
73 | <simpara>The full name of the library, e.g., "Any"</simpara> | |
74 | </listitem> | |
75 | </varlistentry> | |
76 | <varlistentry> | |
77 | <term><code>dirname</code></term> | |
78 | <listitem> | |
79 | <simpara>The name of the directory, relative to | |
80 | <code>boost/libs</code>, in which the library | |
81 | resides. This name may be a relative path, such as | |
82 | <code>math/octonion</code>, using "/" for the directory | |
83 | separator.</simpara> | |
84 | </listitem> | |
85 | </varlistentry> | |
86 | <varlistentry> | |
87 | <term><code>id</code></term> | |
88 | <listitem> | |
89 | <simpara>A short, unique name for the library. For libraries | |
90 | with simple directory names (e.g., ones that do not contain | |
91 | a "/"), this should be the same as the | |
92 | <code>dirname</code>. This <code>id</code> will be used to | |
93 | identify libraries and, for HTML output, will be used as the | |
94 | base name for the HTML file in which the library's | |
95 | documentation resides, so it should use only lowercase | |
96 | alphanumeric characters and underscores.</simpara> | |
97 | </listitem> | |
98 | </varlistentry> | |
99 | <varlistentry> | |
100 | <term><code>last-revision</code></term> | |
101 | <listitem> | |
102 | <simpara>Always set to <code>$Date$</code>, which is | |
103 | expanded by CVS to include the date and time that the file | |
104 | was last modified.</simpara> | |
105 | </listitem> | |
106 | </varlistentry> | |
107 | </variablelist> | |
108 | ||
109 | <para>Inside the <library> element we have the | |
110 | <libraryinfo> element, which gives information about the | |
111 | library itself. It contains the author's name (there may be more | |
112 | than one <author> element), followed by the purpose of the | |
113 | library and the list of categorizations. The | |
114 | <librarypurpose> element should always contain a very short | |
115 | (single sentence) description of the library's purpose, and should | |
116 | <emphasis>not</emphasis> terminate with a period.</para> | |
117 | ||
118 | <para>The list of categories is specified by a set of | |
119 | <librarycategory> elements. Each <librarycategory> | |
120 | element has a <code>name</code> element that identifies one of the | |
121 | categories. The actual list of categories is in the file | |
122 | <filename>doc/src/boost.xml</filename>. | |
123 | </para> | |
124 | ||
125 | <para>At this point, we can apply the BoostBook XSL stylesheets to | |
126 | <code>any.xml</code> (to DocBook) followed by a DocBook XSL | |
127 | stylesheet to generate HTML output, as described in <xref | |
128 | linkend="boostbook.getting.started"/>.</para> | |
129 | </section> | |
130 | ||
131 | <section> | |
132 | <title>From HTML to BoostBook</title> | |
133 | ||
134 | <para>Most library authors are comfortable with writing HTML | |
135 | documentation. Writing <ulink | |
136 | url="http://www.docbook.org">DocBook</ulink> documentation (and, | |
137 | by extension, BoostBook documentation) is quite similar to writing | |
138 | HTML, except that BoostBook uses different element names from HTML | |
139 | (see <xref linkend="html.to.boostbook"/>) and BoostBook XML is a | |
140 | much more rigid format than HTML.</para> | |
141 | ||
142 | <para>One of the easiest ways to convert HTML documentation into | |
143 | BoostBook documentation is to use <ulink | |
144 | url="http://tidy.sourceforge.net/">HTML Tidy</ulink> to transform | |
145 | your HTML into valid XHTML, which will make sure that all elements | |
146 | are properly closed, then apply the transformations in <xref | |
147 | linkend="html.to.boostbook"/> to the body of the XHTML | |
148 | document. The following command uses HTML Tidy to transform HTML | |
149 | into valid XHTML:</para> | |
150 | ||
151 | <programlisting> | |
152 | tidy -asxhtml input.html > output.xhtml</programlisting> | |
153 | ||
154 | <para>When converting documentation from HTML to BoostBook, note | |
155 | that some redundant information that has to be manually maintained | |
156 | in HTML is automatically generated in BoostBook: for instance, the | |
157 | library categorizations, purpose, and author list described in | |
158 | <xref linkend="boostbook.defining"/> are used both in the | |
159 | documentation for the library and to build alphabetical and | |
160 | categorized lists of known libraries; similarly, tables of | |
161 | contents are built automatically from the titles of sections in | |
162 | the BoostBook document.</para> | |
163 | ||
164 | <table id="html.to.boostbook"> | |
165 | <title>Converting HTML elements to BoostBook</title> | |
166 | <tgroup cols="2" align="left"> | |
167 | <thead> | |
168 | <row> | |
169 | <entry>HTML</entry> | |
170 | <entry>BoostBook</entry> | |
171 | </row> | |
172 | </thead> | |
173 | <tbody> | |
174 | <row> | |
175 | <entry><simpara><h1>, <h2>, etc.</simpara></entry> | |
176 | <entry> | |
177 | <simpara><section>, <title>; See <xref | |
178 | linkend="boostbook.sectioning"/></simpara> | |
179 | </entry> | |
180 | </row> | |
181 | <row> | |
182 | <entry><simpara><i>, <em></simpara></entry> | |
183 | <entry><simpara><emphasis></simpara></entry> | |
184 | </row> | |
185 | <row> | |
186 | <entry><simpara><b></simpara></entry> | |
187 | <entry><simpara><emphasis role="bold"></simpara></entry> | |
188 | </row> | |
189 | <row> | |
190 | <entry><simpara><ol></simpara></entry> | |
191 | <entry><simpara><orderedlist></simpara></entry> | |
192 | </row> | |
193 | <row> | |
194 | <entry><simpara><ul></simpara></entry> | |
195 | <entry><simpara><itemizedlist></simpara></entry> | |
196 | </row> | |
197 | <row> | |
198 | <entry><simpara><li></simpara></entry> | |
199 | <entry><simpara><listitem></simpara></entry> | |
200 | </row> | |
201 | <row> | |
202 | <entry><simpara><pre></simpara></entry> | |
203 | <entry><simpara><programlisting></simpara></entry> | |
204 | </row> | |
205 | <row> | |
206 | <entry><simpara><code></simpara></entry> | |
207 | <entry><simpara><computeroutput>,<code></simpara></entry> | |
208 | </row> | |
209 | <row> | |
210 | <entry><simpara><p></simpara></entry> | |
211 | <entry><simpara><para>, <simpara></simpara></entry> | |
212 | </row> | |
213 | <row> | |
214 | <entry><simpara><a></simpara></entry> | |
215 | <entry> | |
216 | <simpara><xref>, <link>, <ulink>;, See <xref | |
217 | linkend="boostbook.linking"/></simpara></entry> | |
218 | </row> | |
219 | <row> | |
220 | <entry><simpara><table>, <tr>, <th>, <td></simpara></entry> | |
221 | <entry><simpara><table>, <informaltable>, <tgroup>, <thead>, <tfoot>, <tbody>, <row>, <entry>, <entrytbl>; BoostBook tables are equivalent to DocBook tables, for which there is a good <ulink url="http://opensource.bureau-cornavin.com/crash-course/en/tables.html">tutorial here</ulink></simpara></entry> | |
222 | </row> | |
223 | </tbody> | |
224 | </tgroup> | |
225 | </table> | |
226 | </section> | |
227 | ||
228 | <section id="boostbook.sectioning"> | |
229 | <title>Sectioning in BoostBook</title> | |
230 | <para>"Sectioning" refers to organization of a document into separate sections, each with a title, some text, and possibly subsections. Each section is described in BoostBook via a <section> element. An introduction section may look like this:</para> | |
231 | <programlisting> | |
232 | <section id="any.intro"> | |
233 | <title>Introduction</title> | |
234 | ||
235 | <para>Introduction to a library...</para> | |
236 | ||
237 | <section> | |
238 | <title>A Subsection</title> | |
239 | <para>Subsection information...</para> | |
240 | </section> | |
241 | </section> | |
242 | </programlisting> | |
243 | <para>The <section> element contains all information that | |
244 | should logically be grouped within that section. The title of the | |
245 | section is placed within the <title> element, and any | |
246 | paragraphs, programs, lists, tables, or subsections can occur | |
247 | within the section. The <code>id</code> attribute of the | |
248 | <section> element gives a unique ID to each section, so that | |
249 | it may later be identified for linking. It is suggested that all | |
250 | IDs start with the short name of a library followed by a period, | |
251 | so that IDs do not conflict between libraries.</para> | |
252 | </section> | |
253 | </chapter> | |
254 |