[ceph.git] / ceph / src / boost / tools / auto_index / doc / html / boost_autoindex / overview.html

<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Overview</title>
<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.77.1">
<link rel="home" href="../index.html" title="Boost.AutoIndex">
<link rel="up" href="../index.html" title="Boost.AutoIndex">
<link rel="prev" href="../index.html" title="Boost.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>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
<td align="center"><a href="../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../index.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="tut.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="boost_autoindex.overview"></a><a class="link" href="overview.html" title="Overview">Overview</a>
</h2></div></div></div>
<p>
      AutoIndex is a tool for taking the grunt work out of indexing a Boostbook/Docbook
      document (perhaps generated by your Quickbook file mylibrary.qbk, and perhaps
      using also Doxygen autodoc) that describes C/C++ code.
    </p>
<p>
      Traditionally, in order to index a Docbook document you would have to manually
      add a large amount of <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">indexterm</span><span class="special">&gt;</span></code> markup: in fact one <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">indexterm</span><span class="special">&gt;</span></code>
      for each occurrence of each term to be indexed.
    </p>
<p>
      Instead AutoIndex will automatically scan one or more C/C++ header files and
      extract all the <span class="emphasis"><em>function</em></span>, <span class="emphasis"><em>class</em></span>,
      <span class="emphasis"><em>macro</em></span> and <span class="emphasis"><em>typedef</em></span> names that are
      defined by those headers, and then insert the <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">indexterm</span><span class="special">&gt;</span></code>s
      into the Docbook XML document for you.
    </p>
<p>
      AutoIndex can also scan using a list of index terms specified in a script file,
      for example index.idx. These manually provided terms can optionally be regular
      expressions, and may allow the user to find references to terms that may not
      occur in the C++ header files. Of course providing a manual list of search
      terms in to index is a tedious task (especially handling plurals and variants),
      and requires enough knowledge of the library to guess what users may be seeking
      to know, but at least the real 'grunt work' of finding the term and listing
      the page number is automated.
    </p>
<p>
      AutoIndex creates index entries as follows:
    </p>
<p>
      for each occurrence of each search term, it creates two index entries:
    </p>
<div class="orderedlist"><ol class="orderedlist" type="1">
<li class="listitem">
          The search term as the <span class="emphasis"><em>primary index key</em></span> and the
          <span class="emphasis"><em>title of the section it appears in</em></span> as a subterm.
        </li>
<li class="listitem">
          The section title as the main index entry and the search term as the subentry.
        </li>
</ol></div>
<p>
      Thus the user has two chances to find what they're looking for, based upon
      either the section name or the <span class="emphasis"><em>function</em></span>, <span class="emphasis"><em>class</em></span>,
      <span class="emphasis"><em>macro</em></span> or <span class="emphasis"><em>typedef</em></span> name.
    </p>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
        This behaviour can be changed so that only one index entry is created (using
        the search term as the key and not using the section name except as a sub-entry
        of the search term).
      </p></td></tr>
</table></div>
<p>
      So for example in Boost.Math the class name <code class="computeroutput"><span class="identifier">students_t_distribution</span></code>
      has a primary entry that lists all sections the class name appears in:
    </p>
<p>
      <span class="inlinemediaobject"><img src="../../students_t_eg_1.png" alt="students_t_eg_1"></span>
    </p>
<p>
      Then those sections also have primary entries, which list all the search terms
      those sections contain:
    </p>
<p>
      <span class="inlinemediaobject"><img src="../../students_t_eg_2.png" alt="students_t_eg_2"></span>
    </p>
<p>
      Of course these automated index entries may not be quite what you're looking
      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. Normally just a few lines
      in AutoIndex's script file are enough to tailor the output to match the author's
      expectations (and thus hopefully the index user's expectations too!).
    </p>
<p>
      AutoIndex also supports multiple indexes (as does Docbook), and since it knows
      which search terms are <span class="emphasis"><em>function</em></span>, <span class="emphasis"><em>class</em></span>,
      <span class="emphasis"><em>macro</em></span> or <span class="emphasis"><em>typedef</em></span> names, it can add
      the necessary attributes to the XML so that you can have separate indexes for
      each of these different types. These specialised indexes only contain entries
      for the <span class="emphasis"><em>function</em></span>, <span class="emphasis"><em>class</em></span>, <span class="emphasis"><em>macro</em></span>
      or <span class="emphasis"><em>typedef</em></span> names, <span class="emphasis"><em>section names</em></span> are
      never used as primary index terms here, unlike the main "include everything"
      index.
    </p>
<p>
      Finally, while the Docbook XSL stylesheets create nice indexes complete with
      page numbers for PDF output, the HTML indexes look poorer by comparison, as
      these use section titles in place of page numbers... but as AutoIndex uses
      section titles as index entries this leads to a lot of repetition, so as an
      alternative AutoIndex can be instructed to construct the index itself. This
      is faster than using the XSL stylesheets, and now each index entry is a hyperlink
      to the appropriate section:
    </p>
<p>
      <span class="inlinemediaobject"><img src="../../students_t_eg_3.png" alt="students_t_eg_3"></span>
    </p>
<p>
      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>
    </p>
<p>
      Finally, you can choose what kind of XML container wraps an internally generated
      index - this defaults to <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">section</span><span class="special">&gt;...&lt;/</span><span class="identifier">section</span><span class="special">&gt;</span></code>
      but you can use either command line options or Boost.Build Jamfile features,
      to select an alternative wrapper - for example <span class="emphasis"><em>appendix</em></span>
      or <span class="emphasis"><em>chapter</em></span> would be good choices, whatever fits best into
      the flow of the document. You can even set the container wrapper to type <span class="emphasis"><em>index</em></span>
      provided you turn off index generation by the XSL stylesheets, for example
      by setting the following build requirements in the Jamfile:
    </p>
<pre class="programlisting">&lt;format&gt;html:&lt;auto-index-internal&gt;on       # Use internally generated indexes.
&lt;auto-index-type&gt;index                     # Use &lt;index&gt;...&lt;/index&gt; as the XML wrapper.
&lt;format&gt;html:&lt;xsl:param&gt;generate.index=0   # Don't let the XSL stylesheets generate indexes.
</pre>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2008, 2011 John Maddock<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../index.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="tut.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
Commit	Line	Data
7c673cae FG	1	<html>
	2	<head>
	3	<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
	4	<title>Overview</title>
	5	<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
	6	<meta name="generator" content="DocBook XSL Stylesheets V1.77.1">
	7	<link rel="home" href="../index.html" title="Boost.AutoIndex">
	8	<link rel="up" href="../index.html" title="Boost.AutoIndex">
	9	<link rel="prev" href="../index.html" title="Boost.AutoIndex">
	10	<link rel="next" href="tut.html" title="Getting Started and Tutorial">
	11	</head>
	12	<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
	13	<table cellpadding="2" width="100%"><tr>
	14	<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
	15	<td align="center"><a href="../../../../../index.html">Home</a></td>
	16	<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td>
	17	<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
	18	<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
	19	<td align="center"><a href="../../../../../more/index.htm">More</a></td>
	20	</tr></table>
	21	<hr>
	22	<div class="spirit-nav">
	23	<a accesskey="p" href="../index.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="tut.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
	24	</div>
	25	<div class="section">
	26	<div class="titlepage"><div><div><h2 class="title" style="clear: both">
	27	<a name="boost_autoindex.overview"></a><a class="link" href="overview.html" title="Overview">Overview</a>
	28	</h2></div></div></div>
	29	<p>
	30	AutoIndex is a tool for taking the grunt work out of indexing a Boostbook/Docbook
	31	document (perhaps generated by your Quickbook file mylibrary.qbk, and perhaps
	32	using also Doxygen autodoc) that describes C/C++ code.
	33	</p>
	34	<p>
	35	Traditionally, in order to index a Docbook document you would have to manually
	36	add a large amount of <code class="computeroutput"><span class="special"><</span><span class="identifier">indexterm</span><span class="special">></span></code> markup: in fact one <code class="computeroutput"><span class="special"><</span><span class="identifier">indexterm</span><span class="special">></span></code>
	37	for each occurrence of each term to be indexed.
	38	</p>
	39	<p>
	40	Instead AutoIndex will automatically scan one or more C/C++ header files and
	41	extract all the <span class="emphasis"><em>function</em></span>, <span class="emphasis"><em>class</em></span>,
	42	<span class="emphasis"><em>macro</em></span> and <span class="emphasis"><em>typedef</em></span> names that are
	43	defined by those headers, and then insert the <code class="computeroutput"><span class="special"><</span><span class="identifier">indexterm</span><span class="special">></span></code>s
	44	into the Docbook XML document for you.
	45	</p>
	46	<p>
	47	AutoIndex can also scan using a list of index terms specified in a script file,
	48	for example index.idx. These manually provided terms can optionally be regular
	49	expressions, and may allow the user to find references to terms that may not
	50	occur in the C++ header files. Of course providing a manual list of search
	51	terms in to index is a tedious task (especially handling plurals and variants),
	52	and requires enough knowledge of the library to guess what users may be seeking
	53	to know, but at least the real 'grunt work' of finding the term and listing
	54	the page number is automated.
	55	</p>
	56	<p>
	57	AutoIndex creates index entries as follows:
	58	</p>
	59	<p>
	60	for each occurrence of each search term, it creates two index entries:
	61	</p>
	62	<div class="orderedlist"><ol class="orderedlist" type="1">
	63	<li class="listitem">
	64	The search term as the <span class="emphasis"><em>primary index key</em></span> and the
65	<span class="emphasis"><em>title of the section it appears in</em></span> as a subterm.
66	</li>
67	<li class="listitem">
68	The section title as the main index entry and the search term as the subentry.
69	</li>
70	</ol></div>
71	<p>
72	Thus the user has two chances to find what they're looking for, based upon
73	either the section name or the <span class="emphasis"><em>function</em></span>, <span class="emphasis"><em>class</em></span>,
74	<span class="emphasis"><em>macro</em></span> or <span class="emphasis"><em>typedef</em></span> name.
75	</p>
76	<div class="note"><table border="0" summary="Note">
77	<tr>
78	<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td>
79	<th align="left">Note</th>
80	</tr>
81	<tr><td align="left" valign="top"><p>
82	This behaviour can be changed so that only one index entry is created (using
83	the search term as the key and not using the section name except as a sub-entry
84	of the search term).
85	</p></td></tr>
86	</table></div>
87	<p>
88	So for example in Boost.Math the class name <code class="computeroutput"><span class="identifier">students_t_distribution</span></code>
89	has a primary entry that lists all sections the class name appears in:
90	</p>
91	<p>
92	<span class="inlinemediaobject"><img src="../../students_t_eg_1.png" alt="students_t_eg_1"></span>
93	</p>
94	<p>
95	Then those sections also have primary entries, which list all the search terms
96	those sections contain:
97	</p>
98	<p>
99	<span class="inlinemediaobject"><img src="../../students_t_eg_2.png" alt="students_t_eg_2"></span>
100	</p>
101	<p>
102	Of course these automated index entries may not be quite what you're looking
103	for: often you'll get a few spurious entries, a few missing entries, and a
104	few entries where the section name used as an index entry is less than ideal.
105	So AutoIndex provides some powerful regular expression based rules that allow
106	you to add, remove, constrain, or rewrite entries. Normally just a few lines
107	in AutoIndex's script file are enough to tailor the output to match the author's
108	expectations (and thus hopefully the index user's expectations too!).
109	</p>
110	<p>
111	AutoIndex also supports multiple indexes (as does Docbook), and since it knows
112	which search terms are <span class="emphasis"><em>function</em></span>, <span class="emphasis"><em>class</em></span>,
113	<span class="emphasis"><em>macro</em></span> or <span class="emphasis"><em>typedef</em></span> names, it can add
114	the necessary attributes to the XML so that you can have separate indexes for
115	each of these different types. These specialised indexes only contain entries
116	for the <span class="emphasis"><em>function</em></span>, <span class="emphasis"><em>class</em></span>, <span class="emphasis"><em>macro</em></span>
117	or <span class="emphasis"><em>typedef</em></span> names, <span class="emphasis"><em>section names</em></span> are
118	never used as primary index terms here, unlike the main "include everything"
119	index.
120	</p>
121	<p>
122	Finally, while the Docbook XSL stylesheets create nice indexes complete with
123	page numbers for PDF output, the HTML indexes look poorer by comparison, as
124	these use section titles in place of page numbers... but as AutoIndex uses
125	section titles as index entries this leads to a lot of repetition, so as an
126	alternative AutoIndex can be instructed to construct the index itself. This
127	is faster than using the XSL stylesheets, and now each index entry is a hyperlink
128	to the appropriate section:
129	</p>
130	<p>
131	<span class="inlinemediaobject"><img src="../../students_t_eg_3.png" alt="students_t_eg_3"></span>
132	</p>
133	<p>
134	With internal index generation there is also a helpful navigation bar at the
135	start of each Index:
136	</p>
137	<p>
138	<span class="inlinemediaobject"><img src="../../students_t_eg_4.png" alt="students_t_eg_4"></span>
139	</p>
140	<p>
141	Finally, you can choose what kind of XML container wraps an internally generated
142	index - this defaults to <code class="computeroutput"><span class="special"><</span><span class="identifier">section</span><span class="special">>...</</span><span class="identifier">section</span><span class="special">></span></code>
143	but you can use either command line options or Boost.Build Jamfile features,
144	to select an alternative wrapper - for example <span class="emphasis"><em>appendix</em></span>
145	or <span class="emphasis"><em>chapter</em></span> would be good choices, whatever fits best into
146	the flow of the document. You can even set the container wrapper to type <span class="emphasis"><em>index</em></span>
147	provided you turn off index generation by the XSL stylesheets, for example
148	by setting the following build requirements in the Jamfile:
149	</p>
150	<pre class="programlisting"><format>html:<auto-index-internal>on # Use internally generated indexes.
151	<auto-index-type>index # Use <index>...</index> as the XML wrapper.
152	<format>html:<xsl:param>generate.index=0 # Don't let the XSL stylesheets generate indexes.
153	</pre>
154	</div>
155	<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
156	<td align="left"></td>
157	<td align="right"><div class="copyright-footer">Copyright © 2008, 2011 John Maddock<p>
158	Distributed under the Boost Software License, Version 1.0. (See accompanying
159	file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
160	</p>
161	</div></td>
162	</tr></table>
163	<hr>
164	<div class="spirit-nav">
165	<a accesskey="p" href="../index.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="tut.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
166	</div>
167	</body>
168	</html>