More docs, better build.

[SVN r49858]
This commit is contained in:
John Maddock 2008-11-21 13:57:03 +00:00
parent 2cc16442de
commit a49b017c7a
6 changed files with 295 additions and 103 deletions

View File

@ -3,10 +3,12 @@
# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
using quickbook ;
#using auto_index ;
path-constant images_location : html ;
xml auto_index : auto_index.qbk ;
#autoindex index : auto_index ;
boostbook standalone
:
auto_index
@ -70,4 +72,5 @@ boostbook standalone
;
install pdf-install : standalone : <install-type>PDF <location>. ;

View File

@ -13,14 +13,14 @@
[section:overview Overview]
AutoIndex is a tool for taking the grunt work out of indexing a
Quickbook\/Boostbook\/Docbook document that describes C/C++ code.
Quickbook\/Boostbook\/Docbook document that describes C\/C++ code.
Traditionally, in order to index a Docbook document you would
have to manually add a large amount of `<indexterm>` markup:
in fact one `<indexterm>` for each occurance of each term to be
indexed.
Instead AutoIndex will scan one or more C/C++ header files
Instead AutoIndex will scan one or more C\/C++ header files
and extract all the ['function], ['class], ['macro] and ['typedef]
names that are defined by those headers, and then insert the
`<indexterm>`'s into the XML document for you.
@ -75,3 +75,129 @@ at the start of each Index:
[$../students_t_eg_4.png]
[endsect]
[section:tut Getting Started and Tutorial]
[h4 Step 1: Build the tool]
cd into `tools/auto_index/build` and invoke bjam as:
bjam release
Optionally pass the name of the compiler toolset you want to use to bjam as well:
bjam release gcc
[h4 Step 2: Configure Boost.Build]
TODO: we need BoostBook integration!!!
Currently the tool can only be run manually.
[h4 Step 3: Add indexes to your documentation]
To add a single index to a BoostBook\/Docbook document, then add
`<index/>` at the location where you want the index to appear. The
index will be rendered as a separate section when the documentation
is built.
To add multiple indexes, then give each one a title and set it's
`type` attribute to specify which terms will be included, for example
to place the ['function], ['class], ['macro] or ['typedef] names
indexed by ['auto_index] in separate indexes along with a main
"include everything" index as well, one could add:
<index type="class_name">
<title>Class Index</title>
</index>
<index type="typedef_name">
<title>Typedef Index</title>
</index>
<index type="function_name">
<title>Function Index</title>
</index>
<index type="macro_name">
<title>Macro Index</title>
</index>
<index/>
In quickbook, you add the same markup but enclose it in an escape:
'''<index/>'''
[h4 Step 4: Create the script file]
AutoIndex works by reading a script file that tells it what to index,
at it's simplest it will scan one or more headers for terms that
should be indexed in the documentation. So for example to scan
"myheader.hpp" the script file would just contain:
!scan myheader.hpp
Or we can recursively scan through directories looking for all
the files to scan whose name matches a particular regular expression:
!scan-path "../../../../boost/math" ".*\.hpp" true
Note how each argument is whitespace separated and can be optionally
enclosed in "double quotes". The final ['true] argument indicates
that subdirectories in `../../../../boost/math` should be searched
in addition to that directory.
Often the ['scan] or ['scan-path] rules will bring in too many terms
to search for, so we need to be able to exclude terms as well:
!exclude type
Which excludes the term "type" from being indexed.
We can also add terms manually:
foobar
will index occurances of "foobar" and:
foo bar
will index occurances of "foo" under the name "bar".
This inclusion rule can also restict the term to
certain sections, and add an index category that
the term should belong to (so it only appears in certain
indexes).
Finally the script can add rewrite rules, that rename section names
that are automatically used as index entries. For example we might
want to remove leading "A" or "The" prefixes from section titles
when AutoIndex uses them as an index entry:
!rewrite-name "(?i)(?:A|The)\s+(.*)" "\1"
[h4 Step 5: Iterate]
Creating a good index is an iterative process, often the first step is
just to add a header scanning rule to the script file and then generate
the documentation and see:
* What's missing.
* What's been included that shouldn't be.
* What's been included under a poor name.
Further rules can then be added to the script to handle these cases
and the next iteration examined, and so on.
[endsect]
[section:script_ref Script File Reference]
[endsect]
[section:comm_ref Command Line Reference]
[endsect]

View File

@ -7,6 +7,7 @@
<link rel="home" href="../index.html" title="AutoIndex">
<link rel="up" href="../index.html" title="AutoIndex">
<link rel="prev" href="../index.html" title="AutoIndex">
<link rel="next" href="tut.html" title="Getting Started and Tutorial">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
@ -19,7 +20,7 @@
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../index.html"><img src="../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/html/images/home.png" alt="Home"></a>
<a accesskey="p" href="../index.html"><img src="../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="tut.html"><img src="../../../doc/html/images/next.png" alt="Next"></a>
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
@ -68,7 +69,9 @@
for: often you'll get a few spurious entries, a few missing entries, and a
few entries where the section name used as an index entry is less than ideal.
So AutoIndex provides some powerful regular expression based rules that allow
you to add, remove, constrain, or rewrite entries.
you to add, remove, constrain, or rewrite entries. Normally just a few lines
in AutoIndex's script file are enough to tailor the output to match the authors
expectations.
</p>
<p>
AutoIndex also supports multiple indexes (as does Docbook), and since it knows
@ -94,7 +97,8 @@
<span class="inlinemediaobject"><img src="../../students_t_eg_3.png" alt="students_t_eg_3"></span>
</p>
<p>
There is also a navigation bar at the start of each Index:
With internal index generation there is also a helpful navigation bar at the
start of each Index:
</p>
<p>
<span class="inlinemediaobject"><img src="../../students_t_eg_4.png" alt="students_t_eg_4"></span>
@ -110,7 +114,7 @@
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../index.html"><img src="../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/html/images/home.png" alt="Home"></a>
<a accesskey="p" href="../index.html"><img src="../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="tut.html"><img src="../../../doc/html/images/next.png" alt="Next"></a>
</div>
</body>
</html>

View File

@ -2,18 +2,15 @@
Copyright (c) 2004 Joel de Guzman
http://spirit.sourceforge.net/
Use, modification and distribution is subject to the Boost Software
License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
http://www.boost.org/LICENSE_1_0.txt)
New syntax color Paul A. Bristow 8 Jun 2007
Distributed under the Boost Software License, Version 1.0. (See accompany-
ing file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
=============================================================================*/
/*=============================================================================
Body defaults
=============================================================================*/
body
body
{
margin: 1em;
font-family: sans-serif;
@ -23,10 +20,10 @@
Paragraphs
=============================================================================*/
p
p
{
text-align: left;
font-size: 10pt;
font-size: 10pt;
line-height: 1.15;
}
@ -47,7 +44,7 @@
padding: 0.5pc 0.5pc 0.5pc 0.5pc;
}
.programlisting,
.programlisting,
.screen
{
font-size: 9pt;
@ -57,7 +54,7 @@
}
/* Program listings in tables don't get borders */
td .programlisting,
td .programlisting,
td .screen
{
margin: 0pc 0pc 0pc 0pc;
@ -68,9 +65,9 @@
Headings
=============================================================================*/
h1, h2, h3, h4, h5, h6
{
text-align: left;
h1, h2, h3, h4, h5, h6
{
text-align: left;
margin: 1em 0em 0.5em 0em;
font-weight: bold;
}
@ -83,13 +80,13 @@
h6 { font: italic 100% }
/* Top page titles */
title,
h1.title,
title,
h1.title,
h2.title
h3.title,
h4.title,
h5.title,
h6.title,
h3.title,
h4.title,
h5.title,
h6.title,
.refentrytitle
{
font-weight: bold;
@ -103,7 +100,7 @@
h5.title { font-size: 110% }
h6.title { font-size: 100% }
.section h1
.section h1
{
margin: 0em 0em 0.5em 0em;
font-size: 140%;
@ -127,9 +124,9 @@
Author
=============================================================================*/
h3.author
{
font-size: 100%
h3.author
{
font-size: 100%
}
/*=============================================================================
@ -141,15 +138,15 @@
font-size: 10pt;
line-height: 1.3;
}
/* Unordered lists */
ul
ul
{
text-align: left;
}
/* Ordered lists */
ol
ol
{
text-align: left;
}
@ -162,7 +159,7 @@
{
text-decoration: none; /* no underline */
}
a:hover
{
text-decoration: underline;
@ -176,18 +173,33 @@
{
text-align: right;
}
.spirit-nav a
{
color: white;
padding-left: 0.5em;
}
.spirit-nav img
{
border-width: 0px;
}
/*=============================================================================
Copyright footer
=============================================================================*/
.copyright-footer
{
text-align: right;
font-size: 70%;
}
.copyright-footer p
{
text-align: right;
font-size: 80%;
}
/*=============================================================================
Table of contents
=============================================================================*/
@ -196,10 +208,10 @@
{
margin: 1pc 4% 0pc 4%;
padding: 0.1pc 1pc 0.1pc 1pc;
font-size: 80%;
font-size: 80%;
line-height: 1.15;
}
.boost-toc
{
float: right;
@ -210,30 +222,30 @@
Tables
=============================================================================*/
.table-title,
.table-title,
div.table p.title
{
margin-left: 4%;
padding-right: 0.5em;
padding-right: 0.5em;
padding-left: 0.5em;
}
.informaltable table,
.informaltable table,
.table table
{
width: 92%;
margin-left: 4%;
margin-right: 4%;
}
div.informaltable table,
div.informaltable table,
div.table table
{
padding: 4px;
}
/* Table Cells */
div.informaltable table tr td,
div.informaltable table tr td,
div.table table tr td
{
padding: 0.5em;
@ -241,7 +253,7 @@
font-size: 9pt;
}
div.informaltable table tr th,
div.informaltable table tr th,
div.table table tr th
{
padding: 0.5em 0.5em 0.5em 0.5em;
@ -249,6 +261,22 @@
font-size: 80%;
}
table.simplelist
{
width: auto !important;
margin: 0em !important;
padding: 0em !important;
border: none !important;
}
table.simplelist td
{
margin: 0em !important;
padding: 0em !important;
text-align: left !important;
font-size: 9pt !important;
border: none !important;
}
/*=============================================================================
Blurbs
=============================================================================*/
@ -266,7 +294,7 @@
margin: 1pc 4% 0pc 4%;
padding: 0.5pc 0.5pc 0.5pc 0.5pc;
}
p.blurb img
{
padding: 1pt;
@ -344,12 +372,16 @@
@media screen
{
body {
background-color: #FFFFFF;
}
/* Links */
a
{
color: #005a9c;
}
a:visited
{
color: #9c5a9c;
@ -362,24 +394,9 @@
text-decoration: none; /* no underline */
color: #000000;
}
/* New Syntax Highlighting
using Recognized color keyword names, for example:
http://www.w3.org/TR/SVG/types.html see section 4.2
*/
.keyword { color: blue; }
.identifier { color: black; }
.special { color: magenta; }
.preprocessor { color: blueviolet; }
.char { color: teal; }
.comment { color: green; }
.string { color: teal; }
.number { color: red; }
.white_bkd { background-color: white; }
.dk_grey_bkd { background-color: dimgray; }
/* Original Syntax Highlighting
.keyword { color: blue; }
/* Syntax Highlighting */
.keyword { color: #0000AA; }
.identifier { color: #000000; }
.special { color: #707070; }
.preprocessor { color: #402080; }
@ -389,37 +406,37 @@
.number { color: teal; }
.white_bkd { background-color: #FFFFFF; }
.dk_grey_bkd { background-color: #999999; }
*/
/* Copyright, Legal Notice */
.copyright
{
color: #666666;
font-size: small;
.copyright
{
color: #666666;
font-size: small;
}
div div.legalnotice p
{
color: #666666;
}
/* Program listing */
pre.synopsis
{
border: 1px solid #DCDCDC;
}
.programlisting,
.programlisting,
.screen
{
border: 1px solid #DCDCDC;
}
td .programlisting,
td .programlisting,
td .screen
{
border: 0px solid #DCDCDC;
}
/* Blurbs */
div.note,
div.tip,
@ -430,34 +447,39 @@
{
border: 1px solid #DCDCDC;
}
/* Table of contents */
.toc
{
border: 1px solid #DCDCDC;
}
/* Tables */
div.informaltable table tr td,
div.informaltable table tr td,
div.table table tr td
{
border: 1px solid #DCDCDC;
}
div.informaltable table tr th,
div.informaltable table tr th,
div.table table tr th
{
background-color: #F0F0F0;
border: 1px solid #DCDCDC;
}
.copyright-footer
{
color: #8F8F8F;
}
/* Misc */
span.highlight
{
color: #00A000;
}
}
@media print
{
/* Links */
@ -465,61 +487,66 @@
{
color: black;
}
a:visited
{
color: black;
}
.spirit-nav
{
display: none;
}
/* Program listing */
pre.synopsis
{
border: 1px solid gray;
}
.programlisting,
.programlisting,
.screen
{
border: 1px solid gray;
}
td .programlisting,
td .programlisting,
td .screen
{
border: 0px solid #DCDCDC;
}
/* Table of contents */
.toc
{
border: 1px solid gray;
}
.informaltable table,
.informaltable table,
.table table
{
border: 1px solid gray;
border-collapse: collapse;
}
/* Tables */
div.informaltable table tr td,
div.informaltable table tr td,
div.table table tr td
{
border: 1px solid gray;
}
div.informaltable table tr th,
div.informaltable table tr th,
div.table table tr th
{
border: 1px solid gray;
}
table.simplelist tr td
{
border: none !important;
}
/* Misc */
span.highlight
{
@ -536,3 +563,26 @@
vertical-align: middle;
}
/*==============================================================================
Super and Subscript: style so that line spacing isn't effected, see
http://www.adobe.com/cfusion/communityengine/index.cfm?event=showdetails&productId=1&postId=5341
==============================================================================*/
sup,
sub {
height: 0;
line-height: 1;
vertical-align: baseline;
_vertical-align: bottom;
position: relative;
}
sup {
bottom: 1ex;
}
sub {
top: .5ex;
}

View File

@ -38,11 +38,14 @@
</div>
<div class="toc">
<p><b>Table of Contents</b></p>
<dl><dt><span class="section"><a href="autoindex/overview.html"> Overview</a></span></dt></dl>
<dl>
<dt><span class="section"><a href="autoindex/overview.html"> Overview</a></span></dt>
<dt><span class="section"><a href="autoindex/tut.html"> Getting Started and Tutorial</a></span></dt>
</dl>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"><p><small>Last revised: November 20, 2008 at 18:04:26 GMT</small></p></td>
<td align="left"><p><small>Last revised: November 21, 2008 at 13:52:42 GMT</small></p></td>
<td align="right"><div class="copyright-footer"></div></td>
</tr></table>
<hr>

View File

@ -1,5 +1,11 @@
/*============================================================================
Copyright 2003-2004 Douglas Gregor
Distributed under the Boost Software License, Version 1.0. (See accompany-
ing file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
============================================================================*/
PRE.synopsis {
background-color: #e0ffff;
border: thin solid blue;
padding: 1em
}
}