[Boost-commit] svn:boost r68722 - in sandbox/guild/mylibrary/libs/mylibrary: doc doc/html/boost/mylibrary example

Subject: [Boost-commit] svn:boost r68722 - in sandbox/guild/mylibrary/libs/mylibrary: doc doc/html/boost/mylibrary example
From: pbristow_at_[hidden]
Date: 2011-02-08 12:20:15

Author: pbristow
Date: 2011-02-08 12:20:14 EST (Tue, 08 Feb 2011)
New Revision: 68722
URL: http://svn.boost.org/trac/boost/changeset/68722

Log:
Some minor changes to text indexing, but don't get debug output, and error in pdf generation and index.
Text files modified: 
   sandbox/guild/mylibrary/libs/mylibrary/doc/autodoc.xml                      |     8 +++---                                  
   sandbox/guild/mylibrary/libs/mylibrary/doc/html/boost/mylibrary/donowt.html |     2                                         
   sandbox/guild/mylibrary/libs/mylibrary/doc/jamfile.v2                       |     1                                         
   sandbox/guild/mylibrary/libs/mylibrary/doc/mylibrary.idx                    |    25 +++++++++++++++++++----                 
   sandbox/guild/mylibrary/libs/mylibrary/doc/mylibrary.qbk                    |    41 +++++++++++++++++++++++---------------- 
   sandbox/guild/mylibrary/libs/mylibrary/example/mylibrary_example.cpp        |    18 ++++++++--------                        
   6 files changed, 58 insertions(+), 37 deletions(-)

Modified: sandbox/guild/mylibrary/libs/mylibrary/doc/autodoc.xml
==============================================================================
--- sandbox/guild/mylibrary/libs/mylibrary/doc/autodoc.xml	(original)
+++ sandbox/guild/mylibrary/libs/mylibrary/doc/autodoc.xml	2011-02-08 12:20:14 EST (Tue, 08 Feb 2011)
@@ -1,13 +1,13 @@
 <?xml version="1.0" standalone="yes"?>
-<library-reference id="boost_mylibrary_c___reference"><title>Boost.mylibrary C++ Reference</title><header name="boost/mylibrary/mylibrary.hpp"><para>Template for Boost documentation. </para><para>Header file for use by example. Also using Quickbook, Doxygen and indexed by Auto-index. </para><namespace name="boost"><namespace name="mylibrary"><class name="myclass"><purpose>A test class - a comment description that preceeds the class. </purpose><enum name="test_enum"><enumvalue name="test_enum_val1"><purpose>Enum value TVal1 (not the &lt; to link to the same line). </purpose></enumvalue><enumvalue name="test_enum_val2"><purpose>Enum value TVal2. </purpose></enumvalue><enumvalue name="test_enum_val3"><description><para>Enum value TVal3. (using C style comment markers). </para></description></enumvalue><purpose>An enum. </purpose><description><para>More detailed enum description. needing more than one line so using C style comment markers. </para></description></enum><data-member name="mypublic_var"><type>int</
type><purpose>A public variable. </purpose><description><para>Details about the variable. My public class variable. </para></description></data-member><method-group name="public member functions"><method name="test_me" cv=""><type>int</type><parameter name="a"><paramtype>int</paramtype><description><para>an integer argument. </para></description></parameter><parameter name="s"><paramtype>const char *</paramtype><description><para>a constant character pointer. </para></description></parameter><purpose>A normal member function taking two arguments and returning an integer value. </purpose><description><para>
+<library-reference id="boost_mylibrary_c___reference"><title>Boost.mylibrary C++ Reference</title><header name="boost/mylibrary/mylibrary.hpp"><para>Template for Boost documentation. </para><para>Header file for use by example. Also using Quickbook, Doxygen, and indexed by AutoIndex. </para><namespace name="boost"><namespace name="mylibrary"><class name="myclass"><purpose>A test class - a comment description that preceeds the class. </purpose><enum name="test_enum"><enumvalue name="test_enum_val1"><purpose>Enum value TVal1 (Note: the use of &lt; to link this Doxygen comment to the same line). </purpose></enumvalue><enumvalue name="test_enum_val2"><purpose>Enum value TVal2. </purpose></enumvalue><enumvalue name="test_enum_val3"><description><para>Enum value TVal3. (Note: using C style comment markers). </para></description></enumvalue><purpose>An fully useless enum with 3 values. </purpose><description><para>More detailed enum description, needing more than one line, so using C style comment markers. </para>
</description></enum><data-member name="mypublic_var"><type>int</type><purpose>A public variable. </purpose><description><para>Details about the variable. My public class variable. </para></description></data-member><method-group name="public member functions"><method name="test_me" cv=""><type>int</type><parameter name="a"><paramtype>int</paramtype><description><para>an integer argument. </para></description></parameter><parameter name="s"><paramtype>const char *</paramtype><description><para>a constant character pointer. </para></description></parameter><purpose>A normal member function taking two arguments and returning an integer value. </purpose><description><para>
 
 <para>Test(), ~Test(), testMeToo() and publicVar() </para>
 </para></description><returns><para>The test result. </para></returns></method><method name="test_me_too" cv=""><type>void</type><parameter name="c1"><paramtype>char</paramtype><description><para>the first argument. </para></description></parameter><parameter name="c2"><paramtype>char</paramtype><description><para>the second argument. </para></description></parameter><description><para>A pure virtual member with descriptions of parameters. And a 'see also' reference to another version of the function.</para><para><para>test_me() </para>
 
 </para></description></method></method-group><constructor><purpose>A constructor. </purpose><description><para>A more elaborate description of the constructor. <para>This constructor does nothing much. </para>
-</para></description></constructor><destructor><purpose>A destructor. </purpose><description><para>A more elaborate description of the destructor. <para>This destructor may explode in your face! </para>
-</para></description></destructor></class><function name="donowt"><type>int</type><parameter name="i"><paramtype>int</paramtype><description><para>is an argument that is ignored completely.</para></description></parameter><description><para>Non-member free function that does nowt useful at all.</para><para>
+</para></description></constructor><destructor><purpose>A destructor. </purpose><description><para>A more detailed description of the destructor. <para>Warning! This destructor may explode in your face! (The doxygen command warning will NOT be found by the index term warning, but words in the warning, like explode, WILL be found). </para>
+</para></description></destructor></class><function name="donowt"><type>int</type><parameter name="i"><paramtype>int</paramtype><description><para>is an argument that is ignored completely. </para></description></parameter><description><para>Non-member free function that does nowt useful at all. 
 
 
 
-</para></description><requires><para>No preconditions. </para></requires><postconditions><para>No side effects.</para></postconditions><returns><para>-1 always </para></returns></function></namespace></namespace><macro name="BOOST_MYLIBRARY_HPP"/></header></library-reference>
+</para></description><requires><para>No preconditions. </para></requires><postconditions><para>No side effects.</para></postconditions><returns><para>-1 always. </para></returns></function></namespace></namespace><macro name="BOOST_MYLIBRARY_HPP"/></header></library-reference>

Modified: sandbox/guild/mylibrary/libs/mylibrary/doc/html/boost/mylibrary/donowt.html
==============================================================================
--- sandbox/guild/mylibrary/libs/mylibrary/doc/html/boost/mylibrary/donowt.html	(original)
+++ sandbox/guild/mylibrary/libs/mylibrary/doc/html/boost/mylibrary/donowt.html	2011-02-08 12:20:14 EST (Tue, 08 Feb 2011)
@@ -34,7 +34,7 @@
 </span>
 <span class="keyword">int</span> <span class="identifier">donowt</span><span class="special">(</span><span class="keyword">int</span> i<span class="special">)</span><span class="special">;</span></pre></div>
 <div class="refsect1" lang="en">
-<a name="id867117"></a><h2>Description</h2>
+<a name="id885705"></a><h2>Description</h2>
 <p>Non-member free function that does nowt useful at all. 
 
 

Modified: sandbox/guild/mylibrary/libs/mylibrary/doc/jamfile.v2
==============================================================================
--- sandbox/guild/mylibrary/libs/mylibrary/doc/jamfile.v2	(original)
+++ sandbox/guild/mylibrary/libs/mylibrary/doc/jamfile.v2	2011-02-08 12:20:14 EST (Tue, 08 Feb 2011)
@@ -32,7 +32,6 @@
         
         <format>html:<xsl:param>index.on.type=1 # = 1 For the native stylesheets to generate multiple different indexes.
         
-        <format>pdf:<xsl:param>index.on.type=1 # For the native stylesheets to generate multiple different indexes.
         # PDF native index support is probably better for PDFs as then you actually get page numbers.
 
         <auto-index-script>mylibrary.idx # Specifies the name of the script to load for mylibrary. 

Modified: sandbox/guild/mylibrary/libs/mylibrary/doc/mylibrary.idx
==============================================================================
--- sandbox/guild/mylibrary/libs/mylibrary/doc/mylibrary.idx	(original)
+++ sandbox/guild/mylibrary/libs/mylibrary/doc/mylibrary.idx	2011-02-08 12:20:14 EST (Tue, 08 Feb 2011)
@@ -8,7 +8,7 @@
 # http://www.boost.org/LICENSE_1_0.txt)
 
 # Diagnostic output - useful during refinement of the index.
-!debug regular-expression 
+!debug regular-expression
 
 #  All header files, recursing down to include sub-folders.
 !scan-path "boost/mylibrary" ".*\.hpp" true 
@@ -19,6 +19,8 @@
 # Terms that you want to appear in the Index.
 # Term to display in index, and word(s) that are to be matched (as a regular expression).
 
+!debug regular-expression
+
 Quickbook
 Doxygen
 
@@ -50,13 +52,26 @@
 
 Kelvin "" ".*idols.*"
 Voltaire "" ".*indexing.*"
-
 Twain
 
-# macro  
-
+macro
+parameters
+detailed
+syntax
+junk  
+elaborate
+explode
 # An index term that should only be found in one Doxygen comment.
-obscure obscure
+obscure
+# An index term that should be 
+trivial
+# index term in \mainpage in my library.hpp
+mainpage
+
+# Several warnings in \warnings comments
+warning
+# Mentioned in Doxygen \details comment in my_library_example.cpp
+markup
 
 # Two word index term, allowing plurals.
 "side effect" \<side effect\w*\>

Modified: sandbox/guild/mylibrary/libs/mylibrary/doc/mylibrary.qbk
==============================================================================
--- sandbox/guild/mylibrary/libs/mylibrary/doc/mylibrary.qbk	(original)
+++ sandbox/guild/mylibrary/libs/mylibrary/doc/mylibrary.qbk	2011-02-08 12:20:14 EST (Tue, 08 Feb 2011)
@@ -45,6 +45,11 @@
 [def __intro [link mylibrary.intro Introduction]] [/Link to a Quickbook section (see below).]
 [def __todo [link mylibrary.todo TODO]]
 
+[def __docbook_params [@http://docbook.sourceforge.net/release/xsl/current/doc/ Docbook xsl:param format options]]
+
+[template deg[]'''&#xB0;'''] [/ degree sign ]
+[/ See latin1_symbols.qbk and math_symbols.qbk for more]
+
 [important This is a template, NOT an official Boost library.]
 
 [/ Examples of links to classes in own files.]
@@ -94,6 +99,8 @@
   This ensures that the code snippets shown in the documentation
   have been compiled, and are updated
   automatically as the source C++ is changed.
+  The output can also be saved, perhaps appended to the example file,
+  and made visible as another snippet.
 
 * Simple markup to link to __doxygen generated entities
  (namespaces, classes, functions, typedefs).
@@ -102,9 +109,9 @@
   both in __quickbook automatically added reference section,
   and also in __doxygen standalone documentation.
 
-* Automatic indexing to __doxygen-generated entities
+* Automatic indexing to __doxygen -generated entities
   (namespaces, classes, functions, typedefs).
-  and author chosen indexing of text
+  and author-chosen indexing of text
   see __autoindex.
 
 * Macro system for simple text substitution.
@@ -117,10 +124,10 @@
 
 __alert
 But to allow a standalone zipped version of html,
- all images must be copied (installed) into the doc\html\images sub-directory.
+ all images must be copied (installed) into the `doc\html\images` sub-directory.
 
 This document is intended to provide a sort of template to help new writers get started,
-with many handy hints and tips (based on the many pitfalls discovered en route).
+with some handy hints and tips (based on the many pitfalls discovered en route).
 
 It is written in __quickbook to demonstrate some features
 (but for much more see __quickbook (itself written in __quickbook)
@@ -163,16 +170,16 @@
 (and __doxygen comments in the C++ code
 provided you can put in the considerable work to provide them)
 will allow users to get an overview of the program,
- see what classes and function do, and where used,
-and to get to read individual files easily.
+see what classes and function do, and where used,
+and to get to view individual files easily.
 
 AutoIndexing - see __autoindex for guidance.
 
-The "Getting Started and Tutorial " section tells what you [*really] need to know.
+The AutoIndex "Getting Started and Tutorial " section tells what you [*really] need to know.
 
 Step 1 is not really optional - the indexing process is slow, even with explicit
 specification of the auto-index.exe.  So follow these instructions carefully,
-including changes to your user-config.jam.
+including essential changes to your user-config.jam.
 
 [xinclude autodoc.xml] [/ Using Doxygen reference documentation.]
 [/ The position of this in the Quickbook determines the location of the Doxygen references section.]
@@ -200,15 +207,15 @@
 
 '''
 
-This is some junk that should [*never] be indexed!
-(because it is excluded in the script file index.idx).
+This is some ['junk] that should [*never] be indexed!
+(because it is excluded in the index script file mylibrary.idx).
 
-Here is a mention of degrees kelvin which should not 
-put the great man's name in the index to here.
+Here is a mention of degrees [deg] kelvin which should [*not] 
+put the great man's name in the index linking to here.
 
-Voltaire should get an (silly) entry only in the indexing section here.
+Voltaire should get an (silly) entry only in the indexing section linking this section or page.
 
-Twain should be indexed in both.
+Twain should be indexed whereever it is found.
 
 [endsect] [/section:indexing How to get Index(es) of your documentation]
 
@@ -221,19 +228,19 @@
 
 For example, if you want to index occurrences of Lord Kelvin's name,
 but only in the idols section,  and Voltaire only in the indexing section,
-but Twain in both, you might then add:
+but Twain in all sections, you might then add:
 
 [pre
 Kelvin "" ".*idols.*"
 Voltaire "" ".*indexing.*"
 ] [/pre]
 
-to the script file,
+to the index script file,
 assuming that the section ID of the intro is "some_library_or_chapter_name.idols",
 here "mylibrary.idols".
 
 This section contains quotes from some scientist idols
-whose name should only be indexed in this section.
+two of whose names should [*only] be indexed in this section.
 
 "It ain't what you don't know that gets you into trouble.
 It's what you know for sure that just ain't so."

Modified: sandbox/guild/mylibrary/libs/mylibrary/example/mylibrary_example.cpp
==============================================================================
--- sandbox/guild/mylibrary/libs/mylibrary/example/mylibrary_example.cpp	(original)
+++ sandbox/guild/mylibrary/libs/mylibrary/example/mylibrary_example.cpp	2011-02-08 12:20:14 EST (Tue, 08 Feb 2011)
@@ -1,5 +1,5 @@
 /*! \file
-\brief 
+\brief
  An example to run the simplest "Hello world" program,
  and to use code in an included header file.
  \version 1
@@ -12,7 +12,7 @@
 to this file in the scan-path in script file mylibrary.idx thus:
 
 # All example source files, assuming no sub-folders.
-!scan-path "libs/mylibrary/example" ".*\.cpp" 
+!scan-path "libs/mylibrary/example" ".*\.cpp"
 
 Some terms in this file should be indexed by the chosen index terms,
 but others should be excluded,
@@ -21,7 +21,7 @@
 
  \warning This example is entirely contrived to show off features, and does nothing useful.
 
- \author Paul A. Bristow 
+ \author Paul A. Bristow
  \version 3
  \date Feb 2011
 */
@@ -45,7 +45,7 @@
 //[mylibrary_example_1
 // This is a snippet of code that can be included into a Quickbook program.
 
-// Include Standard Library input output.
+// Include Standard Library input output, for example.
 #include <iostream>
 using std::cout;
 using std::endl;
@@ -53,23 +53,23 @@
 // Include mylibrary header(s).
 #include <boost/mylibrary/mylibrary.hpp>
 
+// Probably need to add #include directories to the project as well.
 
-// Probably need to add #include directories too.
+/*!  A very simple example program, doing very little except some trivial output.
 
-/*!  A very simple example program, doing very little except some output.
-
-     \detail  273 o kelvin should not be indexed.
+     \detail  273 o kelvin should NOT be indexed.
      \pre No preconditions (apart from assuming that this is the main function)
      \post No side effects, just a zero return.
 
      \returns Zero always, even if an error is detected.
-     \remark This is a Doxygen remark about an obscure detail that should get indexed.
+     \remark This is a Doxygen remark about an obscure detail that should get indexed under "obscure".
 
 */
 
 int main()
 {
   using boost::mylibrary::myclass;
+
   cout << "Hello World!" << endl;
   return 0;