[Boost-commit] svn:boost r69386 - sandbox/guild/mylibrary/libs/mylibrary/doc

Subject: [Boost-commit] svn:boost r69386 - sandbox/guild/mylibrary/libs/mylibrary/doc
From: pbristow_at_[hidden]
Date: 2011-02-28 10:26:47

Author: pbristow
Date: 2011-02-28 10:26:44 EST (Mon, 28 Feb 2011)
New Revision: 69386
URL: http://svn.boost.org/trac/boost/changeset/69386

Log:
Various improvements, but still some errors reported (but looks OK)
Binary files modified: 
   sandbox/guild/mylibrary/libs/mylibrary/doc/mylibrary.pdf
Text files modified: 
   sandbox/guild/mylibrary/libs/mylibrary/doc/jamfile.v2    |    23 ++++++++++++++++--                      
   sandbox/guild/mylibrary/libs/mylibrary/doc/mylibrary.idx |    26 ++++++++++++++++++--                    
   sandbox/guild/mylibrary/libs/mylibrary/doc/mylibrary.qbk |    50 +++++++++++++-------------------------- 
   3 files changed, 60 insertions(+), 39 deletions(-)

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-28 10:26:44 EST (Mon, 28 Feb 2011)
@@ -40,6 +40,7 @@
         # Without this would need !scan-path "../../../boost/mylibrary"
         
         <quickbook-define>enable_index ;
+        # Used by Quickbook to invoke indexing.
 }
 else
 {
@@ -159,10 +160,26 @@
                 <format>pdf:<xsl:param>draft.mode="no"
                 <format>pdf:<xsl:param>boost.url.prefix=I:/boost-sandbox/guild/mylibrary/libs/mylibrary/doc/html
                 
-		<dependency>autodoc #
-
+		<dependency>autodoc # 
+		<dependency>css-install
+		<dependency>png-install
+		<dependency>svg-install
    ;
 
-#install pdf-install : standalone : <install-type>PDF <location>. ;
+# Install (copy) the 'master' copy of boostbook Cascading Style sheet from your current Boost-root.
+path-constant boost-root : [ modules.peek : BOOST ] ;
+install css-install : $(boost-root)/doc/src/boostbook.css : <location>html ;
+
+# Install (copy) the 'master' copies of all icon images (both PNG and SVG)
+# and the Boost logo from your current Boost-root
+# to the local /doc/html/images folder so that html is complete and standalone. 
+install png-install : [ glob $(boost-root)/doc/src/images/*.png $(boost-root)/boost.png ] : <location>html/images ;
+install svg-install : [ glob $(boost-root)/doc/src/images/*.svg ] : <location>html/images ;
+
+# install pdf-install : standalone : <install-type>PDF <location>. ;
+# Effectively copies the file from \bin folder to the \doc folder.
+# But will not work as expected if doxygen and/or autoindex is used
+# because a modified pdf file is created, so 
+# this command  will rename the file to the expected filename, here mylibrary.pdf.
 
 install pdf-install : standalone : <install-type>PDF <location>. <name>mylibrary.pdf ;

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-28 10:26:44 EST (Mon, 28 Feb 2011)
@@ -7,8 +7,6 @@
 # License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
 # http://www.boost.org/LICENSE_1_0.txt)
 
-# Diagnostic output - useful during refinement of the index.
-!debug regular-expression
 
 #  All header files, recursing down to include sub-folders.
 !scan-path "boost/mylibrary" ".*\.hpp" true 
@@ -16,10 +14,29 @@
 # All example source files, assuming no sub-folders.
 !scan-path "libs/mylibrary/example" ".*\.cpp" 
 
+# Diagnostic output - useful during refinement of the index.
 # 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).
+#  \<index\w*\> for example, should show all matches to index, indexes, indexed, indexing and indexation.
+# !debug \<index\w*\> 
+
+# Indexing section: Creating Boost HTML and PDF documentation using Quickbook, Doxygen and Auto-Indexing.
+# Debug term found, in block with ID: my_library_template
+# Current section title is: Creating Boost HTML and PDF documentation using Quickbook, Doxygen and Auto-Indexing.
+# The main index entry will be : Creating Boost HTML and PDF documentation using Quickbook, Doxygen and Auto-Indexing.
+# The indexed term is: index
+# The search regex is: \<index\w*\>
+# The section constraint is: 
+# The index type for this entry is: 
+
+#!debug "\<\w*\>" 
+# Will produce a massive amount of output??
+
+#  This may produce a lot of diagnostic information, so you may also find it useful to restrict to a single section.
+#  (or multiple sub-sections)  
+#!debug "\<kelvin\w*\>" ".*idols.*"
+# Error: Unable to process line: !debug "\<kelvin\w*\>" ".*idols.*"
 
-!debug regular-expression
 
 Quickbook
 Doxygen
@@ -69,6 +86,9 @@
 mainpage
 
 # Several warnings in \warnings comments
+#  the index term is only found when the word "warning" is the in the text of the warning.
+# \warning This says warning so IS indexed.
+# The Doxygen command \warning itself does NOT create an indexable item.
 warning
 # Mentioned in Doxygen \details comment in my_library_example.cpp
 markup

Modified: sandbox/guild/mylibrary/libs/mylibrary/doc/mylibrary.pdf
==============================================================================
Binary files. No diff available.

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-28 10:26:44 EST (Mon, 28 Feb 2011)
@@ -1,4 +1,4 @@
-[article Creating Boost HTML and PDF documentation using Quickbook, Doxygen and Auto-Indexing.
+[article mylibrary - a template for Creating Boost HTML and PDF documentation using Quickbook, Doxygen and Auto-Indexing.
     [quickbook 1.5]
     [id my_library_template]
     [copyright 2011 Paul A. Bristow]
@@ -53,9 +53,9 @@
 [important This is a template, NOT an official Boost library.]
 
 [/ Examples of links to classes in own files.]
-[note Comments and suggestions (even bugs!) to Paul.A.Bristow (at) hetp (dot) u-net (dot) com]
+[note Comments and suggestions (even bugs!) to Paul.A.Bristow (at) hetp (dot) u-net (dot) com.]
 
-A printer-friendly PDF version of this manual is also available.
+[note A printer-friendly PDF version of this manual is also available.]
 
 [section:intro Introduction]
 [/ It is a good idea to give *all* sections an id - which must follow section: with *no* space(s).]
@@ -124,7 +124,7 @@
 
 __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 some handy hints and tips (based on the many pitfalls discovered en route).
@@ -181,32 +181,6 @@
 specification of the auto-index.exe.  So follow these instructions carefully,
 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.]
-
-[/Include the class, function, typedef, and macro indexes, and also a full index with <index/>]
-'''
-  
-  <index type="class_name">
-   <title>Class Index</title>
-  </index>
-  
-  <index type="function_name">
-   <title>Function Index</title>
-  </index>
-  
-  <index type="typedef_name">
-  <title>Typedef Index</title>
-  </index>
-  
-  <index type="macro_name">
-  <title>Macro Index</title>
-  </index>
-
-  <index/>
-
-'''
-
 This is some ['junk] that should [*never] be indexed!
 (because it is excluded in the index script file mylibrary.idx).
 
@@ -227,7 +201,7 @@
 you can easily place a constraint on which sections are examined for a particular term.
 
 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 only in the idols section, and Voltaire only in the indexing section,
 but Twain in all sections, you might then add:
 
 [pre
@@ -262,7 +236,7 @@
 
 Mark Twain [*should] get an index entry both here and in the idols section.
 
-Voltaire should only get an index entry here, and [*not] in idols section.
+Voltaire should (perversely) only get an "how to get indexes.. " index entry, and [*not] in idols section.
 
 [endsect] [/section:idols Idols]
 
@@ -271,11 +245,21 @@
 Last edit to Quickbook file __FILENAME__ was at __TIME__ on __DATE__.
 
 [tip This should appear on the pdf version 
-(but may be redundant on html where the last edit date is on the first page).]
+(but may be redundant on a html version where the last edit date is on the first (home) page).]
 [/See also Adobe Reader pdf File Properties for creation date, and PDF producer, version and page count.]
 
 [endsect] [/section:version_id Version Info]
 
+[xinclude autodoc.xml] [/ Using Doxygen reference documentation.]
+[/ The position of this in the Quickbook determines the location of the Doxygen references section.]
+[/ Index(es) should be invoked in the main module, not within a section.]
+
+[? enable_index
+'''
+  <index/>
+'''
+]
+
 [/ All your .qbk documentation files should append a copyright claim and license like this (with your name of course).]
 [/ mylibrary.qbk
   Copyright 2011 Paul A. Bristow.