MPL docs: README, build script, and numerous fixes to bring up docs generation (unfinished)

[SVN r46462]

doc/src/README.txt

@@ -0,0 +1,39 @@
+
+Building the documenation
+*************************
+
+Prerequisites
+-------------
+
+* Python_ 2.3 or higher
+
+* Docutils_ 0.4 or higher
+
+* Docutils `HTML/frames writer`_ from Docutils Sandbox. Download it as 
+  a part of daily `Sandbox snapshot`_ at or get it from the `Docutils' 
+  Subversion repository`_.
+
+
+Building
+--------
+
+1. Install prerequisites.
+
+2. Make sure your Python ``Scripts`` directory  (e.g. ``C:\Python25\Scripts``) 
+   is in your search path.
+
+3. Go to ``$BOOST_ROOT/libs/mpl/doc/src/docutils`` directory and do 
+   ``python setup.py install`` to install MPL-specific HTML/refdoc Docutils 
+   writer.
+
+4. Do ``python build.py``. It's going to take a couple of minutes to finish.
+
+5. If all goes well, the resulting HTML docs will be placed in
+   ``$BOOST_ROOT/libs/mpl/doc/src/refmanual/build/`` directory.
+
+
+.. _Python: http://python.org/
+.. _Docutils: http://docutils.sourceforge.net/
+.. _HTML/frames writer: http://docutils.sourceforge.net/sandbox/agurtovoy/html_frames/
+.. _Sandbox snapshot: http://docutils.sourceforge.net/docutils-sandbox-snapshot.tgz
+.. _Docutils' Subversion repository: http://docutils.sourceforge.net/docs/dev/repository.html

doc/src/build.py

@@ -0,0 +1,30 @@
+# Copyright (c) Aleksey Gurtovoy 2008
+#
+# Distributed under the Boost Software License, Version 1.0.
+# (See accompanying file LICENSE_1_0.txt or copy at
+# http://www.boost.org/LICENSE_1_0.txt)
+
+import shutil
+import os
+
+
+def build():
+
+   def cleanup():
+       if os.path.exists( 'refmanual.gen' ):
+           os.unlink( 'refmanual.gen' )
+
+       if os.path.exists( 'build' ):
+           shutil.rmtree( 'build' )
+
+   def generate_html():
+       os.system( 'python refmanual.py' )
+       os.mkdir( 'build' )
+       os.system( 'rst2htmlrefdoc.py -g -d -t --no-frames --traceback refmanual.gen build/refmanual.html' )
+
+   os.chdir( 'refmanual' )
+   cleanup()
+   generate_html()
+
+
+build()

doc/src/docutils/setup.py

@@ -0,0 +1,23 @@
+#!/usr/bin/env python
+
+# Copyright Aleksey Gurtovoy 2007-2008
+#
+# Distributed under the Boost Software License, Version 1.0. 
+# (See accompanying file LICENSE_1_0.txt or copy at 
+# http://www.boost.org/LICENSE_1_0.txt)
+
+
+import sys, os
+from distutils.core import setup
+
+setup(
+    name="html_refdoc",
+    version=".1",
+    description="convert C++ rst documentation to a set of HTML pages/frames.",
+    author="Aleksey Gurtovoy",
+    author_email="agurtovoy@meta-comm.com",
+    packages=['docutils.writers.html4_refdoc'],
+    package_dir={'docutils.writers.html4_refdoc': 'writers/html4_refdoc'},
+    package_data={'docutils.writers.html4_refdoc': ['frames.css']},
+    scripts=["tools/rst2htmlrefdoc.py"],
+    )

doc/src/docutils/tools/rst2htmlrefdoc.py

@@ -0,0 +1,22 @@
+#!/usr/bin/env python
+
+# Copyright Aleksey Gurtovoy 2004-2008
+#
+# Distributed under the Boost Software License, Version 1.0. 
+# (See accompanying file LICENSE_1_0.txt or copy at 
+# http://www.boost.org/LICENSE_1_0.txt)
+
+
+import locale
+try:
+    locale.setlocale(locale.LC_ALL, '')
+except:
+    pass
+
+from docutils.core import publish_cmdline, default_description
+
+
+description = ('Generates "framed" (X)HTML documents from standalone reStructuredText '
+               'sources.  ' + default_description)
+
+publish_cmdline(writer_name='html4_refdoc', description=description)

doc/src/docutils/writers/html4_refdoc/__init__.py

@@ -0,0 +1,231 @@
+
+# Copyright Aleksey Gurtovoy 2004-2008
+#
+# Distributed under the Boost Software License, Version 1.0. 
+# (See accompanying file LICENSE_1_0.txt or copy at 
+# http://www.boost.org/LICENSE_1_0.txt)
+
+from docutils.writers import html4_frames
+from docutils.writers import html4css1
+from docutils import nodes
+
+import re
+import string
+
+
+class Writer(html4_frames.Writer):
+        
+    def __init__(self):
+        self.__super = html4_frames.Writer
+        self.__super.__init__(self)
+        self.translator = refdoc_translator
+
+
+class refdoc_translator(html4_frames.frame_pages_translator):
+
+    tocframe_width = 25
+    
+    def __init__(self, document, index_page, page_files_dir, extension):
+        self.docframe += ' refmanual'
+        self.__super = html4_frames.frame_pages_translator
+        self.__super.__init__(self, document, index_page, page_files_dir, extension)
+        self.page_translator = hacked_html_translator
+        self.re_include = re.compile(r'(\s*#include\s+<)(.*?\.hpp)?(>\s*)?')
+        self.re_identifier = re.compile(r'(.*?\W*)(\w+)(\W.*?)?')
+        self.re_modtime = re.compile(r'\s*modtime:\s*(.*)')
+        self.in_literal_block = 0
+        self.in_reference = 0
+
+
+    def visit_title(self, node):
+        old_len = len(self.active_visitor().body)
+        self.__super.visit_title(self, node)
+        
+        self = self.active_visitor()
+        if len(self.body) - old_len > 1 and not node.has_key('refid'):
+            name = nodes.make_id(node.astext())
+            self.body[-1] = self.starttag(
+                  {}, 'a', '', name=name, href='#%s' % name, CLASS='subsection-title'
+                )
+
+    def depart_title(self, node):
+        self.__super.depart_title(self, node)
+
+
+    def visit_reference(self, node):
+        self.in_reference = 1
+        if len(node) == 1 and isinstance(node[0], nodes.literal) and node[0].has_key('class'):
+            if node.has_key('class') and node['class'].find(node[0]['class']) == -1:
+                node['class'] += ' %s' % node[0]['class']
+            else:
+                node['class'] = node[0]['class']
+            
+        self.__super.visit_reference(self, node)
+
+
+    def depart_reference(self, node):
+        self.__super.depart_reference(self, node)
+        self.in_reference = 0
+
+
+    def visit_literal(self, node):
+        if self.in_reference:
+            self.__super.visit_literal(self, node)
+     
+        base = self
+        self = self.active_visitor()
+
+        self.body.append(self.starttag(node, 'tt', '', CLASS='literal'))
+        text = node.astext()
+
+        if base.re_include.search(text):
+            text = base.re_include.sub(lambda m: base._handle_include_sub(self, m), text)
+            self.body.append('<span class="pre">%s</span>' % text)
+        else:
+            for token in self.words_and_spaces.findall(text):
+                if token.strip():
+                    if base.re_identifier.search(token):
+                        token = base.re_identifier.sub(lambda m: base._handle_id_sub(self, m), token)
+                    else:
+                        token = self.encode(token)
+
+                    self.body.append('<span class="pre">%s</span>' % token)
+                elif token in ('\n', ' '):
+                    # Allow breaks at whitespace:
+                    self.body.append(token)
+                else:
+                    # Protect runs of multiple spaces; the last space can wrap:
+                    self.body.append('&nbsp;' * (len(token) - 1) + ' ')
+
+        self.body.append('</tt>')
+        # Content already processed:
+        raise nodes.SkipNode
+
+
+    def visit_literal_block(self, node):
+        self.__super.visit_literal_block(self, node)
+        self.in_literal_block = True
+
+    def depart_literal_block(self, node):
+        self.__super.depart_literal_block(self, node)
+        self.in_literal_block = False
+
+
+    def visit_Text(self, node):
+        if not self.in_literal_block:
+            self.__super.visit_Text(self, node)
+        else:
+            base = self
+            self = self.active_visitor()
+            
+            text = node.astext()            
+            if base.re_include.search(text):
+                text = base.re_include.sub(lambda m: base._handle_include_sub(self, m), text)
+            elif base.re_identifier.search(text):
+                text = base.re_identifier.sub(lambda m: base._handle_id_sub(self, m), text)
+            else:
+                text = self.encode(text)
+            
+            self.body.append(text)
+
+
+    def depart_Text(self, node):
+        pass
+
+
+    def visit_substitution_reference(self, node):
+        # debug help
+        print 'Unresolved substitution_reference:', node.astext()
+        raise nodes.SkipNode
+
+    def _handle_depart_page(self, translator, node):
+        pass
+
+
+    def _handle_include_sub(base, self, match):
+        if not match.group(2) or not match.group():
+            return self.encode(match.group(0))
+
+        header = match.group(2)
+        result = self.encode(match.group(1))
+        result += '<a href="%s" class="header">%s</a>' \
+                        % ( '../../../../%s' % header
+                          , self.encode(header)
+                          )
+        
+        result += self.encode(match.group(3))
+        return result
+
+    
+    def _handle_id_sub(base, self, match):
+        identifier = match.group(2)        
+        if not base.document.has_name( identifier.lower() ):
+            return self.encode(match.group(0))
+        
+        result = self.encode(match.group(1))
+        result += '<a href="%s" class="identifier">%s</a>' \
+                        % ( base._chunk_ref( base._active_chunk_id(), base.document.nameids[identifier.lower()] )
+                          , self.encode(identifier)
+                          )
+        
+        if match.group(3):
+            result += self.encode(match.group(3))
+
+        return result
+
+
+class hacked_html_translator(nodes.NodeVisitor):
+        
+    def __init__(self, document):
+        self.__super = nodes.NodeVisitor
+        self.__super.__init__(self, document)
+        self.base = html4css1.HTMLTranslator(document)
+        self.body = self.base.body
+        self.head = self.base.head
+        self.astext = self.base.astext
+        self.starttag = self.base.starttag
+        self.words_and_spaces = self.base.words_and_spaces
+        self.encode = self.base.encode
+        self.recursion_level = 0
+
+    def visit_section(self, node):
+        if self.base.section_level == 1:
+            self.base.section_level = 2
+            
+        self.base.body_prefix = self.body_prefix
+        self.base.visit_section(node)
+        
+    def depart_section(self, node):
+        self.base.depart_section(node)
+        if self.base.section_level == 2:
+            self.base.section_level = 1
+ 
+
+    def visit_generated(self, node):
+        if node.get('class', '') == 'sectnum':
+            node[0].data = string.strip(node[0].data, u'\u00a0')
+            
+        self.base.visit_generated(node)
+
+    def depart_generated(self, node):
+        self.base.depart_generated(node)
+
+
+def _setup_forwarding(visitor):
+    for name in nodes.node_class_names:
+        if not getattr(visitor, 'visit_' + name, None):
+        
+            def forward_visit(self, node, name=name):
+                self.recursion_level += 1
+                #print '%svisit_%s' % ( '+' * self.recursion_level, name )
+                getattr(self.base, 'visit_' + name)(node)
+
+            def forward_depart(self, node, name=name):
+                #print '%sdepart_%s' % ( '-' * self.recursion_level, name )
+                self.recursion_level -= 1
+                getattr(self.base, 'depart_' + name)(node)
+            
+            setattr(visitor, 'visit_' + name, forward_visit)
+            setattr(visitor, 'depart_' + name, forward_depart)
+
+_setup_forwarding(hacked_html_translator)

doc/src/docutils/writers/html4_refdoc/frames.css

@@ -0,0 +1,205 @@
+/*
+Copyright Aleksey Gurtovoy 2004-2008
+
+Distributed under the Boost Software License, Version 1.0. 
+(See accompanying file LICENSE_1_0.txt or copy at 
+http://www.boost.org/LICENSE_1_0.txt)
+*/
+
+@import url(default.css);
+
+div.section h1
+{
+    margin-top: 0pt;
+    margin-bottom: 0pt;
+}
+
+
+div.section h3
+{
+    margin-bottom: 0pt;
+    padding-bottom: 0pt;
+
+/*
+    padding-left: 1pt;
+    border-style: none none solid none ;
+    border-width: 2px;
+    border-color: #f0a0a0;
+*/
+}
+
+p
+{
+    margin-top: 7pt;
+    padding-top: 0pt;
+}
+
+pre.literal-block
+{
+    border-style: none none none solid;
+    border-width: 1px;
+    border-color: black;
+    padding-top: 1pt;
+    padding-bottom: 1pt;
+    padding-left: 1em;
+    margin-top: 10pt;
+    margin-left: 0pt;
+    background-color: #f5f5f5;
+}
+
+td pre.literal-block
+{
+    border-style: none;
+    margin-top: 0pt;
+    padding-left: 1pt;
+}
+
+tt.literal {
+    background-color: #f5f5f5;
+}
+
+body.docframe {
+    background: #fffff5 url(manual.png) no-repeat top right fixed;
+    margin-right: 25pt;
+}
+
+/*
+span.navigation-group {
+    background-color: #f0f5ff;
+}
+*/
+
+table
+{
+    border: solid 1px; 
+    border-collapse: collapse;
+}
+
+table td
+{
+    margin-top: 0pt;
+    margin-bottom: 0pt;
+    padding-top: 2pt; 
+    padding-bottom: 3pt; 
+}
+
+a.ref-subsection-title
+{
+    text-decoration: none;
+    color: black;
+}
+
+table.table
+{
+    border: solid 1px black; 
+    border-collapse: collapse;
+}
+
+table.table td
+, table.table th
+{
+    border: solid 1px black; 
+}
+
+table.wrapper
+{
+    border: 0px; 
+    width: 100%;
+    margin-top: 0px;
+    margin-left: 0px;
+    margin-bottom: 0px;
+}
+
+table.wrapper td
+{
+    padding-left: 0px;
+    padding-right: 0px;
+    padding-bottom: 0px;
+    vertical-align: middle;
+}
+
+table.wrapper td.right
+{
+    padding-left: 0px;
+    text-align: right;
+}
+
+table.wrapper td.right img
+{
+    float: right;
+    border-width: 0px;
+}
+
+/*
+a:link,
+a:visited
+{
+    color: #505050;
+}
+
+sup a:link,
+sup a:visited,
+a.interlink:link,
+a.interlink:visited
+{
+    color: #505050;
+    text-decoration: none;
+}
+*/
+
+a.subsection-title
+{
+    color: black;
+    text-decoration: none;
+}
+
+ a.identifier
+,a.header
+{
+    color: black;
+    text-decoration: none;
+}
+
+ a.identifier:hover
+,a.header:hover
+{
+/*    color: #0000c0;*/
+    background-color: #eeeeee;
+}
+
+
+hr.navigation-bar-separator {
+    width: 100%;
+    clear: both;
+}
+
+span.navigation-bar {
+    float: left;
+}
+
+span.page-location {
+    float: right;
+}
+
+body.tocframe ul.auto-toc,
+ul.auto-toc {
+    list-style-type: none;
+    margin-left: 0pt;
+}
+
+ul.auto-toc li li,
+body.tocframe ul.auto-toc li li {
+    list-style-type: none;
+    margin-left: 15pt;
+}
+
+body.tocframe ul.toc,
+ul.toc {
+    margin-left: 0pt;
+}
+
+body.tocframe ul.toc li,
+ul.toc li {
+    list-style-type: circle;
+    margin-left: 15pt;
+}

doc/src/refmanual/AUX_LAMBDA_SUPPORT.rst

@@ -102,5 +102,4 @@ See also
 |Macros|, |Metafunctions|, |Lambda Expression|
 
 
-.. |PP-tuple| replace:: `PP-tuple`__
+.. |PP-tuple| replace:: `PP-tuple <http://www.boost.org/libs/preprocessor/doc/data/tuples.html>`__
-__ http://www.boost.org/libs/preprocessor/doc/data/tuples.html

doc/src/refmanual/Acknowledgements.rst

@@ -1,9 +1,9 @@
 
-
 .. Copyright Aleksey Gurtovoy, David Abrahams 2007.
 .. Distributed under the Boost
 .. Software License, Version 1.0. (See accompanying
 .. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
 The format and language of this reference documentation has been greatly influenced by 
 the SGI's `Standard Template Library Programmer's Guide`__.
 

doc/src/refmanual/Algorithms-Iteration.rst

@@ -1,9 +1,9 @@
 
-
 .. Copyright Aleksey Gurtovoy, David Abrahams 2007.
 .. Distributed under the Boost
 .. Software License, Version 1.0. (See accompanying
 .. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
 Iteration algorithms are the basic building blocks behind many of the 
 MPL's algorithms, and are usually the first place to look at when 
 starting to build a new one. Abstracting away the details of sequence 

doc/src/refmanual/Algorithms-Querying.rst

@@ -1,7 +1,7 @@
 
-
 .. Copyright Aleksey Gurtovoy, David Abrahams 2007.
 .. Distributed under the Boost
 .. Software License, Version 1.0. (See accompanying
 .. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
 .. |Querying Algorithms| replace:: `Querying Algorithms`_

doc/src/refmanual/Algorithms-Runtime.rst

@@ -1,9 +1,9 @@
 
-
 .. Copyright Aleksey Gurtovoy, David Abrahams 2007.
 .. Distributed under the Boost
 .. Software License, Version 1.0. (See accompanying
 .. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
 .. The MPL *runtime algorithms* provide out-of-box support for the
    common scenarios of crossing compile time/runtime boundary.
 

doc/src/refmanual/Algorithms-Transformation.rst

@@ -1,9 +1,9 @@
 
-
 .. Copyright Aleksey Gurtovoy, David Abrahams 2007.
 .. Distributed under the Boost
 .. Software License, Version 1.0. (See accompanying
 .. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
 According to their name, MPL's *transformation*, or *sequence-building
 algorithms* provide the tools for building new sequences from the existing
 ones by performing some kind of transformation. A typical transformation 

doc/src/refmanual/Algorithms.rst

@@ -1,9 +1,9 @@
 
-
 .. Copyright Aleksey Gurtovoy, David Abrahams 2007.
 .. Distributed under the Boost
 .. Software License, Version 1.0. (See accompanying
 .. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
 The MPL provides a broad range of fundamental algorithms aimed to 
 satisfy the majority of sequential compile-time data processing 
 needs. The algorithms include compile-time counterparts
@@ -40,6 +40,5 @@ common functionality documented by the |Reversible Algorithm|
 concept.
 
 
-.. |Output Iterator| replace:: `Output Iterator <http://www.sgi.com/tech/stl/OutputIterator.html>`_
+.. |Output Iterator| replace:: `Output Iterator <http://www.sgi.com/tech/stl/OutputIterator.html>`__
-.. |sequence algorithms| replace:: `sequence algorithms`__
+.. |sequence algorithms| replace:: `sequence algorithms <|Algorithms link|>`__
-__ `Algorithms`_

doc/src/refmanual/AssociativeSequence.rst

@@ -114,8 +114,8 @@ See also
 |Sequences|, |Extensible Associative Sequence|, |has_key|, |count|, |order|, |at|, |key_type|, |value_type|
 
 
-.. |key| replace:: `key`__
+.. |key| replace:: `key <|key-part_link|>`__
-__ `key-part`_
+.. |key-part_link| replace:: `key-part`_
 
-.. |value| replace:: `value`__
+.. |value| replace:: `value <|value-part_link|>`__
-__ `value-part`_
+.. |value-part_link| replace:: `value-part`_

doc/src/refmanual/CFG_NO_PREPROCESSED.rst

@@ -40,5 +40,4 @@ See also
 
 |Macros|, |Configuration|
 
-.. |preprocessed headers| replace:: `preprocessed headers`__
+.. |preprocessed headers| replace:: `preprocessed headers <|BOOST_MPL_CFG_NO_PREPROCESSED_HEADERS link|>`__
-__ `BOOST_MPL_CFG_NO_PREPROCESSED_HEADERS`_

doc/src/refmanual/Categorized.rst

@@ -1,9 +1,9 @@
 
-
 .. Copyright Aleksey Gurtovoy, David Abrahams 2007.
 .. Distributed under the Boost
 .. Software License, Version 1.0. (See accompanying
 .. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
 .. _`Categorized`:
 
 Concepts

doc/src/refmanual/Data.rst

@@ -1,9 +1,9 @@
 
-
 .. Copyright Aleksey Gurtovoy, David Abrahams 2007.
 .. Distributed under the Boost
 .. Software License, Version 1.0. (See accompanying
 .. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
 .. _`Data`:
 
 .. |Data Types| replace:: `Data Types`_

doc/src/refmanual/Iterators-Concepts.rst

@@ -1,5 +1,4 @@
 
-
 .. Copyright Aleksey Gurtovoy, David Abrahams 2007.
 .. Distributed under the Boost
 .. Software License, Version 1.0. (See accompanying

doc/src/refmanual/Iterators-Metafunctions.rst

@@ -1,9 +1,9 @@
 
-
 .. Copyright Aleksey Gurtovoy, David Abrahams 2007.
 .. Distributed under the Boost
 .. Software License, Version 1.0. (See accompanying
 .. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
 From the implementation standpoint, iterators are almost-opaque types which
 guarantee to provide us with the only memeber that we can access directly:
 their category. Incrementing, dereferencing and the rest of iterator 

doc/src/refmanual/Iterators.rst

@@ -1,9 +1,9 @@
 
-
 .. Copyright Aleksey Gurtovoy, David Abrahams 2007.
 .. Distributed under the Boost
 .. Software License, Version 1.0. (See accompanying
 .. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
 Iterators are generic means of addressing a particular element or a range 
 of sequential elements in a sequence. They are also a mechanism that makes
 it possible to decouple `algorithms`__ from concrete compile-time `sequence 

doc/src/refmanual/Macros-Asserts.rst

@@ -1,5 +1,4 @@
 
-
 .. Copyright Aleksey Gurtovoy, David Abrahams 2007.
 .. Distributed under the Boost
 .. Software License, Version 1.0. (See accompanying

doc/src/refmanual/Macros-Configuration.rst

@@ -1,7 +1,7 @@
 
-
 .. Copyright Aleksey Gurtovoy, David Abrahams 2007.
 .. Distributed under the Boost
 .. Software License, Version 1.0. (See accompanying
 .. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
 .. |Configuration| replace:: `Configuration`_

doc/src/refmanual/Macros.rst

@@ -1,9 +1,9 @@
 
-
 .. Copyright Aleksey Gurtovoy, David Abrahams 2007.
 .. Distributed under the Boost
 .. Software License, Version 1.0. (See accompanying
 .. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
 Being a *template* metaprogramming framework, the MPL concentrates on 
 getting one thing done well and leaves most of the clearly 
 preprocessor-related tasks to the corresponding specialized 

doc/src/refmanual/Metafunctions-Arithmetic.rst

@@ -1,10 +1,8 @@
 
-
 .. Copyright Aleksey Gurtovoy, David Abrahams 2007.
 .. Distributed under the Boost
 .. Software License, Version 1.0. (See accompanying
 .. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
-.. |Arithmetic Operations| replace:: `Arithmetic Operations`_
 
-.. |arithmetic| replace:: `arithmetic`__
+.. |Arithmetic Operations| replace:: `Arithmetic Operations`_
-__ `Arithmetic Operations`_
+.. |arithmetic| replace:: `arithmetic <|Arithmetic Operations|>`__

doc/src/refmanual/Metafunctions-Bitwise.rst

@@ -1,10 +1,8 @@
 
-
 .. Copyright Aleksey Gurtovoy, David Abrahams 2007.
 .. Distributed under the Boost
 .. Software License, Version 1.0. (See accompanying
 .. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
-.. |Bitwise Operations| replace:: `Bitwise Operations`_
 
-.. |bitwise| replace:: `bitwise`__
+.. |Bitwise Operations| replace:: `Bitwise Operations`_
-__ `Bitwise Operations`_
+.. |bitwise| replace:: `bitwise <|Bitwise Operations|>`__

doc/src/refmanual/Metafunctions-Comparisons.rst

@@ -1,10 +1,8 @@
 
-
 .. Copyright Aleksey Gurtovoy, David Abrahams 2007.
 .. Distributed under the Boost
 .. Software License, Version 1.0. (See accompanying
 .. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
-.. |Comparisons| replace:: `Comparisons`_
 
-.. |comparison| replace:: `comparison`__
+.. |Comparisons| replace:: `Comparisons`_
-__ `Comparisons`_
+.. |comparison| replace:: `comparison <|Comparisons|>`__

doc/src/refmanual/Metafunctions-Composition.rst

@@ -1,12 +1,9 @@
 
-
 .. Copyright Aleksey Gurtovoy, David Abrahams 2007.
 .. Distributed under the Boost
 .. Software License, Version 1.0. (See accompanying
 .. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 .. |Composition and Argument Binding| replace:: `Composition and Argument Binding`_
 
-.. |composition| replace:: `composition`__
+.. |composition| replace:: `composition <|Composition and Argument Binding link|>`__
-.. |argument binding| replace:: `argument binding`__
+.. |argument binding| replace:: `argument binding <|Composition and Argument Binding link|>`__
-__ `Composition and Argument Binding`_
-__ `Composition and Argument Binding`_

doc/src/refmanual/Metafunctions-Conditional.rst

@@ -1,8 +1,7 @@
 
-
 .. Copyright Aleksey Gurtovoy, David Abrahams 2007.
 .. Distributed under the Boost
 .. Software License, Version 1.0. (See accompanying
 .. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
-.. |control flow| replace:: `control flow`__
+
-__ `Control Flow`_
+.. |control flow| replace:: `control flow <|Control Flow link|>`__

doc/src/refmanual/Metafunctions-Invocation.rst

@@ -1,8 +1,7 @@
 
-
 .. Copyright Aleksey Gurtovoy, David Abrahams 2007.
 .. Distributed under the Boost
 .. Software License, Version 1.0. (See accompanying
 .. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
-.. |invocation| replace:: `invocation`__
+
-__ `Invocation`_
+.. |invocation| replace:: `invocation <|Invocation link|>`__

doc/src/refmanual/Metafunctions-Logical.rst

@@ -1,11 +1,9 @@
 
-
 .. Copyright Aleksey Gurtovoy, David Abrahams 2007.
 .. Distributed under the Boost
 .. Software License, Version 1.0. (See accompanying
 .. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
-.. |logical| replace:: `logical`__
-__ `Logical Operations`_
 
+.. |logical| replace:: `logical <|Logical Operations|>`__
 .. |Logical Operations| replace:: `Logical Operations`_
 .. |logical operations| replace:: `logical operations`_

doc/src/refmanual/Metafunctions-Trivial.rst

@@ -1,9 +1,9 @@
 
-
 .. Copyright Aleksey Gurtovoy, David Abrahams 2007.
 .. Distributed under the Boost
 .. Software License, Version 1.0. (See accompanying
 .. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
 The MPL provides a number of |Trivial Metafunction|\ s that a nothing more than
 thin wrappers for a differently-named class nested type members. While important
 in the context of `in-place metafunction composition`__, these metafunctions have
@@ -23,22 +23,13 @@ Trivial Metafunctions Summary
 
 In the following table, ``x`` is an arbitrary class type.
 
-.. |first| replace:: |``first``|__
+.. |first| replace:: `:refentry:`first` <|first link|>`__
-.. |``first``| replace:: :refentry:`first`
+.. |second| replace:: `:refentry:`second` <|second link|>`__
-
+.. |base| replace:: `:refentry:`base` <|base link|>__
-__ `trivial-first`_
-
-.. |second| replace:: |``second``|__
-.. |``second``| replace:: :refentry:`second`
-
-__ `trivial-second`_
-
-
-.. |base| replace:: |``base``|__
-.. |``base``| replace:: :refentry:`base`
-
-__ `trivial-base`_
 
+.. |first link| replace:: `trivial-first`_
+.. |second link| replace:: `trivial-second`_
+.. |base link| replace:: `trivial-base`_
 
 
 .. _`trivial-first`:
@@ -62,5 +53,4 @@ See Also
 
 |Metafunctions|, |Trivial Metafunction|
 
-.. |Trivial Metafunctions| replace:: `Trivial Metafunctions`__
+.. |Trivial Metafunctions| replace:: `Trivial Metafunctions <|Trivial link|>`__
-__ `Trivial`_

doc/src/refmanual/Metafunctions-Type.rst

@@ -1,8 +1,7 @@
 
-
 .. Copyright Aleksey Gurtovoy, David Abrahams 2007.
 .. Distributed under the Boost
 .. Software License, Version 1.0. (See accompanying
 .. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
-.. |type selection| replace:: `type selection`__
+
-__ `Type Selection`_
+.. |type selection| replace:: `type selection <|Type Selection link|>`__

doc/src/refmanual/Metafunctions.rst

@@ -1,9 +1,9 @@
 
-
 .. Copyright Aleksey Gurtovoy, David Abrahams 2007.
 .. Distributed under the Boost
 .. Software License, Version 1.0. (See accompanying
 .. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
 The MPL includes a number of predefined metafunctions that can be roughly
 classified in two categories: `general purpose metafunctions`, dealing with
 conditional |type selection| and higher-order metafunction |invocation|, 

doc/src/refmanual/Sequences-Classes.rst

@@ -1,9 +1,9 @@
 
-
 .. Copyright Aleksey Gurtovoy, David Abrahams 2007.
 .. Distributed under the Boost
 .. Software License, Version 1.0. (See accompanying
 .. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
 The MPL provides a large number of predefined general-purpose sequence 
 classes covering most of the typical metaprogramming needs out-of-box.
 

doc/src/refmanual/Sequences-Concepts.rst

@@ -1,9 +1,9 @@
 
-
 .. Copyright Aleksey Gurtovoy, David Abrahams 2007.
 .. Distributed under the Boost
 .. Software License, Version 1.0. (See accompanying
 .. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
 The taxonomy of sequence concepts in MPL parallels the taxonomy of the MPL 
 |iterators|, with two additional classification dimensions: 
 `extensibility` and `associativeness`. 
@@ -29,5 +29,4 @@ The taxonomy of sequence concepts in MPL parallels the taxonomy of the MPL
    the common parts of different sequence classes' specifications.
 
 
-.. |sequence concepts| replace:: `sequence concepts`__ 
+.. |sequence concepts| replace:: `sequence concepts <|Sequences/Concepts link|>`__ 
-__ `label-Sequences-Concepts`_

doc/src/refmanual/Sequences-Intrinsic.rst

@@ -1,9 +1,9 @@
 
-
 .. Copyright Aleksey Gurtovoy, David Abrahams 2007.
 .. Distributed under the Boost
 .. Software License, Version 1.0. (See accompanying
 .. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
 The metafunctions that form the essential interface of sequence `classes`__
 documented in the corresponding |sequence concepts| are known as 
 *intrinsic sequence operations*. They differ from generic 

doc/src/refmanual/Sequences-Views.rst

@@ -1,9 +1,9 @@
 
-
 .. Copyright Aleksey Gurtovoy, David Abrahams 2007.
 .. Distributed under the Boost
 .. Software License, Version 1.0. (See accompanying
 .. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
 A *view* is a sequence adaptor delivering an altered presentation of 
 one or more underlying sequences. Views are lazy, meaning that their 
 elements are only computed on demand. Similarly to the short-circuit 

doc/src/refmanual/Sequences.rst

@@ -1,9 +1,9 @@
 
-
 .. Copyright Aleksey Gurtovoy, David Abrahams 2007.
 .. Distributed under the Boost
 .. Software License, Version 1.0. (See accompanying
 .. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
 Compile-time sequences of types are one of the basic concepts of C++ 
 template metaprogramming. Differences in types of objects being 
 manipulated is the most common point of variability of similar, but 

doc/src/refmanual/TagDispatchedMetafunction.rst

@@ -161,8 +161,5 @@ See also
 |Metafunction|, |Metafunction Class|, |Numeric Metafunction|
 
 
-.. |tag-metafunction| replace:: `tag metafunction`__
+.. |tag-metafunction| replace:: `tag metafunction <|tag-metafunction link|>`__
-__ `tag-metafunction`_
+.. |tag dispatched| replace:: `tag dispatched <|Tag Dispatched Metafunction link|>`__
-
-.. |tag dispatched| replace:: `tag dispatched`__
-__ `Tag Dispatched Metafunction`_

doc/src/refmanual/VariadicSequence.rst

@@ -113,11 +113,7 @@ See also
 
 |Sequences|, |Configuration|, |Integral Sequence Wrapper|
 
-.. |variadic| replace:: `variadic`__
+.. |variadic| replace:: `variadic <|Variadic Sequence link|>`__
-__ `Variadic Sequence`_
+.. |variadic forms| replace:: `variadic forms <|Variadic Sequence link|>`__
-
+.. |numbered forms| replace:: `numbered forms <|Variadic Sequence link|>`__
-.. |variadic forms| replace:: `variadic forms`__
+.. |Variadic Sequence link| replace:: `Variadic Sequence`_
-__ `Variadic Sequence`_
-
-.. |numbered forms| replace:: `numbered forms`__
-__ `Variadic Sequence`_

doc/src/refmanual/bool_.rst

@@ -88,10 +88,5 @@ See also
 |Data Types|, |Integral Constant|, |int_|, |long_|, |integral_c|
 
 
-.. |true_| replace:: |``true_``|__
+.. |true_| replace:: ```true_`` <|bool_ link|>`__
-.. |``true_``| replace:: ``true_``
+.. |false_| replace:: ```false_`` <|bool_ link|>`__
-__ `bool\_`_
-
-.. |false_| replace:: |``false_``|__
-.. |``false_``| replace:: ``false_``
-__ `bool\_`_

doc/src/refmanual/for_each.rst

@@ -141,5 +141,5 @@ See also
 
 |Runtime Algorithms|, |Views|, |transform_view|
 
-.. |unary function object| replace:: `unary function object <http://www.sgi.com/tech/stl/UnaryFunction.html>`_
+.. |unary function object| replace:: `unary function object <http://www.sgi.com/tech/stl/UnaryFunction.html>`__
-.. |value_initialized| replace:: `value_initialized <http://www.boost.org/libs/utility/value_init.htm>`_
+.. |value_initialized| replace:: `value_initialized <http://www.boost.org/libs/utility/value_init.htm>`__

doc/src/refmanual/inserter_.rst

@@ -101,6 +101,4 @@ See also
 
 
 .. |+inserter+| replace:: inserter
-.. |inserter| replace:: |``inserter``|__
+.. |inserter| replace:: ':refentry:`inserter` <|inserter_ link|>'__
-.. |``inserter``| replace:: :refentry:`inserter`
-__ `inserter_`_

doc/src/refmanual/refmanual.py

@@ -20,7 +20,8 @@ def __section_header(section):
     underline = underlines[len(parts) - 1] * len(parts[-1])
     if len(parts) > 0:
         hidden_target = '.. _`label-%s`:' % '-'.join( parts )
-        return '\n%s\n%s\n%s\n\n' % (parts[-1], underline, hidden_target )
+        replacement_link = '.. |%s link| replace:: `label-%s`_' % ( '/'.join( parts ), '-'.join( parts ) )
+        return '\n%s\n%s\n%s\n%s\n\n' % (parts[-1], underline, hidden_target, replacement_link )
     else:
         return '\n%s\n%s\n\n' % (parts[-1], underline )
 
@@ -39,9 +40,10 @@ def __include_page( output, page, name = None ):
     else:    ref = '/'.join( page.split('.')[0].split('-') )
     if ref.upper() == ref or ref.lower() == ref:
         output.write( 
-              ( '.. |%(ref)s| replace:: |``%(ref)s``|__\n'
+              ( '.. |%(ref)s| replace:: `|%(ref)s refentry| <|%(ref)s link|>`__\n'
-                + '.. |``%(ref)s``| replace:: :refentry:`%(ref)s`\n'
+                + '.. |%(ref)s refentry| replace:: :refentry:`%(ref)s`\n'
-                + '__ `%(ref)s`_\n' ) 
+                + '.. |%(ref)s link| replace:: `%(ref)s`_\n'
+                ) 
                     % { 'ref': ref }
             )
     else:

doc/src/refmanual/refmanual.rst

@@ -1,9 +1,9 @@
 
-
 .. Copyright Aleksey Gurtovoy, David Abrahams 2007.
 .. Distributed under the Boost
 .. Software License, Version 1.0. (See accompanying
 .. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
 The MPL Reference Manual
 ************************
 
@@ -29,11 +29,8 @@ __ http://www.boost.org/LICENSE_1_0.txt
 .. contents:: Table of Contents
     :depth: 3
 
-.. |Boost.Bind| replace:: `Boost.Bind`__
+.. |Boost.Bind| replace:: `Boost.Bind <http://www.boost.org/libs/bind/bind.html>`__
-__ http://www.boost.org/libs/bind/bind.html
+.. |Boost.Lambda| replace:: `Boost.Lambda <http://www.boost.org/libs/lambda/doc/index.html>`__
-
-.. |Boost.Lambda| replace:: `Boost.Lambda`__
-__ http://www.boost.org/libs/lambda/doc/index.html
 
 .. role:: refentry(literal)
 
@@ -87,24 +84,19 @@ __ http://www.boost.org/libs/lambda/doc/index.html
 
 .. |O(1)| replace:: *O(1)*
 
-.. |_1| replace:: |``_1``|__
+.. |_1| replace:: `|_1 refentry| <|Placeholders|>`__
-.. |_2| replace:: |``_2``|__
+.. |_2| replace:: `|_2 refentry| <|Placeholders|>`__
-.. |_3| replace:: |``_3``|__
+.. |_3| replace:: `|_3 refentry| <|Placeholders|>`__
-.. |_4| replace:: |``_4``|__
+.. |_4| replace:: `|_4 refentry| <|Placeholders|>`__
-.. |_5| replace:: |``_5``|__
+.. |_5| replace:: `|_5 refentry| <|Placeholders|>`__
-.. |``_1``| replace:: :refentry:`_1`
-.. |``_2``| replace:: :refentry:`_2`
-.. |``_3``| replace:: :refentry:`_3`
-.. |``_4``| replace:: :refentry:`_4`
-.. |``_5``| replace:: :refentry:`_5`
-__ `Placeholders`_
-__ `Placeholders`_
-__ `Placeholders`_
-__ `Placeholders`_
-__ `Placeholders`_
 
-.. |placeholder| replace:: `placeholder`__
+.. |_1 refentry| replace:: :refentry:`_1`
-__ `Placeholders`_
+.. |_2 refentry| replace:: :refentry:`_2`
+.. |_3 refentry| replace:: :refentry:`_3`
+.. |_4 refentry| replace:: :refentry:`_4`
+.. |_5 refentry| replace:: :refentry:`_5`
+
+.. |placeholder| replace:: `placeholder <|Placeholders|>`__
 
 .. |_1,_2,..._n| replace:: |_1|, |_2|, |_3|,\ |...|
 
@@ -130,12 +122,12 @@ __ `Placeholders`_
 
 
 .. |preprocessed headers disclaimer| replace:: [*Note:* Overriding will take effect 
-   *only* if the library is configured not to use `preprocessed headers`__. See 
+   *only* if the library is configured not to use `preprocessed headers 
-   |+BOOST_MPL_CFG_NO_PREPROCESSED_HEADERS+|__ for more information. |--| *end note*\]
+   <|BOOST_MPL_CFG_NO_PREPROCESSED_HEADERS_link|>`__. See 
+   |BOOST_MPL_CFG_NO_PREPROCESSED_HEADERS_ref| for more information. |--| *end note*\]
 
-.. |+BOOST_MPL_CFG_NO_PREPROCESSED_HEADERS+| replace:: :refentry:`BOOST_MPL_CFG_NO_PREPROCESSED_HEADERS`
+.. |BOOST_MPL_CFG_NO_PREPROCESSED_HEADERS_ref| replace:: `:refentry:`BOOST_MPL_CFG_NO_PREPROCESSED_HEADERS` <|BOOST_MPL_CFG_NO_PREPROCESSED_HEADERS_link|>`__
-__ `BOOST_MPL_CFG_NO_PREPROCESSED_HEADERS`_
+.. |BOOST_MPL_CFG_NO_PREPROCESSED_HEADERS_link| replace:: `BOOST_MPL_CFG_NO_PREPROCESSED_HEADERS`_
-__ `BOOST_MPL_CFG_NO_PREPROCESSED_HEADERS`_
 
 
 .. |transformation algorithm disclaimer| replace:: 

doc/src/refmanual/terminology.rst

@@ -1,10 +1,11 @@
 
-
 .. Copyright Aleksey Gurtovoy, David Abrahams 2007.
 .. Distributed under the Boost
 .. Software License, Version 1.0. (See accompanying
 .. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
 .. _`Overloaded name`:
+.. |Overloaded name link| replace:: `Overloaded name`_
 
 Overloaded name
     Overloaded name is a term used in this reference documentation to designate
@@ -13,12 +14,11 @@ Overloaded name
     is implemented by other, unspecified, means.
     
 
-.. |overloaded name| replace:: `overloaded name`__
+.. |overloaded name| replace:: `overloaded name <|Overloaded name link|>`__
-__ `Overloaded name`_
-
 
 
 .. _`Concept-identical`:
+.. |Concept-identical link| replace:: `Concept-identical`_
 
 Concept-identical    
     A sequence ``s1`` is said to be concept-identical to a sequence ``s2`` if 
@@ -26,6 +26,7 @@ Concept-identical
 
 
 .. _`Bind expression`:
+.. |Bind expression link| replace:: `Bind expression`_
 
 Bind expression
     A bind expression is simply that |--| an instantiation of one of the |bind| 
@@ -42,12 +43,5 @@ Bind expression
         _2
 
 
-.. |bind expression| replace:: `bind expression`__
+.. |bind expression| replace:: `bind expression <|Bind expression link|>`__
-__ `Bind expression`_
+.. |concept-identical| replace:: `concept-identical <|Concept-identical link|>`__
-
-
-
-.. |concept-identical| replace:: `concept-identical`__
-__ `Concept-identical`_
-
-