| 1 | <html> |
|---|
| 2 | <head> |
|---|
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> |
|---|
| 4 | <link rel="stylesheet" type="text/css" href="../../boost.css"> |
|---|
| 5 | <title>Writing Documentation for Boost - HTML Design</title> |
|---|
| 6 | </head> |
|---|
| 7 | <body link="#0000ff" vlink="#800080"> |
|---|
| 8 | <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= |
|---|
| 9 | "header"> |
|---|
| 10 | <tr> |
|---|
| 11 | <td valign="top" width="300"> |
|---|
| 12 | <h3><a href="index.html"><img height="86" width="277" alt="C++ Boost" src="../../boost.png" border="0"></a></h3> |
|---|
| 13 | </td> |
|---|
| 14 | <td valign="top"> |
|---|
| 15 | <h1 align="center">Writing Documentation for Boost</h1> |
|---|
| 16 | <h2 align="center">HTML Design</h2> |
|---|
| 17 | </td> |
|---|
| 18 | </tr> |
|---|
| 19 | </table> |
|---|
| 20 | <hr> |
|---|
| 21 | <dl class="page-index"> |
|---|
| 22 | <dt><a href="#introduction">Introduction</a></dt> |
|---|
| 23 | <dt><a href="#common-pages">Common Pages Included in HTML Documentation</a></dt> |
|---|
| 24 | <dl class="page-index"> |
|---|
| 25 | <dt><a href="#index-page">Index</a></dt> |
|---|
| 26 | <dt><a href="#overview-page">Overview</a></dt> |
|---|
| 27 | <dt><a href="#definitions-page">Definitions</a></dt> |
|---|
| 28 | <dt><a href="#rationale-page">Rationale</a></dt> |
|---|
| 29 | <dt><a href="#configuration-page">Configuration Information</a></dt> |
|---|
| 30 | <dt><a href="#faq-page">Frequently Asked Questions</a></dt> |
|---|
| 31 | <dt><a href="#bibliography-page">Bibliography</a></dt> |
|---|
| 32 | <dt><a href="#acknowledgements-page">Acknowledgment</a></dt> |
|---|
| 33 | <dt><a href="#header-page">Header Reference</a></dt> |
|---|
| 34 | </dl> |
|---|
| 35 | <dt><a href="#layout">Layout</a></dt> |
|---|
| 36 | <dl class="page-index"> |
|---|
| 37 | <dt><a href="#page-banner">Page Banner</a></dt> |
|---|
| 38 | <dt><a href="#page-index">Page Index</a></dt> |
|---|
| 39 | <dt><a href="#content">Documentation Content</a></dt> |
|---|
| 40 | <dl class="page-index"> |
|---|
| 41 | <dt><a href="#doc-footnotes">Footnotes</a></dt> |
|---|
| 42 | </dl> |
|---|
| 43 | <dt><a href="#revision-info">Revision Information</a></dt> |
|---|
| 44 | <dt><a href="#copyright">Copyright Information</a></dt> |
|---|
| 45 | </dl> |
|---|
| 46 | <dt><a href="#format">Format</a></dt> |
|---|
| 47 | <dl class="page-index"> |
|---|
| 48 | <dt><a href="#style-sheets">Cascading Style Sheets</a></dt> |
|---|
| 49 | <dl class="page-index"> |
|---|
| 50 | <dt><a href="#boost-style-sheet">Boost Style Sheet</a></dt> |
|---|
| 51 | </dl> |
|---|
| 52 | </dl> |
|---|
| 53 | <dt><a href="#templates">Templates</a></dt> |
|---|
| 54 | <dl class="page-index"> |
|---|
| 55 | <dt><a href="#index-template">Index Page Template</a></dt> |
|---|
| 56 | <dt><a href="#overview-template">Overview Page Template</a></dt> |
|---|
| 57 | <dt><a href="#definitions-template">Definitions Page Template</a></dt> |
|---|
| 58 | <dt><a href="#rationale-template">Rationale Page Template</a></dt> |
|---|
| 59 | <dt><a href="#configuration-template">Configuration Page Template</a></dt> |
|---|
| 60 | <dt><a href="#faq-template">FAQ (Frequently Asked Questions) Page Template</a></dt> |
|---|
| 61 | <dt><a href="#bibliography-template">Bibliography Page Template</a></dt> |
|---|
| 62 | <dt><a href="#acknowledgements-template">Acknowledgments Page Template</a></dt> |
|---|
| 63 | <dt><a href="#header-template">Header Page Template</a></dt> |
|---|
| 64 | </dl> |
|---|
| 65 | </dl> |
|---|
| 66 | <h2><a name="introduction"></a>Introduction</h2> |
|---|
| 67 | <p>Boost places no requirements on the design of HTML documentation for library |
|---|
| 68 | submitters. If you are submitting a library for which documentation already |
|---|
| 69 | exists in either HTML or in a form easily converted to HTML then there is no |
|---|
| 70 | need for you to read this document. However, if you have not yet written the |
|---|
| 71 | documentation, or if you expect to have to translate documentation written in |
|---|
| 72 | a format not easily convertible to HTML then this document can give you a lot |
|---|
| 73 | of information on how to go about writing documentation in HTML.</p> |
|---|
| 74 | <p>In several places this document assumes you're writing the documentation to |
|---|
| 75 | conform to the structure described in the <a href="structure.html">Documentation |
|---|
| 76 | Structure</a> document. There is no requirement that your documentation content |
|---|
| 77 | follow these guidelines, but they provide an effective way to communicate technical |
|---|
| 78 | specifications for a library in a terse yet precise manner that's familiar to |
|---|
| 79 | many Boost users.</p> |
|---|
| 80 | <p>This document also contains links to <a href="#templates">HTML template files</a> |
|---|
| 81 | that can be used to rapidly develop documentation for a library submission. |
|---|
| 82 | These templates follow the guidelines presented here and in the <a href="structure.html">Documentation |
|---|
| 83 | Structure</a> document.</p> |
|---|
| 84 | <h2><a name="common-pages"></a>Common Pages Included in HTML Documentation</h2> |
|---|
| 85 | <p>Most HTML documentation projects will contain some common pages. General guidelines |
|---|
| 86 | for these common pages are provided below.</p> |
|---|
| 87 | <h3><a name="index-page"></a>Index</h3> |
|---|
| 88 | <p>The index page is the first page presented to a user when he browses the documentation. |
|---|
| 89 | Generally this page should not contain any actual content, but instead contains |
|---|
| 90 | a list of links to specific content. At a minimum this list should contain a |
|---|
| 91 | link to every HTML page contained in the documentation. Optionally, sub-lists |
|---|
| 92 | may be provided for individual pages linking to specific subjects within the |
|---|
| 93 | page. These sub-lists should form a "tree" hierarchy based on the |
|---|
| 94 | level of heading tag used for the specific subject. Inclusion of such sub-lists |
|---|
| 95 | for every page can make the index rather lengthy, and since each page should |
|---|
| 96 | include its own <a href="#page-index">Page Index</a>, it may make the navigation |
|---|
| 97 | of the documentation easier if such sub-lists are avoided. However, there is |
|---|
| 98 | one exception to this guideline: reference documentation should contain a link |
|---|
| 99 | to every header file in the library and a sub-list with a link to every macro, |
|---|
| 100 | value, type, class, function and object (see <a href="structure.html">Documentation |
|---|
| 101 | Structure</a>) found in the header. Users aren't always sure what header file |
|---|
| 102 | any of these may be contained in, so this structure in the index allows for |
|---|
| 103 | easy navigation of the reference documentation.</p> |
|---|
| 104 | <p>The index list should generally be constructed using an HTML "definition |
|---|
| 105 | list" (<dl> and <dt> tags). A definition list has no bullets |
|---|
| 106 | or ordered specifications and produces a cleaner layout then an unordered list |
|---|
| 107 | (<ul> and <li> tags) or an ordered list (<ol> and <li> |
|---|
| 108 | tags). If you choose to use the common <a href="#boost-style-sheet">Boost Style |
|---|
| 109 | Sheet</a> you should add a <code>class="index"</code> attribute/value pair to |
|---|
| 110 | the <dl> tag.</p> |
|---|
| 111 | <p>An Index page <a href="#index-template">template</a> is provided for use.</p> |
|---|
| 112 | <h3><a name="overview-page"></a>Overview</h3> |
|---|
| 113 | <p>The Overview page is used to introduce the reader to the library. It should |
|---|
| 114 | give a high-level overview of the purpose of the library and introduce the reader |
|---|
| 115 | to any concepts they may be unfamiliar with. This may also be an appropriate |
|---|
| 116 | place for some "light" rationale, though more thorough presentation |
|---|
| 117 | of any rationale would be better placed in the <a href="#rationale-page">Rational |
|---|
| 118 | Page</a>.</p> |
|---|
| 119 | <p>Like most content pages, the Overview page should include a <a href="#page-index">Page |
|---|
| 120 | Index</a>.</p> |
|---|
| 121 | <p>An Overview page <a href="#overview-template">template</a> is provided for |
|---|
| 122 | use.</p> |
|---|
| 123 | <h3><a name="definitions-page"></a>Definitions</h3> |
|---|
| 124 | <p>The Definitions page is used to provide a list of definitions for terms that |
|---|
| 125 | a user may be unfamiliar with.</p> |
|---|
| 126 | <p>The definition list should generally be constructed using an HTML "definition |
|---|
| 127 | list" (<dl> and <DT> tags). A definition list has no bullets |
|---|
| 128 | or ordered specifications and produces a cleaner layout then an unordered list |
|---|
| 129 | (<UL> and <li> tags) or an ordered list (<ol> and <li> |
|---|
| 130 | tags). If you choose to use the common <a href="#boost-style-sheet">Boost Style |
|---|
| 131 | Sheet</a> you should add a <code>class="definition"</code> attribute/value pair |
|---|
| 132 | to the <dl> tag.</p> |
|---|
| 133 | <p>Because this page's content should only contain a list of definitions, it should |
|---|
| 134 | not have a <a href="#page-index">Page Index</a>.</p> |
|---|
| 135 | <p></p> |
|---|
| 136 | <p> A Definitions page <a href="#definitions-template">template</a> is provided |
|---|
| 137 | for use.</p> |
|---|
| 138 | <h3><a name="rationale-page"></a>Rationale</h3> |
|---|
| 139 | <p>The Rationale page is used to provide lengthy descriptions of the rationale |
|---|
| 140 | behind the library's design. This information helps users to understand why |
|---|
| 141 | a library was designed the way it was and may reduce the frequency of a number |
|---|
| 142 | of frequently asked questions. For a better description of why rationale is |
|---|
| 143 | important see the <a href="http://www.boost.org/more/lib_guide.htm#Rationale">Rationale |
|---|
| 144 | rationale</a> in the general submission guidelines.</p> |
|---|
| 145 | <p>Like most content pages, the Rationale page should include a <a href="#page-index">Page |
|---|
| 146 | Index</a>.</p> |
|---|
| 147 | <p></p> |
|---|
| 148 | <p>A Rationale page <a href="#rationale-template">template</a> is provided for |
|---|
| 149 | use.</p> |
|---|
| 150 | <h3><a name="configuration-page"></a>Configuration Information</h3> |
|---|
| 151 | <p>The Configuration Information page is used to document configuration macros |
|---|
| 152 | used by the library. Such macros belong in one of three groups: macros used |
|---|
| 153 | by library implenters defined in <code><boost/config.hpp></code>, macros |
|---|
| 154 | used by library users to detect platform configuration information and macros |
|---|
| 155 | defined by library users to configure library behavior.</p> |
|---|
| 156 | <p>Like most content pages, the Overview page should include a <a href="#page-index">Page |
|---|
| 157 | Index</a>.</p> |
|---|
| 158 | <p></p> |
|---|
| 159 | <p>A Configuration page <a href="#configuration-template">template</a> is provided |
|---|
| 160 | for use.</p> |
|---|
| 161 | <h3><a name="faq-page"></a>Frequently Asked Questions</h3> |
|---|
| 162 | <p>As a library matures the users will have questions about the usage of the library. |
|---|
| 163 | Often users will ask the same questions over and over again. Rather than having |
|---|
| 164 | to deal with answering the question every time it's asked, a Frequently Asked |
|---|
| 165 | Questions (commonly known as FAQs) page can be used to document the questions |
|---|
| 166 | and answers. This is such a valuable piece of documentation not only for the |
|---|
| 167 | users but for the maintainers as well, that a FAQ page should be provided from |
|---|
| 168 | the outset. If there are no questions that will obviously become a FAQ, the |
|---|
| 169 | initial page may just indicate that there are no FAQs yet. This empty place |
|---|
| 170 | holder helps to indicate to the users that you plan to address any FAQs as they |
|---|
| 171 | occur.</p> |
|---|
| 172 | <p>The <a href="#page-index">Page Index</a> for the FAQ page should contain a |
|---|
| 173 | list of all the questions contained in the document. The actual question entries |
|---|
| 174 | should be formatted with the question in a heading tag and the answers in standard |
|---|
| 175 | paragraph format. This provides a clean presentation that's easy to read.</p> |
|---|
| 176 | <p>A Frequently Asked Questions page <a href="#faq-template">template</a> is provided |
|---|
| 177 | for use.</p> |
|---|
| 178 | <h3><a name="bibliography-page"></a>Bibliography</h3> |
|---|
| 179 | <p>The Bibliography page is used to document any bibliographical information associated |
|---|
| 180 | with references made within the documentation to external resources. Parenthetical |
|---|
| 181 | references are used within the documentation which link to entries in the Bibliography |
|---|
| 182 | page. Bibliographical entries provide detailed information about the external |
|---|
| 183 | resource and may contain hyper links to the resource if it's available online. |
|---|
| 184 | There are several formal styles used for writing bibliographies. You may use |
|---|
| 185 | what ever style you want, but one of the better styles to consider using can |
|---|
| 186 | be referenced <a href="http://www.columbia.edu/cu/cup/cgos/idx_basic.html">here</a>.</p> |
|---|
| 187 | <p>Since the Bibliography page should contain only bibliographical information |
|---|
| 188 | there is no need for a <a href="#page-index">Page Index</a>.</p> |
|---|
| 189 | <p>A Bibliography page <a href="#bibliography-template">template</a> is provided |
|---|
| 190 | for use.</p> |
|---|
| 191 | <h3><a name="acknowledgements-page"></a>Acknowledgment</h3> |
|---|
| 192 | <p>The Acknowledgment page is used to give credit where credit is due. When individuals |
|---|
| 193 | provide input on the design or implementation, or when you make use of someone |
|---|
| 194 | else's work, you should acknowledge them. This is a courtesy that you'd expect |
|---|
| 195 | others to extend to you, so you should strive to acknowledge the efforts of |
|---|
| 196 | everyone else in your own documentation.</p> |
|---|
| 197 | <p>Since the Acknowledgment page should contain only a list of acknowledgment |
|---|
| 198 | there is no need for a <a href="#page-index">Page Index</a>.</p> |
|---|
| 199 | <p>An Acknowledgments page <a href="#acknowledgements-template">template</a> is |
|---|
| 200 | provided for use.</p> |
|---|
| 201 | <h3><a name="header-page"></a>Header Reference</h3> |
|---|
| 202 | <p>The Header Reference pages are the most important pages in your documentation. |
|---|
| 203 | They document all library headers, including all the macros, values, types, |
|---|
| 204 | classes, functions and objects defined in them. In general it may prove useful |
|---|
| 205 | to follow the guidelines in <a href="structure.html">Documentation Structure</a> |
|---|
| 206 | when writing the content for these pages.</p> |
|---|
| 207 | <p>Like most content pages, the Header Reference pages should include a <a href="#page-index">Page |
|---|
| 208 | Index</a>.</p> |
|---|
| 209 | <p>A Header Reference page <a href="#header-template">template</a> is provided |
|---|
| 210 | for use.</p> |
|---|
| 211 | <h2><a name="layout"></a>Layout</h2> |
|---|
| 212 | <p>There are certain page layout concepts that will be used frequently in many |
|---|
| 213 | of your pages. This section outlines some general guidelines that you can follow |
|---|
| 214 | when designing each of these layout concepts for your documentation.</p> |
|---|
| 215 | <h3><a name="page-banner"></a>Page Banner</h3> |
|---|
| 216 | <p>The Page Banner is located at the very top of a page and provides quick information |
|---|
| 217 | about the page contents. This includes the Boost logo, which indicates to the |
|---|
| 218 | reader that this page is part of the Boost web site, a title for the documentation |
|---|
| 219 | (generally the library name) and the page title. The Boost logo should hyper |
|---|
| 220 | link to the Boost home page on the index page and to the index page on all other |
|---|
| 221 | pages. This allows the user to easily navigate through the Boost web site and |
|---|
| 222 | through the documentation. The <title> tag for the HTML page should consist |
|---|
| 223 | of the documentation title and the page title separated by a hyphen.</p> |
|---|
| 224 | <p>The Page Banner should be separated from the rest of the page by the use of |
|---|
| 225 | an <hr> tag. This helps to clearly separate the actual content from the |
|---|
| 226 | title information and produces cleaner text.</p> |
|---|
| 227 | <h3><a name="page-index"></a>Page Index</h3> |
|---|
| 228 | <p>The page index is used to quickly navigate to the various sections of the documentation |
|---|
| 229 | on the page, and when present should be located just below the Page Banner.</p> |
|---|
| 230 | <p>The index list should generally be constructed using an HTML "definition |
|---|
| 231 | list" (<dl> and <DT> tags). A definition list has no bullets |
|---|
| 232 | or ordered specifications and produces a cleaner layout then an unordered list |
|---|
| 233 | (<UL> and <li> tags) or an ordered list (<ol> and <li> |
|---|
| 234 | tags). If you choose to use the Boost Style Sheet you should add a <code>class="page-index"</code> |
|---|
| 235 | attribute/value pair to the <dl> tag.</p> |
|---|
| 236 | <p>Most pages should include a Page Index.</p> |
|---|
| 237 | <h3><a name="content"></a>Documentation Content</h3> |
|---|
| 238 | <p>The page's actual documentation content will be formatted according to the |
|---|
| 239 | specific needs of individual pages, and should be placed right after the Page |
|---|
| 240 | Index if present, or after the Page Banner if not. In general the documentation |
|---|
| 241 | content will take the form of paragraph text contained underneath section headings.</p> |
|---|
| 242 | <h3><a name="doc-footnotes"></a>Footnotes</h3> |
|---|
| 243 | <p>Footnotes may be used within a page's documentation. Within the documentation |
|---|
| 244 | content a footnote reference should take the form of a footnote number in parentheses |
|---|
| 245 | (the parentheses make it easier for the reader to click on the hyper link) hyper |
|---|
| 246 | linking to the actual footnote at the bottom of the page's documentation content. |
|---|
| 247 | You may either use the <sup> tag to format such footnote numbers, or, |
|---|
| 248 | preferably, you can use a CSS style class in order to distinguish the number |
|---|
| 249 | as a footnote instead of as part of the actual text. If you choose to use the |
|---|
| 250 | common <a href="#boost-style-sheet">Boost Style Sheet</a>, a <code>footnote</code> |
|---|
| 251 | class is defined for this purpose.</p> |
|---|
| 252 | <h3><a name="revision-info"></a>Revision Information</h3> |
|---|
| 253 | <p>At the bottom of every page should be some revision information indicating |
|---|
| 254 | when the page was last revised. This information should be separated from the |
|---|
| 255 | rest of the page above by an <hr> tag. The following HTML code snippet |
|---|
| 256 | can be used to track this revision information (this code uses some server components |
|---|
| 257 | that exist on the Boost web site to automatically track revision dates with |
|---|
| 258 | out the need for hand editing the date text):</p> |
|---|
| 259 | <pre><hr> |
|---|
| 260 | <p>Revised |
|---|
| 261 | <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> |
|---|
| 262 | 01 January, 2001 |
|---|
| 263 | <!--webbot bot="Timestamp" endspan i-checksum="39359" --> |
|---|
| 264 | </p> |
|---|
| 265 | </pre> |
|---|
| 266 | <h3><a name="copyright"></a>Copyright Information</h3> |
|---|
| 267 | <p>The very bottom of the page should contain any copyright information that applies |
|---|
| 268 | to the document.</p> |
|---|
| 269 | <h2><a name="format"></a>Format</h2> |
|---|
| 270 | <p>This section provides general guidelines for formatting documentation using |
|---|
| 271 | HTML. The description of the various "common pages" gave specific |
|---|
| 272 | details for formatting specific sections of the documentation, which should |
|---|
| 273 | override these guidelines.</p> |
|---|
| 274 | <h3><a name="code-format"></a>Code</h3> |
|---|
| 275 | <p>Code within the documentation should be placed within either <code></code> |
|---|
| 276 | or <pre></pre> tags. For code that's placed inline with other text |
|---|
| 277 | you use <code></code> tags, while <pre></pre> tags are |
|---|
| 278 | used for code "blocks". If a cascading style sheet is used to specify |
|---|
| 279 | formatting for these tags, a fixed width sans serif font should be used. This |
|---|
| 280 | insures that the code is easily distinguishable from the rest of the text. It |
|---|
| 281 | may also be beneficial to set the style for <pre></pre> tags to |
|---|
| 282 | indent the text, to help separate code blocks from other structural HTML blocks. |
|---|
| 283 | The <a href="#boost-style-sheet">Boost Style Sheet</a> specifies formatting |
|---|
| 284 | for these tags.</p> |
|---|
| 285 | <p><b>Note:</b> "Code" includes variable names, function names, etc.</p> |
|---|
| 286 | <h3><a name="lists"></a>Lists</h3> |
|---|
| 287 | <p>Lists should be constructed as unordered (<UL> and <li> tags), |
|---|
| 288 | ordered (<ol> and <li> tags) or definition (<dl> and <DT> |
|---|
| 289 | tags) lists in HTML. You use an unordered list when you need a collection of |
|---|
| 290 | items that don't have any kind of logical ordering, such as a list of data types |
|---|
| 291 | that are defined by the library and can be used for a template argument. You |
|---|
| 292 | use an ordered list when the collection of items must be grouped in a logical |
|---|
| 293 | ordering, such as when enumerating the steps that an action logically performs. |
|---|
| 294 | You use a definition list when the list consists of not only items that have |
|---|
| 295 | no logical ordering, but also contains definitions/descriptions/etc. of the |
|---|
| 296 | items. A good example of this is the function specifications as described in |
|---|
| 297 | <a href="structure.html">Documentation Structure</a>.</p> |
|---|
| 298 | <h3><a name="graphics"></a>Graphics</h3> |
|---|
| 299 | <p>Graphics should be used very sparingly, if at all. Graphic images greatly effect |
|---|
| 300 | the download time for many people, which can discourage users from reading the |
|---|
| 301 | documentation. If you need graphic images to help illustrate something in your |
|---|
| 302 | documentation consider supplying only a link to the image within the documentation, |
|---|
| 303 | instead of embedding it directly in the text. If an image is going to be included |
|---|
| 304 | in the text of the document you should specify the image's size in the <img> |
|---|
| 305 | tag, in order to allow the user's browser to optimize the formatting of the |
|---|
| 306 | text before the image is loaded.</p> |
|---|
| 307 | <h3><a name="non-breaking-spaces"></a>Non-breaking Spaces</h3> |
|---|
| 308 | <p>Non-breaking spaces (&nbsp;) should be avoided in HTML text. Generally |
|---|
| 309 | there are more appropriate ways to format the document, such as using list constructs |
|---|
| 310 | or specifying indentation as a style attribute or in cascading style sheets.</p> |
|---|
| 311 | <h3><a name="style-sheets"></a>Cascading Style Sheets</h3> |
|---|
| 312 | <p>Cascading style sheets allow you to apply some advanced formatting styles to |
|---|
| 313 | an HTML document. More importantly, they allow you to change the formatting |
|---|
| 314 | in a single file and effect all pages using the style sheet. Instead of struggling |
|---|
| 315 | to produce a specific format in HTML it's often easier and more flexible to |
|---|
| 316 | specify the formatting in a style sheet.</p> |
|---|
| 317 | <h4><a name="boost-style-sheet"></a>Boost Style Sheet</h4> |
|---|
| 318 | <p>The concept of using cascading style sheets to format HTML is such a good idea |
|---|
| 319 | that it can be beneficial to apply this across the entire Boost site. Of course |
|---|
| 320 | we can't require this (if Boost were to require such trivia for submissions |
|---|
| 321 | it's likely that many programmers would be discouraged from contributing). However, |
|---|
| 322 | a "standard" Boost style sheet (http://www.boost.org/boost.css) is |
|---|
| 323 | supplied anyway, so that a contributer can quickly and easily produce clear |
|---|
| 324 | and consistent documentation that reflects a Boost "brand" if they |
|---|
| 325 | so choose. If, at a later date, it's decided to update the Boost "brand", |
|---|
| 326 | it may be done in this single file and all documents using the style sheet will |
|---|
| 327 | automatically be updated.</p> |
|---|
| 328 | <p>The Boost supplied style sheet not only specifies styles for many standard |
|---|
| 329 | tags, it also specifies several style "classes". A class is specified |
|---|
| 330 | for a given tag instead of being applied to all instances of a given tag type. |
|---|
| 331 | Below is a list of the classes specified in the Boost style sheet and a description |
|---|
| 332 | of when to use them:</p> |
|---|
| 333 | <dl> |
|---|
| 334 | <dt><b>index</b> Used for <dl> tags when writing index lists.</dt> |
|---|
| 335 | <dt><b>page-index</b> Used for <dl> tags when writing page index lists.</dt> |
|---|
| 336 | <dt><b>Footnote</b> Used when writing Footnote numbers.</dt> |
|---|
| 337 | <dt><b>function-semantics</b> Used for <dl> tags when writing function |
|---|
| 338 | semantic lists.</dt> |
|---|
| 339 | </dl> |
|---|
| 340 | <h2><a name="templates"></a>Templates</h2> |
|---|
| 341 | <p>Instead of hand coding every HTML page, HTML "templates" can be used instead. |
|---|
| 342 | The list below provides links to templates that may be used when writing documentation |
|---|
| 343 | for a contribution to Boost. Links provided in these templates assume the files |
|---|
| 344 | will reside in the "traditional" directory hierarchy of <i>boost/libs/library/doc</i>. |
|---|
| 345 | They may need correcting if the file will reside in some other location.</p> |
|---|
| 346 | <p><b>Note:</b> Since these "templates" are just HTML pages simply clicking |
|---|
| 347 | on the links below will load the template in your browser. You will need to |
|---|
| 348 | use a browser specific method to download the files instead of loading them |
|---|
| 349 | into the browser (for instance, on most Windows browsers you can right click |
|---|
| 350 | on the link and select the appropriate command from the context sensitive menu).</p> |
|---|
| 351 | <ul> |
|---|
| 352 | <li><a name="index-template"></a><a href="template/index.html">Index Page Template</a></li> |
|---|
| 353 | <li><a name="overview-template"></a><a href="template/overview.html">Overview |
|---|
| 354 | Page Template</a></li> |
|---|
| 355 | <li><a name="definitions-template"></a><a href="template/definitions.html">Definitions |
|---|
| 356 | Page Template</a></li> |
|---|
| 357 | <li><a name="rationale-template"></a><a href="template/rationale.html">Rationale |
|---|
| 358 | Page Template</a></li> |
|---|
| 359 | <li><a name="configuration-template"></a><a href="template/configuration.html">Configuration |
|---|
| 360 | Page Template</a></li> |
|---|
| 361 | <li><a name="faq-template"></a><a href="template/faq.html">FAQ (Frequently Asked |
|---|
| 362 | Questions) Page Template</a></li> |
|---|
| 363 | <li><a name="bibliography-template"></a><a href="template/bibliography.html">Bibliography |
|---|
| 364 | Page Template</a></li> |
|---|
| 365 | <li><a name="acknowledgements-template"></a><a href="template/acknowledgments.html">Acknowledgments |
|---|
| 366 | Page Template</a></li> |
|---|
| 367 | <li><a name="header-template"></a><a href="template/header.html">Header Page |
|---|
| 368 | Template</a></li> |
|---|
| 369 | </ul> |
|---|
| 370 | <hr> |
|---|
| 371 | <p>Revised |
|---|
| 372 | <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->29 November, 2003<!--webbot bot="Timestamp" endspan i-checksum="39371" --> |
|---|
| 373 | </p> |
|---|
| 374 | <p><i>© Copyright <a href="mailto:williamkempf@hotmail.com">William E. Kempf</a> |
|---|
| 375 | 2001. All Rights Reserved.</i></p> |
|---|
| 376 | </body> |
|---|
| 377 | </html> |
|---|
