[Boost-commit] svn:boost r65737 - sandbox/variadic_macro_data/libs/variadic_macro_data/doc

Subject: [Boost-commit] svn:boost r65737 - sandbox/variadic_macro_data/libs/variadic_macro_data/doc
From: eldiener_at_[hidden]
Date: 2010-10-03 14:41:19

Author: eldiener
Date: 2010-10-03 14:41:17 EDT (Sun, 03 Oct 2010)
New Revision: 65737
URL: http://svn.boost.org/trac/boost/changeset/65737

Log:
Boost jamfile and quickbook documents
Added:
   sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VMDAcknowledgements.qbk   (contents, props changed)
   sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VMDDesign.qbk   (contents, props changed)
   sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VMDDetail.qbk   (contents, props changed)
   sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VMDFunctionality.qbk   (contents, props changed)
   sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VMDIntroduction.qbk   (contents, props changed)
   sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VMDNaming.qbk   (contents, props changed)
   sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VMDReference.qbk   (contents, props changed)
   sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VMDVariadicMacros.qbk   (contents, props changed)
   sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VariadicMacroData.qbk   (contents, props changed)
   sandbox/variadic_macro_data/libs/variadic_macro_data/doc/jamfile.v2   (contents, props changed)

Added: sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VMDAcknowledgements.qbk
==============================================================================
--- (empty file)
+++ sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VMDAcknowledgements.qbk	2010-10-03 14:41:17 EDT (Sun, 03 Oct 2010)
@@ -0,0 +1,12 @@
+[section:vmd_ack Acknowledgements]
+
+First and foremost I would like to thank Paul Mensonides for providing 
+advice, explanation and code for working with variadic macros and macros 
+in general. Secondly I would like to thank Steve Watanabe for his help, code, 
+and explanations. Finally I have to acknowledge that this library is an amalgam 
+of already known techniques for dealing with variadic macros themselves, 
+among which are techniques published online by Laurent Deniau. I have added 
+design and some cleverness in creating the library but I could not have done 
+it without the previous knowledge of others.
+
+[endsect]

Added: sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VMDDesign.qbk
==============================================================================
--- (empty file)
+++ sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VMDDesign.qbk	2010-10-03 14:41:17 EDT (Sun, 03 Oct 2010)
@@ -0,0 +1,22 @@
+[section:vmd_design Design]
+
+The initial impetus for creating this library is entirely practical. I had been 
+working on another library of macro functionality, which used Boost PP 
+functionality, and I realized that if I could use variadic macros with 
+my other library, the end-user usability for that library would be much easier. 
+Therefore the main design goal of this library is to interoperate variadic macro data 
+with Boost PP in the easiest and clearest way possible.
+
+I also wanted to make the library as orthogonal and as easy to use as possible. 
+Because of this, there is functionality in this library that is really not 
+necessary for someone knowledgable about Boost PP, but it is included in 
+the library even though it is just a convenient shorthand for 
+functionality in Boost PP combined with new functionality in this library.
+This includes a number of the conversions back and forth between variadic
+macro data and Boost PP data types as well as nearly all of the specific 
+Boost PP tuple functionality. As long as there is no run-time programming 
+overhead, and a minimum of compile-time overhead, I value ease of use to 
+be much more important than redundancy, so I added the functionality to 
+this library.
+
+[endsect]

Added: sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VMDDetail.qbk
==============================================================================
--- (empty file)
+++ sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VMDDetail.qbk	2010-10-03 14:41:17 EDT (Sun, 03 Oct 2010)
@@ -0,0 +1,89 @@
+[section:vmd_detail Functional groups]
+
+The macros in the variadic macro data library can best be explained 
+as falling into four groups. These are:
+
+# Macros which directly support variadic macro data usage.
+# Macros which convert variadic macro data to Boost PP data types.
+# Macros which convert Boost PP data types to variadic macro data.
+# Macros which offer an easy to use replacement for Boost PP 
+  tuple macros because they do not require the size of the tuple 
+  to be specified.
+   
+A further general explanation of each of these groups follow, while 
+a specific explanation for each macro can be found in the reference 
+section.
+
+[section:vmd_usage Variadic Usage]
+
+There are two macros which enhance variadic macro data usage. 
+These macros add functionality to variadic macros so that the number 
+of comma-separated tokens in the variadic macro data can be calculated, 
+and that any token among the variadic macro data's comma-separated 
+tokens can be returned. The two macros are:
+
+# VMD_DATA_SIZE(...), which returns the number of comma-separated 
+  tokens.
+# VMD_DATA_ELEM(n,...), which returns a particular token among 
+  the comma-separated sequence. Here 'n' stands for the number of 
+  the token, starting with 0, which is returned from the variadic 
+  macro data.
+   
+[endsect]
+
+[section:vmd_toPP Convert to Boost PP data types]
+
+There are four macros which convert variadic macro data as a whole to 
+each of the four Boost PP data types. These are:
+
+# VMD_DATA_TO_PP_TUPLE(...), which converts to a Boost PP tuple.
+# VMD_DATA_TO_PP_ARRAY(...), which converts to a Boost PP array.
+# VMD_DATA_TO_PP_LIST(...), which converts to a Boost PP list.
+# VMD_DATA_TO_PP_SEQ(...), which converts to a Boost PP sequence.
+   
+[endsect]
+
+[section:vmd_fromPP Convert from Boost PP data types]
+
+There are four macros which convert each of the four Boost PP data 
+types to variadic macro data. These are:
+
+# VMD_PP_TUPLE_TO_DATA(tuple), which converts from a Boost PP tuple.
+# VMD_PP_ARRAY_TO_DATA(array), which converts from a Boost PP array.
+# VMD_PP_LIST_TO_DATA(list), which converts from a Boost PP list.
+# VMD_PP_SEQ_TO_DATA(seq), which converts from a Boost PP sequence.
+
+In these macros the data is returned as a comma-separated list of 
+tokens, which is the format of variadic macro data. The results of 
+any of these macros can be passed to variadic macros as the final 
+parameter.
+
+[endsect]
+
+[section:vmd_tuple Boost PP tuple enhancements]
+
+There are six macros which manipulate Boost PP tuple data. The first is an 
+addition to Boost PP functionality when dealing with tuples while the 
+final five are direct replacements for Boost PP tuple data manipulation 
+macros and which do not require the size of the tuple. These are:
+
+# VMD_PP_TUPLE_SIZE(tuple), which returns the size of the tuple.
+# VMD_PP_TUPLE_ELEM(tuple), which is a replacement for 
+  BOOST_PP_TUPLE_ELEM without having to pass the size of the 
+  tuple as the first parameter.
+# VMD_PP_TUPLE_REM_CTOR(tuple), which is a replacement for 
+  BOOST_PP_TUPLE_REM_CTOR without having to pass the size of the 
+  tuple as the first parameter.
+# VMD_PP_TUPLE_REVERSE(tuple), which is a replacement for 
+  BOOST_PP_TUPLE_REVERSE without having to pass the size of the 
+  tuple as the first parameter.
+# VMD_PP_TUPLE_TO_LIST(tuple), which is a replacement for 
+  BOOST_PP_TUPLE_TO_LIST without having to pass the size of the 
+  tuple as the first parameter.
+# VMD_PP_TUPLE_TO_SEQ(tuple), which is a replacement for 
+  BOOST_PP_TUPLE_TO_SEQ without having to pass the size of the 
+  tuple as the first parameter.
+
+[endsect]
+
+[endsect]

Added: sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VMDFunctionality.qbk
==============================================================================
--- (empty file)
+++ sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VMDFunctionality.qbk	2010-10-03 14:41:17 EDT (Sun, 03 Oct 2010)
@@ -0,0 +1,32 @@
+[section:vmd_functionality Functionality]
+
+The design of Boost PP allows data, in the form of preprocessor 
+tokens, to be grouped together into various data types, any one of 
+which can be treated as a single preprocessor argument to a macro. 
+A number of Boost PP macros accept data as a single argument. Each 
+of these data types also has its own rich set of macros to manipulate 
+the data. It is imperative that when interoperating with Boost PP 
+data be passed as a single argument, even though the data itself 
+may consist of a number of preprocessing tokens.
+
+In variadic macros the data to be passed as variadic macro data is 
+a comma-separated list of arguments, each of which can be any 
+preprocessing token. 
+
+Because the variadic macro data is more than a single token, in 
+order to use variadic macro data with Boost PP, it is 
+necessary to be able to convert the variadic macro data as a whole 
+to a single argument Boost PP data type. Alternatively one can extract 
+from the variadic macro data any given token and use that as a single 
+argument, or possibly combine individual tokens from the variadic 
+macro data into Boost PP data types using the functionality of any 
+given Boost PP data type to do so.
+
+The variadic macro data library provides means to interoperate 
+variadic macro data with Boost PP in either general case.
+
+Outside of Boost PP interoperability, the variadic macro data library 
+allows individual tokens to be extracted from the variadic macro data 
+and used in macro expansion in all the normal ways one may write macros.
+   
+[endsect]

Added: sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VMDIntroduction.qbk
==============================================================================
--- (empty file)
+++ sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VMDIntroduction.qbk	2010-10-03 14:41:17 EDT (Sun, 03 Oct 2010)
@@ -0,0 +1,27 @@
+[section:vmd_intro Introduction]
+
+The variadic macro data library is a library of macros which 
+provide important functionality for variadic macros as well as 
+integrating variadic macros with the Boost preprocessor library, 
+which will afterwards be referred to as just 'Boost PP' in this 
+documentation. It integrates with Boost PP without changing the 
+latter library in any way.
+
+The functionality of the library may be summed up as:
+
+# Providing the means to extract any single token from the 
+  comma-separated data which makes up variadic macro data, 
+  as well as to calculate the number of tokens.
+# Convert variadic macro data to and from Boost PP data types. 
+# Enhance the tuple functionality of Boost PP by providing 
+  a means of calculating the size of a tuple as well as by 
+  providing equivalent macros to Boost PP tuple macros 
+  which do not require the size of the tuple to be explicitly 
+  passed.
+   
+The library is a header only library and all macros in the 
+library are in a single header, whose name is 'VariadicMacroData.hpp'.
+
+The library is dependent on Boost PP.
+   
+[endsect]

Added: sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VMDNaming.qbk
==============================================================================
--- (empty file)
+++ sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VMDNaming.qbk	2010-10-03 14:41:17 EDT (Sun, 03 Oct 2010)
@@ -0,0 +1,24 @@
+[section:vmd_naming Naming conventions]
+
+Currently all of the macros in the library begin with the prefix VMD_, 
+which stands for 'Variadic Macro Data'. If this library were to be 
+accepted into Boost, the macros can easily be changed to use BOOST_VMD_ 
+as the prefix instead.
+
+Following the prefix, certain names in the macros refer to data types 
+in this library or Boost PP. These names and their data 
+types are:
+
+# DATA  = variadic macro data as represented by '...' in a variadic 
+  macro signature and __VA_ARGS__ in variadic macro expansion.
+# TUPLE = Boost PP tuple data type.
+# ARRAY = Boost PP array data type.
+# LIST  = Boost PP list data type.
+# SEQ   = Boost PP sequence data type.
+
+I have used names in order to mimic the naming of Boost PP 
+as closely as possible. Therefore I have used the terms SIZE and ELEM 
+in the macro names because these are the terms in Boost PP to denote 
+the number of tokens of data and the general name for a token.
+
+[endsect]

Added: sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VMDReference.qbk
==============================================================================
--- (empty file)
+++ sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VMDReference.qbk	2010-10-03 14:41:17 EDT (Sun, 03 Oct 2010)
@@ -0,0 +1,3 @@
+[section:vmd_reference Reference]
+[xinclude VariadicMacroDataReference.xml]
+[endsect]

Added: sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VMDVariadicMacros.qbk
==============================================================================
--- (empty file)
+++ sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VMDVariadicMacros.qbk	2010-10-03 14:41:17 EDT (Sun, 03 Oct 2010)
@@ -0,0 +1,26 @@
+[section:vmd_vmacros Variadic Macros]
+
+Variadic macros, as specified by C++0x, is a feature taken from the C99 
+specification. They are macros which take a final parameter denoted as 
+'...' which represents one or more final arguments to the macro as a 
+series of comma-separated tokens. In the macro expansion a special 
+keyword of '__VA_ARGS__' represents the comma-separated tokens. This 
+information when passed to a variadic macro I call 'variadic macro data',
+which gives its name to this library. C99, and by implication C++0x, 
+provides no built-in way of accessing a single token from the 
+comma-separated list of variadic macro data. But this library does 
+provide a means to do that among its other functionality.
+
+[section:vmd_vmacros_Boost Boost support]
+
+Boost until recently has had no generic support for variadic macros 
+based on the ability of a given compiler/version to support C99's variadic 
+macros. This support has now been added to the trunk in the form of 
+a macro which denotes that compiler support for variadic macros does not exist. 
+This macro is BOOST_NO_VARIADIC_MACROS. The variadic macro data library 
+will only work for a compiler/version combination when BOOST_NO_VARIADIC_MACROS 
+is not defined.
+
+[endsect]
+
+[endsect]

Added: sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VariadicMacroData.qbk
==============================================================================
--- (empty file)
+++ sandbox/variadic_macro_data/libs/variadic_macro_data/doc/VariadicMacroData.qbk	2010-10-03 14:41:17 EDT (Sun, 03 Oct 2010)
@@ -0,0 +1,20 @@
+[library The Variadic Macro Data Library
+    [quickbook 1.5]
+    [version 1.0]
+    [id variadic_macro_data]
+    [dirname variadic_macro_data]
+    [copyright 2010 Tropic Software East Inc]
+    [purpose Integration of variadic macro data with the Boost PP library]
+    [category preprocessor]
+    [authors [Diener, Edward]]
+    [source-mode c++]
+]
+
+[include VMDIntroduction.qbk]
+[include VMDVariadicMacros.qbk]
+[include VMDFunctionality.qbk]
+[include VMDNaming.qbk]
+[include VMDDetail.qbk]
+[include VMDReference.qbk]
+[include VMDDesign.qbk]
+[include VMDAcknowledgements.qbk]

Added: sandbox/variadic_macro_data/libs/variadic_macro_data/doc/jamfile.v2
==============================================================================
--- (empty file)
+++ sandbox/variadic_macro_data/libs/variadic_macro_data/doc/jamfile.v2	2010-10-03 14:41:17 EDT (Sun, 03 Oct 2010)
@@ -0,0 +1,67 @@
+# VariadicMacroData documentation Jamfile
+#
+# Copyright (c) 2010
+# Edward Diener
+#
+
+project variadic_macro_data ;
+
+using quickbook ;
+using doxygen ;
+
+import modules ;
+import path ;
+import os ;
+
+local BOOST_ROOT = ../../../ ;
+path-constant local-boost-root : $(BOOST_ROOT) ;
+path-constant nav-images : $(local-boost-root)/doc/src/images/ ; # png and svg images for home, next, note, tip...
+path-constant images_location : html/images/ ; # location of SVG images referenced by Quickbook.
+path-constant here : . ; # convenient to refer to files in the same directory as this jamfile.v2
+
+doxygen VariadicMacroDataReference
+  :
+    [ glob $(here)/../../../boost/variadic_macro_data/VariadicMacroData.hpp ]
+  : 
+    <doxygen:param>PROJECT_NAME="VariadicMacroData"
+    <doxygen:param>PROJECT_NUMBER=1
+    <doxygen:param>SORT_MEMBER_DOCS=NO
+    <doxygen:param>SHOW_INCLUDE_FILES=NO
+    <doxygen:param>MAX_INITIALIZER_LINES=0
+    <doxygen:param>VERBATIM_HEADERS=NO
+;
+
+xml VariadicMacroData
+  :
+    VariadicMacroData.qbk
+  :
+    <dependency>VariadicMacroDataReference
+;
+
+boostbook standalone
+  :
+     VariadicMacroData
+  :
+  <xsl:param>boost.root=../../../.. # OK but link to I:/boost_trunk/boost.png
+  <xsl:param>table.footnote.number.format=1 # Identifies the format used for footnote numbers in tables.
+  <xsl:param>footnote.number.format=1 # Identifies the format used for text footnote numbers.
+  <xsl:param>nav.layout=horizontal # to get a horizontal navigation bar (you probably DO want this).
+  <xsl:param>navig.graphics=1  # Use graphics not text for navigation.
+  <xsl:param>chunk.section.depth=10  # How far down we chunk nested sections, basically all of them.
+  <xsl:param>chunk.first.sections=1  # Don't put the first section on the same page as the TOC.
+  <xsl:param>toc.section.depth=10  # How far down sections get TOCs.
+  <xsl:param>toc.max.depth=4  # Max depth in each TOC.
+  <xsl:param>generate.section.toc.level=10  # How far down we go with TOCs.
+  <xsl:param>fop1.extensions=0 # DISable extensions for FOP version 0.90 and later .
+  <format>pdf:<xsl:param>fop.extensions=0 # DISable extensions for FOP version 0.20.5 and earlier.
+  <format>pdf:<xsl:param>xep.extensions=1 # Use XEP extension- PDF bookmarks, document information and better index processing.
+  <format>pdf:<xsl:param>body.start.indent=0pt #
+  <format>pdf:<xsl:param>paper.type=A4  # Paper type = A4
+  <xsl:param>admon.graphics=1
+  <format>pdf:<xsl:param>admon.graphics.extension=".svg"  #
+  <format>pdf:<xsl:param>use.role.for.mediaobject=1 # Use print role on next line.
+  <format>pdf:<xsl:param>preferred.mediaobject.role=print # pdf role is to be printed.
+  <format>pdf:<xsl:param>img.src.path=$(images_location)/ # Path of image (.svg) files. (Note trailing /) ? //
+  <format>pdf:<xsl:param>admon.graphics.path=$(nav-images)/ # path to admonition (warning, smiley...) image (.svg) files.
+  <format>pdf:<xsl:param>draft.mode="no"
+  ;