boost_mirror/auto_index
1
0
Fork 0
mirror of https://github.com/boostorg/auto_index.git synced 2025-05-09 23:24:02 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add more improved error handling.

Browse Source 
Add docs on what containers can hold an index.
Fix tests not to generate bad Docbook!

[SVN r68458]
This commit is contained in:
John Maddock 2011-01-26 18:13:05 +00:00
parent 67a3a0341f
commit c0e5727a80
11 changed files with 316 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
doc/auto_index.qbk
View File

@ -180,7 +180,23 @@ entry that uses the section title is not created. Defaults to "on"]]
prints progress information - generally useful only for debugging purposes.]]
[[<auto-index-prefix>filename][Specifies a directory to apply as a prefix to all relative file paths in the script file.]]
[[<auto-index-type>element-name][Specifies the name of the XML element to enclose internally generated indexes in:
defaults to "section", but could equally be "appendix" or "chapter" or some other block level element that has a formal title.]]
defaults to "section", but could equally be "appendix" or "chapter" or some other block level element that has a formal title.
The actual list of available options depends upon the document type, the following table gives the available options:]]
]
[table
[[Document Type][Available Index Types]]
[[book][appendix index article chapter reference part]]
[[article][section appendix index sect1]]
[[library][See Chapter]]
[[chapter][section index sect1]]
[[part][appendix index article chapter reference]]
[[appendix][section index sect1]]
[[preface][section index sect1]]
[[qandadiv][N/A: an index would have to be placed within a subsection of the document.]]
[[qandaset][N/A: an index would have to be placed within a subsection of the document.]]
[[reference][N/A: an index would have to be placed within a subsection of the document.]]
[[set][N/A: an index would have to be placed within a subsection of the document.]]
]

1
doc/html/autoindex/comm_ref.html
View File

@ -1,4 +1,3 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">

1
doc/html/autoindex/overview.html
View File

@ -1,4 +1,3 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">

17
doc/html/autoindex/script_ref.html
View File

@ -1,4 +1,3 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
@ -24,7 +23,7 @@
The following elements can occur in a script:
</p>
<a name="autoindex.script_ref.comments_and_blank_lines"></a><h5>
<a name="id981834"></a>
<a name="id981429"></a>
<a class="link" href="script_ref.html#autoindex.script_ref.comments_and_blank_lines">Comments and
blank lines</a>
</h5>
@ -33,7 +32,7 @@
with a '#'.
</p>
<a name="autoindex.script_ref.simple_inclusions"></a><h5>
<a name="id981851"></a>
<a name="id981446"></a>
<a class="link" href="script_ref.html#autoindex.script_ref.simple_inclusions">Simple Inclusions</a>
</h5>
<pre class="programlisting"><span class="identifier">term</span> <span class="special">[</span><span class="identifier">regular</span><span class="special">-</span><span class="identifier">expression1</span> <span class="special">[</span><span class="identifier">regular</span><span class="special">-</span><span class="identifier">expression2</span> <span class="special">[</span><span class="identifier">category</span><span class="special">]]]</span>
@ -100,7 +99,7 @@
</dl>
</div>
<a name="autoindex.script_ref.source_file_scanning"></a><h5>
<a name="id982060"></a>
<a name="id981655"></a>
<a class="link" href="script_ref.html#autoindex.script_ref.source_file_scanning">Source File Scanning</a>
</h5>
<pre class="programlisting"><span class="special">!</span><span class="identifier">scan</span> <span class="identifier">source</span><span class="special">-</span><span class="identifier">file</span><span class="special">-</span><span class="identifier">name</span>
@ -129,7 +128,7 @@
</p></td></tr>
</table></div>
<a name="autoindex.script_ref.directory_and_source_file_scanning"></a><h5>
<a name="id982138"></a>
<a name="id981733"></a>
<a class="link" href="script_ref.html#autoindex.script_ref.directory_and_source_file_scanning">Directory
and Source File Scanning</a>
</h5>
@ -158,7 +157,7 @@
</dl>
</div>
<a name="autoindex.script_ref.excluding_terms"></a><h5>
<a name="id982263"></a>
<a name="id981857"></a>
<a class="link" href="script_ref.html#autoindex.script_ref.excluding_terms">Excluding Terms</a>
</h5>
<pre class="programlisting"><span class="special">!</span><span class="identifier">exclude</span> <span class="identifier">term</span><span class="special">-</span><span class="identifier">list</span>
@ -171,7 +170,7 @@
of things to index.
</p>
<a name="autoindex.script_ref.rewriting_section_names"></a><h5>
<a name="id982318"></a>
<a name="id981913"></a>
<a class="link" href="script_ref.html#autoindex.script_ref.rewriting_section_names">Rewriting Section
Names</a>
</h5>
@ -218,7 +217,7 @@
all index entries - thus preventing lots of entries under "The" etc!
</p>
<a name="autoindex.script_ref.defining_or_changing_the_file_scanners"></a><h5>
<a name="id982470"></a>
<a name="id982065"></a>
<a class="link" href="script_ref.html#autoindex.script_ref.defining_or_changing_the_file_scanners">Defining
or Changing the File Scanners</a>
</h5>
@ -321,7 +320,7 @@
scanner may find in the documentation.
</p>
<a name="autoindex.script_ref.debugging"></a><h5>
<a name="id983118"></a>
<a name="id982568"></a>
<a class="link" href="script_ref.html#autoindex.script_ref.debugging">Debugging</a>
</h5>
<p>

174
doc/html/autoindex/tut.html
View File

@ -1,4 +1,3 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
@ -21,7 +20,7 @@
<a name="autoindex.tut"></a><a class="link" href="tut.html" title="Getting Started and Tutorial">Getting Started and Tutorial</a>
</h2></div></div></div>
<a name="autoindex.tut.step_1__build_the_tool"></a><h5>
<a name="id972655"></a>
<a name="id975919"></a>
<a class="link" href="tut.html#autoindex.tut.step_1__build_the_tool">Step 1: Build the tool</a>
</h5>
<p>
@ -63,7 +62,7 @@
is accepted into Boost.
</p>
<a name="autoindex.tut.step_2__configure_boost_build"></a><h5>
<a name="id972819"></a>
<a name="id976083"></a>
<a class="link" href="tut.html#autoindex.tut.step_2__configure_boost_build">Step 2: Configure
Boost.Build</a>
</h5>
@ -151,10 +150,167 @@
Specifies the name of the XML element to enclose internally generated
indexes in: defaults to "section", but could equally be "appendix"
or "chapter" or some other block level element that has a formal
title.
title. The actual list of available options depends upon the document
type, the following table gives the available options:
</p></dd>
</dl>
</div>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
<p>
Document Type
</p>
</th>
<th>
<p>
Available Index Types
</p>
</th>
</tr></thead>
<tbody>
<tr>
<td>
<p>
book
</p>
</td>
<td>
<p>
appendix index article chapter reference part
</p>
</td>
</tr>
<tr>
<td>
<p>
article
</p>
</td>
<td>
<p>
section appendix index sect1
</p>
</td>
</tr>
<tr>
<td>
<p>
library
</p>
</td>
<td>
<p>
See Chapter
</p>
</td>
</tr>
<tr>
<td>
<p>
chapter
</p>
</td>
<td>
<p>
section index sect1
</p>
</td>
</tr>
<tr>
<td>
<p>
part
</p>
</td>
<td>
<p>
appendix index article chapter reference
</p>
</td>
</tr>
<tr>
<td>
<p>
appendix
</p>
</td>
<td>
<p>
section index sect1
</p>
</td>
</tr>
<tr>
<td>
<p>
preface
</p>
</td>
<td>
<p>
section index sect1
</p>
</td>
</tr>
<tr>
<td>
<p>
qandadiv
</p>
</td>
<td>
<p>
N/A: an index would have to be placed within a subsection of the
document.
</p>
</td>
</tr>
<tr>
<td>
<p>
qandaset
</p>
</td>
<td>
<p>
N/A: an index would have to be placed within a subsection of the
document.
</p>
</td>
</tr>
<tr>
<td>
<p>
reference
</p>
</td>
<td>
<p>
N/A: an index would have to be placed within a subsection of the
document.
</p>
</td>
</tr>
<tr>
<td>
<p>
set
</p>
</td>
<td>
<p>
N/A: an index would have to be placed within a subsection of the
document.
</p>
</td>
</tr>
</tbody>
</table></div>
<p>
It is possible to make the use of auto-index optional in Boost.Build, to allow
users who do not have auto-index installed to build your documentation. One
@ -172,7 +328,7 @@
<span class="special">}</span>
</pre>
<a name="autoindex.tut.step_3__add_indexes_to_your_documentation"></a><h5>
<a name="id980968"></a>
<a name="id976693"></a>
<a class="link" href="tut.html#autoindex.tut.step_3__add_indexes_to_your_documentation">Step
3: Add indexes to your documentation</a>
</h5>
@ -266,7 +422,7 @@ boostbook standalone
&lt;xsl:param&gt;index.on.type=1
</pre>
<a name="autoindex.tut.step_4__create_the_script_file"></a><h5>
<a name="id981270"></a>
<a name="id976995"></a>
<a class="link" href="tut.html#autoindex.tut.step_4__create_the_script_file">Step 4: Create
the script file</a>
</h5>
@ -339,7 +495,7 @@ boostbook standalone
<pre class="programlisting"><span class="special">!</span><span class="identifier">rewrite</span><span class="special">-</span><span class="identifier">name</span> <span class="string">"(?i)(?:A|The)\s+(.*)"</span> <span class="string">"\1"</span>
</pre>
<a name="autoindex.tut.step_5__add_manual_index_entries___optional"></a><h5>
<a name="id981525"></a>
<a name="id977249"></a>
<a class="link" href="tut.html#autoindex.tut.step_5__add_manual_index_entries___optional">Step
5: Add Manual Index Entries - Optional</a>
</h5>
@ -355,7 +511,7 @@ boostbook standalone
index itself, with the exception of the "type" attribute.
</p>
<a name="autoindex.tut.step_6__build_the_docs"></a><h5>
<a name="id981645"></a>
<a name="id981239"></a>
<a class="link" href="tut.html#autoindex.tut.step_6__build_the_docs">Step 6: Build the Docs</a>
</h5>
<p>
@ -381,7 +537,7 @@ boostbook standalone
If you don't see that, or if it's indexing 0 terms then something is wrong!
</p>
<a name="autoindex.tut.step_7__iterate"></a><h5>
<a name="id981755"></a>
<a name="id981350"></a>
<a class="link" href="tut.html#autoindex.tut.step_7__iterate">Step 7: Iterate</a>
</h5>
<p>

1
doc/html/autoindex/xml.html
View File

@ -1,4 +1,3 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">

5
doc/html/index.html
View File

@ -1,4 +1,3 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
@ -22,7 +21,7 @@
</h3></div></div></div>
<div><p class="copyright">Copyright &#169; 2008 John Maddock</p></div>
<div><div class="legalnotice">
<a name="id972367"></a><p>
<a name="id975631"></a><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>
@ -42,7 +41,7 @@
</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: January 21, 2011 at 18:33:36 GMT</small></p></td>
<td align="left"><p><small>Last revised: January 26, 2011 at 18:09:33 GMT</small></p></td>
<td align="right"><div class="copyright-footer"></div></td>
</tr></table>
<hr>

2
src/file_scanning.cpp
View File

@ -117,6 +117,8 @@ void scan_file(const char* file)
std::cout << "Scanning file... " << file << std::endl;
std::string text;
std::ifstream is(file);
if(!is.peek() || !is.good())
throw std::runtime_error(std::string("Unable to read from file: ") + file);
load_file(text, is);
for(file_scanner_set_type::iterator pscan = file_scanner_set.begin(); pscan != file_scanner_set.end(); ++pscan)

109
src/index_generator.cpp
View File

@ -19,6 +19,111 @@ std::string get_next_index_id()
return s.str();
}
//
// Validate that the container for the Index is in a valid place:
//
void check_index_type_and_placement(const std::string& parent, const std::string& container)
{
if(container == "section")
{
if((parent != "appendix")
&& (parent != "article")
&& (parent != "chapter")
&& (parent != "partintro")
&& (parent != "preface")
&& (parent != "section"))
throw std::runtime_error("Error: element " + container + " can not appear inside the container " + parent + ": try using a different value for property \"auto-index-type\".");
}
else if(container == "appendix")
{
if((parent != "article")
&& (parent != "book")
&& (parent != "part"))
throw std::runtime_error("Error: element " + container + " can not appear inside the container " + parent + ": try using a different value for property \"auto-index-type\".");
}
else if(container == "index")
{
if((parent != "appendix")
&& (parent != "article")
&& (parent != "book")
&& (parent != "chapter")
&& (parent != "part")
&& (parent != "preface")
&& (parent != "sect1")
&& (parent != "sect2")
&& (parent != "sect3")
&& (parent != "sect4")
&& (parent != "sect5")
&& (parent != "section")
)
throw std::runtime_error("Error: element " + container + " can not appear inside the container " + parent + ": try using a different value for property \"auto-index-type\".");
}
else if((container == "article") || (container == "chapter") || (container == "reference"))
{
if((parent != "book")
&& (parent != "part"))
throw std::runtime_error("Error: element " + container + " can not appear inside the container " + parent + ": try using a different value for property \"auto-index-type\".");
}
else if(container == "part")
{
if(parent != "book")
throw std::runtime_error("Error: element " + container + " can not appear inside the container " + parent + ": try using a different value for property \"auto-index-type\".");
}
else if(container == "refsect1")
{
if(parent != "refentry")
throw std::runtime_error("Error: element " + container + " can not appear inside the container " + parent + ": try using a different value for property \"auto-index-type\".");
}
else if(container == "refsect2")
{
if(parent != "refsect1")
throw std::runtime_error("Error: element " + container + " can not appear inside the container " + parent + ": try using a different value for property \"auto-index-type\".");
}
else if(container == "refsect3")
{
if(parent != "refsect2")
throw std::runtime_error("Error: element " + container + " can not appear inside the container " + parent + ": try using a different value for property \"auto-index-type\".");
}
else if(container == "refsection")
{
if((parent != "refsection") && (parent != "refentry"))
throw std::runtime_error("Error: element " + container + " can not appear inside the container " + parent + ": try using a different value for property \"auto-index-type\".");
}
else if(container == "sect1")
{
if((parent != "appendix")
&& (parent != "article")
&& (parent != "chapter")
&& (parent != "partintro")
&& (parent != "preface")
)
throw std::runtime_error("Error: element " + container + " can not appear inside the container " + parent + ": try using a different value for property \"auto-index-type\".");
}
else if(container == "sect2")
{
if(parent != "sect1")
throw std::runtime_error("Error: element " + container + " can not appear inside the container " + parent + ": try using a different value for property \"auto-index-type\".");
}
else if(container == "sect3")
{
if(parent != "sect2")
throw std::runtime_error("Error: element " + container + " can not appear inside the container " + parent + ": try using a different value for property \"auto-index-type\".");
}
else if(container == "sect4")
{
if(parent != "sect3")
throw std::runtime_error("Error: element " + container + " can not appear inside the container " + parent + ": try using a different value for property \"auto-index-type\".");
}
else if(container == "sect5")
{
if(parent != "sect4")
throw std::runtime_error("Error: element " + container + " can not appear inside the container " + parent + ": try using a different value for property \"auto-index-type\".");
}
else
{
throw std::runtime_error("Error: element " + container + " is unknown, and can not be used as a container for an index: try using a different value for property \"auto-index-type\".");
}
}
//
// Generate indexes using our own internal method:
//
void generate_indexes()
@ -170,6 +275,10 @@ void generate_indexes()
}
}
node->name = internal_index_type;
boost::tiny_xml::element_ptr p(node->parent);
while(p->name.empty())
p = boost::tiny_xml::element_ptr(p->parent);
check_index_type_and_placement(p->name, node->name);
node->attributes.clear();
if(!has_title)
{

3
test/Jamfile.v2
View File

@ -57,7 +57,8 @@ rule auto-index-test ( target-name : input-file : output-file ? : options * )
auto-index-test test1 : type_traits.docbook : : script=index.idx ;
auto-index-test test2 : type_traits.docbook : : --internal-index script=index.idx ;
auto-index-test test3 : type_traits.docbook : : --internal-index index-type=appendix script=index.idx ;
auto-index-test test3 : type_traits.docbook : : --internal-index index-type=index script=index.idx ;

22
test/test3.gold
View File

File diff suppressed because one or more lines are too long