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