Change 12830
#review-1031983
Incorporate AsciiDoc into the doc build infrastructure. This
builds on Matt's initial generate.rb, but uses its own version
that is more generic and adds some rudimentary validation.
Requirements to build AsciiDoc guides:
- in the build.properties (or build.xml) for a guide, the property
"input-xml" must point to the master AsciiDoc guide.
- additionally, a property "input-type" must be set to "adoc".
I.e.: "input-type=adoc".
- Ruby must be installed and available in your path.
- AsciiDoctor must be installed and available in your path.
- The master AsciiDoc file must have a metadata line providing
the guide's subtitle (which, by convention, is the release
string, e.g. "2015.1"), like so:
:subtitle: 2015.1
The standard invocations:
- "ant pdf" to create a PDF,
- "ant publicsite" to create HTML destined for perforce.com,
- "ant htmlhelp" to provide the files for CHM production,
- "ant product" (if implemented for the guide) to produce
HTML destined for product inclusion
should all work just as if the guide originated in DocBook XML.
As the DVCS guide is the only one authored in AsciiDoc at this
point, the necessary modifications to its configuration/source
are included in this review, as well as a first cut of common
AsciiDoc files for license statement inclusion.
Note: I had to rename aa_license to aa_license.adoc because
AsciiDoctor's include mechanism requires a known filename
extension for nested includes. In the future, all AsciiDoc files
should have the ".adoc" extension or frustration will prevail.
Incorporate AsciiDoc into the doc build infrastructure. This
builds on Matt's initial generate.rb, but uses its own version
that is more generic and adds some rudimentary validation.
Requirements to build AsciiDoc guides:
- in the build.properties (or build.xml) for a guide, the property
"input-xml" must point to the master AsciiDoc guide.
- additionally, a property "input-type" must be set to "adoc".
I.e.: "input-type=adoc".
- Ruby must be installed and available in your path.
- AsciiDoctor must be installed and available in your path.
- The master AsciiDoc file must have a metadata line providing
the guide's subtitle (which, by convention, is the release
string, e.g. "2015.1"), like so:
:subtitle: 2015.1
The standard invocations:
- "ant pdf" to create a PDF,
- "ant publicsite" to create HTML destined for perforce.com,
- "ant htmlhelp" to provide the files for CHM production,
- "ant product" (if implemented for the guide) to produce
HTML destined for product inclusion
should all work just as if the guide originated in DocBook XML.
As the DVCS guide is the only one authored in AsciiDoc at this
point, the necessary modifications to its configuration/source
are included in this review, as well as a first cut of common
AsciiDoc files for license statement inclusion.
Note: I had to rename aa_license to aa_license.adoc because
AsciiDoctor's include mechanism requires a known filename
extension for nested includes. In the future, all AsciiDoc files
should have the ".adoc" extension or frustration will prevail.