Support for asciidoctor tool to process asciidoc documents.

doc/jamfile.jam

@@ -3,7 +3,6 @@
 # (See accompanying file LICENSE_1_0.txt or http://www.boost.org/LICENSE_1_0.txt)
 
 import quickbook ;
-using boostbook ;
 
 project tools/build/doc
     ;
@@ -12,9 +11,9 @@ boostbook userman : src/standalone.xml
     :   <xsl:param>toc.section.depth=1
         <xsl:param>doc.standalone=true 
         <xsl:param>nav.layout=none
-        <xsl:param>boost.root=..
-        <xsl:param>boost.graphics.root=../images/
-        <xsl:param>html.stylesheet=../boostbook.css
+        <xsl:param>boost.root=.
+        <xsl:param>boost.graphics.root=images/
+        <xsl:param>html.stylesheet=boostbook.css
         <xsl:param>chunk.first.sections=0
         <xsl:param>admon.graphics=0
 
@@ -25,6 +24,14 @@ boostbook userman : src/standalone.xml
 
         <implicit-dependency>examples_docs
         <dependency>examples_docs
+
+        <implicit-dependency>tools
+        <dependency>tools
+
+        <dependency>images
+        <dependency>callouts
+        <dependency>css
+        <dependency>logo
     ;
 
 xml jam_docs : bjam.qbk ;
@@ -32,6 +39,18 @@ xml jam_docs : bjam.qbk ;
 local examples = [ glob-tree-ex [ glob ../example/* ] : *.* : bin .DS_Store ] ;
 xml examples_docs : examples.qbk : <dependency>$(examples) ;
 
+docbook tools : src/tools.adoc ;
+
+# HTML dependencies for standalone docs.
+install images : [ glob images/*.png ] : <location>html/images ;
+explicit images ;
+install callouts : [ glob images/callouts/*.png ] : <location>html/images/callouts ;
+explicit callouts ;
+install css : [ glob *.css ] : <location>html ;
+explicit css ;
+install logo : [ glob *.png ] : <location>html ;
+explicit logo ;
+
 ###############################################################################
 
 alias boostdoc : src/userman.xml

doc/src/standalone.xml

@@ -18,6 +18,12 @@
   <xi:include href="extending.xml"/>
   <xi:include href="faq.xml"/>
 
+  <!-- Tools -->
+  <appendix id="extra-tools">
+    <title>Extra Tools</title>
+    <xi:include href="tools.docbook" parse="xml"
+      xpointer="xpointer(id('_documentation_tools')|id('_documentation_tools')/following-sibling::*)"/>
+  </appendix>
   <!-- Appendicies -->
   <appendix id="examples">
     <title>Examples</title>

doc/src/tools.adoc

@@ -0,0 +1,7 @@
+= Extra Tools
+
+== Documentation Tools
+
+:leveloffset: +2
+include::../../src/tools/asciidoctor.jam[tag=doc]
+:leveloffset: -2

example/asciidoctor/example.adoc

@@ -0,0 +1,3 @@
+= The Dangerous and Thrilling Documentation Chronicles
+
+This journey begins on a bleary Monday morning.

example/asciidoctor/example_manpage.adoc

@@ -0,0 +1,38 @@
+= b2(1)
+Rene Rivera
+v0.0.0
+:doctype: manpage
+:manmanual: B2
+:mansource: B2
+:man-linkstyle: pass:[blue R < >]
+
+== NAME
+
+b2 - Boost Build
+
+== SYNOPSIS
+
+*b2* ['OPTION']... 'TARGET'...
+
+== OPTIONS
+
+*-n*::
+  Print out what would get built.
+
+== EXIT STATUS
+
+*0*::
+  Success.
+
+*1*::
+  Failure.
+
+== RESOURCES
+
+*Project web site:* http://boost.org
+
+== COPYING
+
+Copyright \(C) 2017 {author}. +
+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)

example/asciidoctor/jamroot.jam

@@ -0,0 +1,11 @@
+#|
+Copyright 2017 Rene Rivera
+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)
+|#
+
+html example_html : example.adoc ;
+manpage example_1 : example_manpage.adoc ;
+pdf example_pdf : example.adoc ;
+docbook example_docbook : example.adoc ;

src/tools/asciidoctor.jam

@@ -0,0 +1,209 @@
+#|
+Copyright 2017 Rene Rivera
+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)
+|#
+
+#| tag::doc[]
+= Asciidoctor
+
+The asciidoctor tool converts the ascidoc documentation format to various
+backend formats for either viewing or further processing by documentation
+tools. This tool supports the baseline asciidoctor distribution (i.e. the
+Ruby based tool).
+|# # end::doc[]
+
+import common ;
+import feature ;
+import generators ;
+import toolset ;
+import "class" : new ;
+
+feature.feature asciidoctor : : implicit propagated symmetric ;
+
+#| tag::doc[]
+
+== Feature: `asciidoctor-attribute`
+
+Defines arbitrary asciidoctor attributes. The value of the feature should be
+specified with the CLI syntax for attributes.
+For example to use as a target requirement:
+
+```
+html example : example.adoc :
+    <asciidoctor-attribute>idprefix=ex ;
+```
+
+This is a `free` feature and is not `propagated`. I.e. it applies only to the
+target it's specified on.
+
+|# # end::doc[]
+
+feature.subfeature asciidoctor : attribute : : free ;
+
+#| tag::doc[]
+
+== Feature: `asciidoctor-doctype`
+
+Specifies the `doctype` to use for generating the output format. Allowed
+`doctype` values are: `article`, `book`, `manpage`, and `inline`.
+
+|# # end::doc[]
+
+feature.subfeature asciidoctor : doctype
+    : article book manpage inline
+    : optional propagated ;
+
+#| tag::doc[]
+
+== Feature: `asciidoctor-backend`
+
+Specifies the `backend` to use to produce output from the source asciidoc.
+This feature is automatically applied to fit the build target type. For
+example, when specifying an `html` target for an `asciidoc` source:
+
+```
+html example : example.adoc ;
+```
+
+The target will by default acquire the `<asciidoctor-backend>html5`
+requirement. The default for each target type are:
+
+* `html`: `<asciidoctor-backend>html5`
+* `docbook`: `<asciidoctor-backend>docbook45`
+* `man`: `<asciidoctor-backend>manpage`
+* `pdf`: `<asciidoctor-backend>pdf`
+
+To override the defaults you specify it as a requirement on the target:
+
+```
+docbook example : example.adoc :
+    <asciidoctor-backend>docbook5 ;
+```
+
+Allowed `backend` values are: `html5`, `docbook45`, `docbook5`, `pdf`.
+
+|# # end::doc[]
+
+feature.subfeature asciidoctor : backend
+    : html5 docbook5 docbook45 manpage pdf
+    : propagated symmetric composite ;
+
+#| tag::doc[]
+
+== Initialization
+
+To use the `asciidoctor` tool you need to declare it in a configuration file
+with the `using` rule. The initialiation takes the following arguments:
+
+* `command`: The command, with any extra arguments, to execute.
+
+For example you could insert the following in your `user-config.jam`:
+
+```
+using asciidoctor : "/usr/local/bin/asciidoctor" ;
+```
+
+If no `command` is given it defaults to just `asciidoctor` with assumption
+that the `asciidoctor` is available in the search `PATH`.
+
+|# # end::doc[]
+
+rule init ( command * )
+{
+    if ! $(.initialized)
+    {
+        # Setup only if we were called via "using .. ;"
+        .initialized = true ;
+
+        # Register generators.
+        for local target-type in HTML MANPAGE PDF DOCBOOK
+        {
+            generators.register
+                [ new asciidoctor-generator asciidoctor.convert
+                    : ASCIIDOC : $(target-type) ] ;
+        }
+        
+        # Seriously bad kludge to prevent docbook generators from being
+        # considered when we are generating html directly.
+        # TODO: Design and implement a mechanism to resolve generator conflicts.
+        generators.override asciidoctor.convert : boostbook.docbook-to-onehtml ;
+    }
+
+    # The command.. Default is bare asciidoctor.
+    command ?= asciidoctor ;
+    # We attempt to resolve each component of the command to account for
+    # script interpreter wrappers.
+    ASCIIDOCTOR = ;
+    for local c in $(command)
+    {
+        local t = [ common.find-tool $(c) ] ;
+        t ?= $(c) ;
+        ASCIIDOCTOR += $(t) ;
+    }
+}
+
+class asciidoctor-generator : generator
+{
+    import property-set ;
+    
+    rule run ( project name ? : property-set : sources + )
+    {
+        # ECHO *** asciidoctor-generator.run $(project) $(name) :: [ $(property-set).raw ] :: $(sources) ;
+        
+        # We set a default backend based on the target type.
+        local backend = [ $(property-set).get <asciidoctor-backend> ] ;
+        
+        # For now, we only accept a single adoc source.
+        if ( ! $(sources[2]) ) && ( [ $(sources[1]).type ] = ASCIIDOC )
+        {
+            # If no output name is specified, guess it from sources.
+            name ?= [ generator.determine-output-name $(sources) ] ;
+            
+            # Depending on the kind of target we set up the backend, and
+            # and any other options.
+            if ! $(backend)
+            {
+                switch [ $(property-set).get <main-target-type> ]
+                {
+                    case HTML : backend = html5 ;
+                    case DOCBOOK : backend = docbook45 ;
+                    case MANPAGE : backend = manpage ;
+                    case PDF : backend = pdf ;
+                }
+                if $(backend)
+                {
+                    property-set = [ $(property-set).add-raw  ] ;
+                }
+            }
+        }
+        
+        # We build a reduced property set so that we are not toolset dependent.
+        local raw-set = <asciidoctor-backend>$(backend) ;
+        for local p in [ $(property-set).raw ]
+        {
+            if $(p:G) in <asciidoctor-attribute> <asciidoctor-doctype>
+                <include> <flags>
+            {
+                raw-set += $(p) ;
+            }
+        }
+        property-set = [ property-set.create $(raw-set) ] ;
+        return [ generator.run $(project) $(name) : $(property-set) : $(sources) ] ;
+    }
+}
+
+_ = " " ;
+toolset.flags asciidoctor ATTRIBUTE : <asciidoctor-attribute> ;
+toolset.flags asciidoctor DOCTYPE : <asciidoctor-doctype> ;
+toolset.flags asciidoctor INCLUDES : <include> ;
+toolset.flags asciidoctor BACKEND : <asciidoctor-backend> ;
+toolset.flags asciidoctor FLAGS : <flags> ;
+
+feature.compose <asciidoctor-backend>pdf : <flags>"-r asciidoctor-pdf" ;
+
+actions convert
+{
+    "$(ASCIIDOCTOR)" -o$(_)"$(<:D=)" -D$(_)"$(<:D)" -b$(_)"$(BACKEND)" -a$(_)"$(ATTRIBUTE)" -d$(_)"$(DOCTYPE)" -I$(_)"$(INCLUDES)" $(FLAGS) "$(>)"
+}

src/tools/types/adoc.jam

@@ -0,0 +1,26 @@
+#|
+Copyright 2017 Rene Rivera
+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 scanner ;
+import type ;
+
+type ASCIIDOC : adoc asciidoc ;
+
+class asciidoc-scanner : common-scanner
+{
+    rule pattern ( )
+    {
+        return
+            "include::([^[]+)"
+            "image::([^[]+)"
+            "image:([^[]+)"
+        ;
+    }
+}
+
+scanner.register asciidoc-scanner : include ;
+type.set-scanner ASCIIDOC : asciidoc-scanner ;

src/tools/types/man.jam

@@ -0,0 +1,8 @@
+#|
+Copyright 2017 Rene Rivera
+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 MANPAGE : man 0 1 1M 2 3 4 5 6 7 8 9 n p x ;

test/unused.py

@@ -13,7 +13,7 @@ t = BoostBuild.Tester(["-d+2"], use_test_config=False)
 
 t.write("a.cpp", "int main() {}\n")
 t.write("b.cpp", "\n")
-t.write("b.x", "")
+t.write("b.xyz", "")
 t.write("jamroot.jam", """\
 import "class" : new ;
 import modules ;
@@ -22,7 +22,7 @@ import targets ;
 import type ;
 import virtual-target ;
 
-type.register X : x ;
+type.register X : xyz ;
 
 class test-target-class : basic-target
 {
@@ -31,7 +31,7 @@ class test-target-class : basic-target
         local result = [ property-set.empty ] ;
         if ! [ modules.peek : GENERATE_NOTHING ]
         {
-            result += [ virtual-target.from-file b.x : . : $(self.project) ] ;
+            result += [ virtual-target.from-file b.xyz : . : $(self.project) ] ;
             if ! [ modules.peek : GENERATE_ONLY_UNUSABLE ]
             {
                 result += [ virtual-target.from-file b.cpp : . : $(self.project)