|
|
Boost-Commit : |
Subject: [Boost-commit] svn:boost r49858 - in sandbox/tools/auto_index/doc: . html html/autoindex
From: john_at_[hidden]
Date: 2008-11-21 08:57:04
Author: johnmaddock
Date: 2008-11-21 08:57:03 EST (Fri, 21 Nov 2008)
New Revision: 49858
URL: http://svn.boost.org/trac/boost/changeset/49858
Log:
More docs, better build.
Text files modified:
sandbox/tools/auto_index/doc/Jamfile.v2 | 3
sandbox/tools/auto_index/doc/auto_index.qbk | 130 +++++++++++++++++++++
sandbox/tools/auto_index/doc/html/autoindex/overview.html | 12 +
sandbox/tools/auto_index/doc/html/boostbook.css | 238 ++++++++++++++++++++++++---------------
sandbox/tools/auto_index/doc/html/index.html | 7
sandbox/tools/auto_index/doc/html/reference.css | 8 +
6 files changed, 295 insertions(+), 103 deletions(-)
Modified: sandbox/tools/auto_index/doc/Jamfile.v2
==============================================================================
--- sandbox/tools/auto_index/doc/Jamfile.v2 (original)
+++ sandbox/tools/auto_index/doc/Jamfile.v2 2008-11-21 08:57:03 EST (Fri, 21 Nov 2008)
@@ -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 @@
;
+install pdf-install : standalone : <install-type>PDF <location>. ;
Modified: sandbox/tools/auto_index/doc/auto_index.qbk
==============================================================================
--- sandbox/tools/auto_index/doc/auto_index.qbk (original)
+++ sandbox/tools/auto_index/doc/auto_index.qbk 2008-11-21 08:57:03 EST (Fri, 21 Nov 2008)
@@ -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 @@
[$../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]
+
Modified: sandbox/tools/auto_index/doc/html/autoindex/overview.html
==============================================================================
--- sandbox/tools/auto_index/doc/html/autoindex/overview.html (original)
+++ sandbox/tools/auto_index/doc/html/autoindex/overview.html 2008-11-21 08:57:03 EST (Fri, 21 Nov 2008)
@@ -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>
Modified: sandbox/tools/auto_index/doc/html/boostbook.css
==============================================================================
--- sandbox/tools/auto_index/doc/html/boostbook.css (original)
+++ sandbox/tools/auto_index/doc/html/boostbook.css 2008-11-21 08:57:03 EST (Fri, 21 Nov 2008)
@@ -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,19 +173,34 @@
{
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;
+}
+
Modified: sandbox/tools/auto_index/doc/html/index.html
==============================================================================
--- sandbox/tools/auto_index/doc/html/index.html (original)
+++ sandbox/tools/auto_index/doc/html/index.html 2008-11-21 08:57:03 EST (Fri, 21 Nov 2008)
@@ -38,11 +38,14 @@
</div>
<div class="toc">
<p><b>Table of Contents</b></p>
-<dl><dt><span class="section"> Overview</span></dt></dl>
+<dl>
+<dt><span class="section"> Overview</span></dt>
+<dt><span class="section"> Getting Started and Tutorial</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>
Modified: sandbox/tools/auto_index/doc/html/reference.css
==============================================================================
--- sandbox/tools/auto_index/doc/html/reference.css (original)
+++ sandbox/tools/auto_index/doc/html/reference.css 2008-11-21 08:57:03 EST (Fri, 21 Nov 2008)
@@ -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
-}
+}
\ No newline at end of file
Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk