|
+ |
+
+ Writing Documentation for Boost+HTML Design+ |
+
Boost places no requirements on the design of HTML documentation for library + submitters. If you are submitting a library for which documentation already + exists in either HTML or in a form easily converted to HTML then there is no + need for you to read this document. However, if you have not yet written the + documentation, or if you expect to have to translate documentation written in + a format not easily convertible to HTML then this document can give you a lot + of information on how to go about writing documentation in HTML.
+In several places this document assumes you're writing the documentation to + conform to the structure described in the Documentation + Structure document. There is no requirement that your documentation content + follow these guidelines, but they provide an effective way to communicate technical + specifications for a library in a terse yet precise manner that's familiar to + many Boost users.
+This document also contains links to HTML template files + that can be used to rapidly develop documentation for a library submission. + These templates follow the guidelines presented here and in the Documentation + Structure document.
+Most HTML documentation projects will contain some common pages. General guidelines + for these common pages are provided below.
+The index page is the first page presented to a user when he browses the documentation. + Generally this page should not contain any actual content, but instead contains + a list of links to specific content. At a minimum this list should contain a + link to every HTML page contained in the documentation. Optionally, sub-lists + may be provided for individual pages linking to specific subjects within the + page. These sub-lists should form a "tree" hierarchy based on the + level of heading tag used for the specific subject. Inclusion of such sub-lists + for every page can make the index rather lengthy, and since each page should + include its own Page Index, it may make the navigation + of the documentation easier if such sub-lists are avoided. However, there is + one exception to this guideline: reference documentation should contain a link + to every header file in the library and a sub-list with a link to every macro, + value, type, class, function and object (see Documentation + Structure) found in the header. Users aren't always sure what header file + any of these may be contained in, so this structure in the index allows for + easy navigation of the reference documentation.
+The index list should generally be constructed using an HTML "definition
+ list" (<dl> and <dt> tags). A definition list has no bullets
+ or ordered specifications and produces a cleaner layout then an unordered list
+ (<ul> and <li> tags) or an ordered list (<ol> and <li>
+ tags). If you choose to use the common Boost Style
+ Sheet you should add a class="index" attribute/value pair to
+ the <dl> tag.
An Index page template is provided for use.
+The Overview page is used to introduce the reader to the library. It should + give a high-level overview of the purpose of the library and introduce the reader + to any concepts they may be unfamiliar with. This may also be an appropriate + place for some "light" rationale, though more thorough presentation + of any rationale would be better placed in the Rational + Page.
+Like most content pages, the Overview page should include a Page + Index.
+An Overview page template is provided for + use.
+The Definitions page is used to provide a list of definitions for terms that + a user may be unfamiliar with.
+The definition list should generally be constructed using an HTML "definition
+ list" (<dl> and <DT> tags). A definition list has no bullets
+ or ordered specifications and produces a cleaner layout then an unordered list
+ (<UL> and <li> tags) or an ordered list (<ol> and <li>
+ tags). If you choose to use the common Boost Style
+ Sheet you should add a class="definition" attribute/value pair
+ to the <dl> tag.
Because this page's content should only contain a list of definitions, it should + not have a Page Index.
+ +A Definitions page template is provided + for use.
+The Rationale page is used to provide lengthy descriptions of the rationale + behind the library's design. This information helps users to understand why + a library was designed the way it was and may reduce the frequency of a number + of frequently asked questions. For a better description of why rationale is + important see the Rationale + rationale in the general submission guidelines.
+Like most content pages, the Rationale page should include a Page + Index.
+ +A Rationale page template is provided for + use.
+The Configuration Information page is used to document configuration macros
+ used by the library. Such macros belong in one of three groups: macros used
+ by library implenters defined in <boost/config.hpp>, macros
+ used by library users to detect platform configuration information and macros
+ defined by library users to configure library behavior.
Like most content pages, the Overview page should include a Page + Index.
+ +A Configuration page template is provided + for use.
+As a library matures the users will have questions about the usage of the library. + Often users will ask the same questions over and over again. Rather than having + to deal with answering the question every time it's asked, a Frequently Asked + Questions (commonly known as FAQs) page can be used to document the questions + and answers. This is such a valuable piece of documentation not only for the + users but for the maintainers as well, that a FAQ page should be provided from + the outset. If there are no questions that will obviously become a FAQ, the + initial page may just indicate that there are no FAQs yet. This empty place + holder helps to indicate to the users that you plan to address any FAQs as they + occur.
+The Page Index for the FAQ page should contain a + list of all the questions contained in the document. The actual question entries + should be formatted with the question in a heading tag and the answers in standard + paragraph format. This provides a clean presentation that's easy to read.
+A Frequently Asked Questions page template is provided + for use.
+The Bibliography page is used to document any bibliographical information associated + with references made within the documentation to external resources. Parenthetical + references are used within the documentation which link to entries in the Bibliography + page. Bibliographical entries provide detailed information about the external + resource and may contain hyper links to the resource if it's available online. + There are several formal styles used for writing bibliographies. You may use + what ever style you want, but one of the better styles to consider using can + be referenced here.
+Since the Bibliography page should contain only bibliographical information + there is no need for a Page Index.
+A Bibliography page template is provided + for use.
+The Acknowledgment page is used to give credit where credit is due. When individuals + provide input on the design or implementation, or when you make use of someone + else's work, you should acknowledge them. This is a courtesy that you'd expect + others to extend to you, so you should strive to acknowledge the efforts of + everyone else in your own documentation.
+Since the Acknowledgment page should contain only a list of acknowledgment + there is no need for a Page Index.
+An Acknowledgments page template is + provided for use.
+The Header Reference pages are the most important pages in your documentation. + They document all library headers, including all the macros, values, types, + classes, functions and objects defined in them. In general it may prove useful + to follow the guidelines in Documentation Structure + when writing the content for these pages.
+Like most content pages, the Header Reference pages should include a Page + Index.
+A Header Reference page template is provided + for use.
+There are certain page layout concepts that will be used frequently in many + of your pages. This section outlines some general guidelines that you can follow + when designing each of these layout concepts for your documentation.
+The Page Banner is located at the very top of a page and provides quick information + about the page contents. This includes the Boost logo, which indicates to the + reader that this page is part of the Boost web site, a title for the documentation + (generally the library name) and the page title. The Boost logo should hyper + link to the Boost home page on the index page and to the index page on all other + pages. This allows the user to easily navigate through the Boost web site and + through the documentation. The <title> tag for the HTML page should consist + of the documentation title and the page title separated by a hyphen.
+The Page Banner should be separated from the rest of the page by the use of + an <hr> tag. This helps to clearly separate the actual content from the + title information and produces cleaner text.
+The page index is used to quickly navigate to the various sections of the documentation + on the page, and when present should be located just below the Page Banner.
+The index list should generally be constructed using an HTML "definition
+ list" (<dl> and <DT> tags). A definition list has no bullets
+ or ordered specifications and produces a cleaner layout then an unordered list
+ (<UL> and <li> tags) or an ordered list (<ol> and <li>
+ tags). If you choose to use the Boost Style Sheet you should add a class="page-index"
+ attribute/value pair to the <dl> tag.
Most pages should include a Page Index.
+The page's actual documentation content will be formatted according to the + specific needs of individual pages, and should be placed right after the Page + Index if present, or after the Page Banner if not. In general the documentation + content will take the form of paragraph text contained underneath section headings.
+Footnotes may be used within a page's documentation. Within the documentation
+ content a footnote reference should take the form of a footnote number in parentheses
+ (the parentheses make it easier for the reader to click on the hyper link) hyper
+ linking to the actual footnote at the bottom of the page's documentation content.
+ You may either use the <sup> tag to format such footnote numbers, or,
+ preferably, you can use a CSS style class in order to distinguish the number
+ as a footnote instead of as part of the actual text. If you choose to use the
+ common Boost Style Sheet, a footnote
+ class is defined for this purpose.
At the bottom of every page should be some revision information indicating + when the page was last revised. This information should be separated from the + rest of the page above by an <hr> tag. The following HTML code snippet + can be used to track this revision information (this code uses some server components + that exist on the Boost web site to automatically track revision dates with + out the need for hand editing the date text):
+<hr> +<p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 01 January, 2001 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> +</p> ++
The very bottom of the page should contain any copyright information that applies + to the document.
+This section provides general guidelines for formatting documentation using + HTML. The description of the various "common pages" gave specific + details for formatting specific sections of the documentation, which should + override these guidelines.
+Code within the documentation should be placed within either <code></code> + or <pre></pre> tags. For code that's placed inline with other text + you use <code></code> tags, while <pre></pre> tags are + used for code "blocks". If a cascading style sheet is used to specify + formatting for these tags, a fixed width sans serif font should be used. This + insures that the code is easily distinguishable from the rest of the text. It + may also be beneficial to set the style for <pre></pre> tags to + indent the text, to help separate code blocks from other structural HTML blocks. + The Boost Style Sheet specifies formatting + for these tags.
+Note: "Code" includes variable names, function names, etc.
+Lists should be constructed as unordered (<UL> and <li> tags), + ordered (<ol> and <li> tags) or definition (<dl> and <DT> + tags) lists in HTML. You use an unordered list when you need a collection of + items that don't have any kind of logical ordering, such as a list of data types + that are defined by the library and can be used for a template argument. You + use an ordered list when the collection of items must be grouped in a logical + ordering, such as when enumerating the steps that an action logically performs. + You use a definition list when the list consists of not only items that have + no logical ordering, but also contains definitions/descriptions/etc. of the + items. A good example of this is the function specifications as described in + Documentation Structure.
+Graphics should be used very sparingly, if at all. Graphic images greatly effect + the download time for many people, which can discourage users from reading the + documentation. If you need graphic images to help illustrate something in your + documentation consider supplying only a link to the image within the documentation, + instead of embedding it directly in the text. If an image is going to be included + in the text of the document you should specify the image's size in the <img> + tag, in order to allow the user's browser to optimize the formatting of the + text before the image is loaded.
+Non-breaking spaces ( ) should be avoided in HTML text. Generally + there are more appropriate ways to format the document, such as using list constructs + or specifying indentation as a style attribute or in cascading style sheets.
+Cascading style sheets allow you to apply some advanced formatting styles to + an HTML document. More importantly, they allow you to change the formatting + in a single file and effect all pages using the style sheet. Instead of struggling + to produce a specific format in HTML it's often easier and more flexible to + specify the formatting in a style sheet.
+The concept of using cascading style sheets to format HTML is such a good idea + that it can be beneficial to apply this across the entire Boost site. Of course + we can't require this (if Boost were to require such trivia for submissions + it's likely that many programmers would be discouraged from contributing). However, + a "standard" Boost style sheet (http://www.boost.org/boost.css) is + supplied anyway, so that a contributer can quickly and easily produce clear + and consistent documentation that reflects a Boost "brand" if they + so choose. If, at a later date, it's decided to update the Boost "brand", + it may be done in this single file and all documents using the style sheet will + automatically be updated.
+The Boost supplied style sheet not only specifies styles for many standard + tags, it also specifies several style "classes". A class is specified + for a given tag instead of being applied to all instances of a given tag type. + Below is a list of the classes specified in the Boost style sheet and a description + of when to use them:
+Instead of hand coding every HTML page, HTML "templates" can be used instead. + The list below provides links to templates that may be used when writing documentation + for a contribution to Boost. Links provided in these templates assume the files + will reside in the "traditional" directory hierarchy of boost/libs/library/doc. + They may need correcting if the file will reside in some other location.
+Note: Since these "templates" are just HTML pages simply clicking + on the links below will load the template in your browser. You will need to + use a browser specific method to download the files instead of loading them + into the browser (for instance, on most Windows browsers you can right click + on the link and select the appropriate command from the context sensitive menu).
+Revised + + 05 November, 2001 + +
+© Copyright William E. Kempf + 2001. All Rights Reserved.
+ + diff --git a/writingdoc/index.html b/writingdoc/index.html new file mode 100644 index 0000000..0753496 --- /dev/null +++ b/writingdoc/index.html @@ -0,0 +1,36 @@ + + + + +|
+ |
+
+ Writing Documentation for Boost+Index+ |
+
Revised + + 05 November, 2001 + +
+© Copyright William E. Kempf + 2001. All Rights Reserved.
+ + diff --git a/writingdoc/introduction.html b/writingdoc/introduction.html new file mode 100644 index 0000000..896aa7b --- /dev/null +++ b/writingdoc/introduction.html @@ -0,0 +1,48 @@ + + + + +|
+ |
+
+ Writing Documentation for Boost+Introduction+ |
+
Boost does not have any requirements on how you write your documentation. If + you are submitting a library that already has written documentation in HTML + format, there is no reason to change it to follow any of the guidelines presented + here. However, if you have documentation that's not in HTML format and can't + be easily converted to HTML, or if you're starting on a library from scratch + or have a library with no documentation then these guidelines can make writing + the documentation much easier.
+The section on Documentation Structure describes + how to go about structuring the documentation's content. This section may be + helpful even for libraries that already have documentation. If there's a desire + to present the library for possible inclusion by the C++ Standards Committee + then there may be a need to restructure the documentation's content in order + to insure the content meets explicit requirements for library components (Section + 17.3).
+The section on HTML Design gives general rules to + follow when writing HTML documentation in order to give a professional and consistent + look. This section also contains some template files that can be used to rapidly + create documentation pages.
+Revised + + 05 November, 2001 + +
+© Copyright William E. Kempf + 2001. All Rights Reserved.
+ + diff --git a/writingdoc/structure.html b/writingdoc/structure.html new file mode 100644 index 0000000..8d85561 --- /dev/null +++ b/writingdoc/structure.html @@ -0,0 +1,257 @@ + + + + +|
+ |
+
+ Writing Documentation for Boost+Documentation Structure+ |
+
Boost itself does not require any specific documentation structure. The C++ + Standard, however, has very explicit requirements for the description of library + components (Section 17.3). So for Boost libraries likely to be proposed for + inclusion in the standard, it is highly desirable to structure documentation + in a way that meets the requirements of the the standard. Doing so eliminates + the need to rewrite the documentation for standardization.
+Library developers should remember that for a library to be accepted as part + of the C++ Standard Library, the proposal must include full wording. The committee + will not do that work for you.
+Beyond that, the documentation structure required for the standard is an effective + way to communicate the technical specifications for a library. Although terse, + it is already familiar to many Boost users, and is far more precise than most + ad hoc documentation structures.
+The following description is for the structure of documentation required by + the standard. Boost libraries should also provided additional documentation, + such as introductory, tutorial, example, and rationale material.
+Each document contains the following elements, as applicable(1):
+The Summary provides a synopsis of the category, and introduces the first-level + subclauses. Each subclause also provides a summary, listing the headers specified + in the subclause and the library entities provided in each header.
+Paragraphs labeled "Note(s):" or "Example(s):" are informative, other paragraphs + are normative.
+The summary and the detailed specifications are presented in the order:
+The library can be extended by a C++ program. Each clause, as applicable, describes + the requirements that such extensions must meet. Such extensions are generally + one of the following:
+Interface convention requirements are stated as generally as possible. Instead
+ of stating "class X has to define a member function operator++(),"
+ the interface requires "for any object x of class X,
+ ++x is defined." That is, whether the operator is a member is unspecified.
Requirements are stated in terms of well-defined expressions, which define + valid terms of the types that satisfy the requirements. For every set of requirements + there is a table that specifies an initial set of the valid expressions and + their semantics. Any generic algorithm that uses the requirements is described + in terms of the valid expressions for its formal type parameters.
+Template argument requirements are sometimes referenced by name.
+In some cases the semantic requirements are presented as C++ code. Such code + is intended as a specification of equivalance of a construct to another construct, + not necessarily as the way the construct must be implemented.(2)
+The detailed specifications each contain the following elements:
+Descriptions of class member functions follow the order (as appropriate)(3):
+Descriptions of function semantics contain the following elements + (as appropriate)(4):
+Complexity requirements specified in the library clauses are upper bounds, + and implementations that provide better complexity guarantees satisfy the requirements.
+These conventions are for describing implementation-defined types, and member + functions.
+The Requirements subclauses may describe names that are used to specify constraints + on template arguments.
+The function semantic element description above + is taken directly from the C++ standard, and is quite terse. Here is a more + detailed explanation of each of the elements.
+Note the use of the <code> ... </code> font tag to
+ distinguish actual C++ usage from English prose.
Preconditions for calling the function, typically expressed as predicates. + The most common preconditions are requirements on the value of arguments, often + in the form of C++ expressions. For example, +
+void limit( int * p, int min, int max );
+
+p != 0 && min <= maxRequirements already enforced by the C++ language rules (such as the type of + arguments) are not repeated in Requires paragraphs.
+The actions performed by the function, described either in prose or in C++. + A description in prose is often less limiting on implementors, but is often + less precise than C++ code.
+If an effect is specified in one of the other elements, particularly postconditions, + returns, or throws, it is not also described in the effects + paragraph. Having only a single description ensures that there is one and only + one specification, and thus eliminates the risk of divergence.
+The observable results of the function, such as the value of variables. Postconditions + are often expressed as predicates that are true after the function completes, + in the form of C++ expressions. For example:
++void make_zero_if_negative( int & x ); ++
x >= 0The value returned by the function, usually in the form of a C++ expression. + For example:
++int sum( int x, int y ); ++
x + yOnly specify the return value; the type is already dictated by C++ language + rules. +
Specify both the type of exception thrown, and the condition that causes the
+ exception to be thrown. For example, the std::basic_string class
+ specifies:
+
+void resize(size_type n, charT c); ++
length_error if n > max_size().Specifying the time and/or space complexity of a function is often not desirable + because it over-constrains implementors and is hard to specify correctly. Complexity + is thus often best left as a quality of implementation issue.
+A library component, however, can become effectively non-portable if there + is wide variation in performance between conforming implementations. Containers + are a prime example. In these cases it becomes worthwhile to specify complexity.
+Complexity is often specified in generalized + "Big-O" notation.
+Specifying the rationale for a function's design or existence can often give users + a lot of insight into why a library is designed the way it is. More importantly, it + can help prevent "fixing" something that wasn't really broken as the library matures.
+Revised + + 05 November, 2001 + +
+© Copyright William E. Kempf + 2001. All Rights Reserved.
+ + diff --git a/writingdoc/template/acknowledgments.html b/writingdoc/template/acknowledgments.html new file mode 100644 index 0000000..18c7453 --- /dev/null +++ b/writingdoc/template/acknowledgments.html @@ -0,0 +1,31 @@ + + + + +|
+ |
+
+ {{Library}}+Acknowledgments+ |
+
Revised + + 05 November, 2001 + +
+© Copyright {{author}} + 2002. All Rights Reserved.
+ + diff --git a/writingdoc/template/bibliography.html b/writingdoc/template/bibliography.html new file mode 100644 index 0000000..9cff452 --- /dev/null +++ b/writingdoc/template/bibliography.html @@ -0,0 +1,31 @@ + + + + +|
+ |
+
+ {{Library}}+Bibliography+ |
+
Revised + + 05 November, 2001 + +
+© Copyright {{author}} + 2002. All Rights Reserved.
+ + diff --git a/writingdoc/template/configuration.html b/writingdoc/template/configuration.html new file mode 100644 index 0000000..d8f4e26 --- /dev/null +++ b/writingdoc/template/configuration.html @@ -0,0 +1,90 @@ + + + + +|
+ |
+
+ {{Library}}+Configuration+ |
+
{{library}} uses several configuration macros in <boost/config.hpp>, + as well as configuration macros meant to be supplied by the application. These + macros are documented here.
+These are the macros that may be defined by an application using {{library}}.
+| Macro | +Meaning | +
| {{macro}} | +{{meaning}} | +
| {{macro}} | +{{meaning}} | +
These macros are defined by {{library}} but are expected to be used by application + code.
+| Macro | +Meaning | +
| {{macro}} | +{{meaning}} | +
| {{macro}} | +{{meaning}} | +
These macros are defined by {{library}} and are implementation details of interest + only to implementers.
+| Macro | +Meaning | +
| {{macro}} | +{{meaning}} | +
| {{macro}} | +{{meaning}} | +
Revised + + 05 November, 2001 + +
+© Copyright {{author}} + 2002. All Rights Reserved.
+ + diff --git a/writingdoc/template/definitions.html b/writingdoc/template/definitions.html new file mode 100644 index 0000000..557fb38 --- /dev/null +++ b/writingdoc/template/definitions.html @@ -0,0 +1,34 @@ + + + + +|
+ |
+
+ {{Library}}+Definitions+ |
+
Revised + + 05 November, 2001 + +
+© Copyright {{author}} + 2002. All Rights Reserved.
+ + diff --git a/writingdoc/template/faq.html b/writingdoc/template/faq.html new file mode 100644 index 0000000..62da4bb --- /dev/null +++ b/writingdoc/template/faq.html @@ -0,0 +1,38 @@ + + + + +|
+ |
+
+ {{Library}}+Frequently Asked Questions (FAQs)+ |
+
{{answer}}
+{{answer}}
+Revised + + 05 November, 2001 + +
+© Copyright {{author}} + 2002. All Rights Reserved.
+ + diff --git a/writingdoc/template/header.html b/writingdoc/template/header.html new file mode 100644 index 0000000..435dec9 --- /dev/null +++ b/writingdoc/template/header.html @@ -0,0 +1,181 @@ + + + + +|
+ |
+
+ {{library}}+Header <{{header}}>+ |
+
{{class name}}{{Introductory text}}
+{{name}}{{class overview text}}
+
+namespace boost
+{
+ class {{name}}
+ {
+ };
+};
+
+
+{{constructor}}
+
+
+{{destructor}}
+
+
+{{function}}
+
+
+{{function}}
+
+
+{{function}}
+
+
+{{function}}
+
++{{function}} ++
{{Example(s)}}
+Revised + + 05 November, 2001 + +
+© Copyright {{author}} + 2002. All Rights Reserved.
+ + diff --git a/writingdoc/template/index.html b/writingdoc/template/index.html new file mode 100644 index 0000000..25ba901 --- /dev/null +++ b/writingdoc/template/index.html @@ -0,0 +1,70 @@ + + + + +|
+ |
+
+ {{Library}}+Index+ |
+
Revised + + 05 November, 2001 + +
+© Copyright {{author}} + 2002. All Rights Reserved.
+ + diff --git a/writingdoc/template/overview.html b/writingdoc/template/overview.html new file mode 100644 index 0000000..efa9f72 --- /dev/null +++ b/writingdoc/template/overview.html @@ -0,0 +1,47 @@ + + + + +|
+ |
+
+ {{Library}}+Overview+ |
+
{{text}}
+{{text}}
+{{text}}
+Revised + + 05 November, 2001 + +
+© Copyright {{author}} + 2002. All Rights Reserved.
+ + diff --git a/writingdoc/template/rationale.html b/writingdoc/template/rationale.html new file mode 100644 index 0000000..b41b466 --- /dev/null +++ b/writingdoc/template/rationale.html @@ -0,0 +1,47 @@ + + + + +|
+ |
+
+ {{Library}}+Rationale+ |
+
{{text}}
+{{text}}
+{{text}}
+Revised + + 05 November, 2001 + +
+© Copyright {{author}} + 2002. All Rights Reserved.
+ +