Boost logo

Boost-Commit :

Subject: [Boost-commit] svn:boost r85259 - trunk/tools/quickbook/src
From: dnljms_at_[hidden]
Date: 2013-08-10 05:04:25


Author: danieljames
Date: 2013-08-10 05:04:25 EDT (Sat, 10 Aug 2013)
New Revision: 85259
URL: http://svn.boost.org/trac/boost/changeset/85259

Log:
Improve some id_manager comments.

Text files modified:
   trunk/tools/quickbook/src/id_manager.cpp | 44 ++++++++++++++++++++++++++++-----------
   1 files changed, 31 insertions(+), 13 deletions(-)

Modified: trunk/tools/quickbook/src/id_manager.cpp
==============================================================================
--- trunk/tools/quickbook/src/id_manager.cpp Sat Aug 10 05:04:05 2013 (r85258)
+++ trunk/tools/quickbook/src/id_manager.cpp 2013-08-10 05:04:25 EDT (Sat, 10 Aug 2013) (r85259)
@@ -20,7 +20,7 @@
 
 namespace quickbook
 {
- // TODO: This should possibly try to make ids are generated:
+ // TODO: This should possibly try to always generate valid XML ids:
     // http://www.w3.org/TR/REC-xml/#NT-NameStartChar
 
     //
@@ -38,33 +38,49 @@
     //
     // id_placeholder
     //
+ // When generating the xml, quickbook can't allocate the identifiers until
+ // the end, so it stores in the intermedia xml a placeholder string,
+ // e.g. id="$1". This represents one of these placeholders.
+ //
 
     struct id_placeholder
     {
- enum state_enum { child, unresolved, resolved, generated };
+ enum state_enum {
+ child, // A child id before it's appended to the parent id.
+ unresolved, // Id includes parent's fully generated id.
+ resolved, // Id has been added to the data structures, might
+ // still change if there are any duplicates.
+ generated // The final id which has been altered to avoid
+ // duplicates.
+ };
 
- unsigned index; // The poisition in the placeholder deque.
+ unsigned index; // The index in id_state::placeholders.
+ // Use for the dollar identifiers in
+ // intermediate xml.
         state_enum generation_state;
- // Placeholder's position in generation
- // process.
+ // The stage in the generation process.
         std::string unresolved_id;
- // The id that would be generated without any
- // duplicate handling.
+ // The id that would be generated
+ // without any duplicate handling.
+ // Used for generating old style header anchors.
         std::string id; // The id so far.
         id_placeholder* parent; // Placeholder of the parent id.
- // Only when generation_state == child
+ // Set to 0 if there isn't a parent, or the
+ // parent has been included in the id.
         id_category category;
         unsigned num_dots; // Number of dots in the id.
- // Normally equal to the section level.
+ // Normally equal to the section level
+ // but not when an explicit id contains
+ // dots.
         unsigned order; // Order of the placeholders in the generated
                                 // xml. Stored because it can be slightly
                                 // different to the order they're generated
                                 // in. e.g. for nested tables the cells
                                 // are processed before the title id.
- // Only set when processing ids.
- id_data* data; // Assigned data shared by duplicate ids
- // used to detect them. Only when
- // generation_state == resolved
+ // This is set when processing ids.
+ id_data* data; // Data shared by placeholders with the same
+ // ids.
+ // Only valid when generation_state == resolved
 
         id_placeholder(
                 unsigned index,
@@ -107,6 +123,8 @@
     //
     // id_state
     //
+ // Contains all the data tracked by the id_manager.
+ //
 
     struct file_info;
     struct doc_info;


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