ceph/src/boost/tools/build/src/tools/asciidoctor.jam

   1 #|
   2 Copyright 2017 Rene Rivera
   3 Distributed under the Boost Software License, Version 1.0. (See
   4 accompanying file LICENSE_1_0.txt or copy at
   5 http://www.boost.org/LICENSE_1_0.txt)
   6 |#
   7
   8 #| tag::doc[]
   9 = Asciidoctor
  10
  11 The asciidoctor tool converts the ascidoc documentation format to various
  12 backend formats for either viewing or further processing by documentation
  13 tools. This tool supports the baseline asciidoctor distribution (i.e. the
  14 Ruby based tool).
  15 |# # end::doc[]
  16
  17 import common ;
  18 import feature ;
  19 import generators ;
  20 import toolset ;
  21 import "class" : new ;
  22
  23 feature.feature asciidoctor : : implicit propagated symmetric ;
  24
  25 #| tag::doc[]
  26
  27 == Feature: `asciidoctor-attribute`
  28
  29 Defines arbitrary asciidoctor attributes. The value of the feature should be
  30 specified with the CLI syntax for attributes.
  31 For example to use as a target requirement:
  32
  33 ```
  34 html example : example.adoc :
  35     <asciidoctor-attribute>idprefix=ex ;
  36 ```
  37
  38 This is a `free` feature and is not `propagated`. I.e. it applies only to the
  39 target it's specified on.
  40
  41 |# # end::doc[]
  42
  43 feature.subfeature asciidoctor : attribute : : free ;
  44
  45 #| tag::doc[]
  46
  47 == Feature: `asciidoctor-doctype`
  48
  49 Specifies the `doctype` to use for generating the output format. Allowed
  50 `doctype` values are: `article`, `book`, `manpage`, and `inline`.
  51
  52 |# # end::doc[]
  53
  54 feature.subfeature asciidoctor : doctype
  55     : article book manpage inline
  56     : optional propagated ;
  57
  58 #| tag::doc[]
  59
  60 == Feature: `asciidoctor-backend`
  61
  62 Specifies the `backend` to use to produce output from the source asciidoc.
  63 This feature is automatically applied to fit the build target type. For
  64 example, when specifying an `html` target for an `asciidoc` source:
  65
  66 ```
  67 html example : example.adoc ;
  68 ```
  69
  70 The target will by default acquire the `<asciidoctor-backend>html5`
  71 requirement. The default for each target type are:
  72
  73 * `html`: `<asciidoctor-backend>html5`
  74 * `docbook`: `<asciidoctor-backend>docbook45`
  75 * `man`: `<asciidoctor-backend>manpage`
  76 * `pdf`: `<asciidoctor-backend>pdf`
  77
  78 To override the defaults you specify it as a requirement on the target:
  79
  80 ```
  81 docbook example : example.adoc :
  82     <asciidoctor-backend>docbook5 ;
  83 ```
  84
  85 Allowed `backend` values are: `html5`, `docbook45`, `docbook5`, `pdf`.
  86
  87 |# # end::doc[]
  88
  89 feature.subfeature asciidoctor : backend
  90     : html5 docbook5 docbook45 manpage pdf
  91     : propagated symmetric composite ;
  92
  93 #| tag::doc[]
  94
  95 == Initialization
  96
  97 To use the `asciidoctor` tool you need to declare it in a configuration file
  98 with the `using` rule. The initialiation takes the following arguments:
  99
 100 * `command`: The command, with any extra arguments, to execute.
 101
 102 For example you could insert the following in your `user-config.jam`:
 103
 104 ```
 105 using asciidoctor : "/usr/local/bin/asciidoctor" ;
 106 ```
 107
 108 If no `command` is given it defaults to just `asciidoctor` with assumption
 109 that the `asciidoctor` is available in the search `PATH`.
 110
 111 |# # end::doc[]
 112
 113 rule init ( command * )
 114 {
 115     if ! $(.initialized)
 116     {
 117         # Setup only if we were called via "using .. ;"
 118         .initialized = true ;
 119
 120         # Register generators.
 121         for local target-type in HTML MANPAGE PDF DOCBOOK
 122         {
 123             generators.register
 124                 [ new asciidoctor-generator asciidoctor.convert
 125                     : ASCIIDOC : $(target-type) ] ;
 126         }
 127
 128         # Seriously bad kludge to prevent docbook generators from being
 129         # considered when we are generating html directly.
 130         # TODO: Design and implement a mechanism to resolve generator conflicts.
 131         generators.override asciidoctor.convert : boostbook.docbook-to-onehtml ;
 132     }
 133
 134     # The command.. Default is bare asciidoctor.
 135     command ?= asciidoctor ;
 136     # We attempt to resolve each component of the command to account for
 137     # script interpreter wrappers.
 138     ASCIIDOCTOR = ;
 139     for local c in $(command)
 140     {
 141         local t = [ common.find-tool $(c) ] ;
 142         t ?= $(c) ;
 143         ASCIIDOCTOR += $(t) ;
 144     }
 145 }
 146
 147 class asciidoctor-generator : generator
 148 {
 149     import property-set ;
 150
 151     rule run ( project name ? : property-set : sources + )
 152     {
 153         # ECHO *** asciidoctor-generator.run $(project) $(name) :: [ $(property-set).raw ] :: $(sources) ;
 154
 155         # We set a default backend based on the target type.
 156         local backend = [ $(property-set).get <asciidoctor-backend> ] ;
 157
 158         # For now, we only accept a single adoc source.
 159         if ( ! $(sources[2]) ) && ( [ $(sources[1]).type ] = ASCIIDOC )
 160         {
 161             # If no output name is specified, guess it from sources.
 162             # NOTE: For some reason the "?=" conditional assign op doesn't
 163             # work here. It assigns the value regardless, so work around it.
 164             # TODO: Look into why that happens.
 165             if ! $(name)
 166             {
 167                 name = [ generator.determine-output-name $(sources) ] ;
 168             }
 169
 170             # Depending on the kind of target we set up the backend, and
 171             # and any other options.
 172             if ! $(backend)
 173             {
 174                 switch [ $(property-set).get <main-target-type> ]
 175                 {
 176                     case HTML : backend = html5 ;
 177                     case DOCBOOK : backend = docbook45 ;
 178                     case MANPAGE : backend = manpage ;
 179                     case PDF : backend = pdf ;
 180                 }
 181             }
 182         }
 183
 184         # We build a reduced property set so that we are not toolset dependent.
 185         local raw-set = <asciidoctor-backend>$(backend) ;
 186         for local p in [ $(property-set).raw ]
 187         {
 188             if $(p:G) in <asciidoctor-attribute> <asciidoctor-doctype>
 189                 <include> <flags>
 190             {
 191                 raw-set += $(p) ;
 192             }
 193         }
 194         raw-set = [ feature.expand-composites $(raw-set) ] ;
 195         raw-set += [ $(property-set).incidental ] ;
 196         property-set = [ property-set.create $(raw-set) ] ;
 197         return [ generator.run $(project) $(name) : $(property-set) : $(sources) ] ;
 198     }
 199 }
 200
 201 _ = " " ;
 202 toolset.flags asciidoctor ATTRIBUTE : <asciidoctor-attribute> ;
 203 toolset.flags asciidoctor DOCTYPE : <asciidoctor-doctype> ;
 204 toolset.flags asciidoctor INCLUDES : <include> ;
 205 toolset.flags asciidoctor BACKEND : <asciidoctor-backend> ;
 206 toolset.flags asciidoctor FLAGS : <flags> ;
 207
 208 feature.compose <asciidoctor-backend>pdf : <flags>"-r asciidoctor-pdf" ;
 209
 210 actions convert
 211 {
 212     "$(ASCIIDOCTOR)" -o$(_)"$(<:D=)" -D$(_)"$(<:D)" -b$(_)"$(BACKEND)" -a$(_)"$(ATTRIBUTE)" -d$(_)"$(DOCTYPE)" -I$(_)"$(INCLUDES)" $(FLAGS) "$(>)"
 213 }