#!/usr/bin/env ruby # # ad_generator.rb: a simple script that takes two arguments: # 1) the path to an AsciiDoc file to be converted to DocBook # 2) the path where the converted DocBook should be written # # Most of the work is handled by AsciiDoctor, which this script # depends on. A few minor touchups to the DocBook XML source # to make our doc build toolchain happy also occur. =begin # Requirements: brew cask install java brew install ant brew install source-highlight gem install asciidoctor =end require 'optparse' def emit(*message) return unless $options[:verbose] and !message.empty? p message end # handle options $options = {} OptionParser.new do |opts| opts.banner = "Usage: ad_generator.rb [options]" opts.on("-a", "--asciidoc PATH", "path to AsciiDoc file to convert") do |a| $options[:ad] = a end opts.on("-p", "--p4build PATH", "path to doc build infrastructure") do |p| $options[:p4] = p end opts.on("-t", "--type TYPE", "specify asset type") do |t| $options[:type] = t end opts.on("-v", "--verbose", "enable verbose output") do |v| $options[:verbose] = v end opts.on("-x", "--xml PATH", "path to DocBook XML to write") do |x| $options[:xml] = x end opts.on("-h", "--help", "This help") do puts opts exit end end.parse! # startup checks abort("Bad AsciiDoc path #{$options[:ad]}") unless File.file?($options[:ad]) emit "Starting DocBook generation..." # read the specified AsciiDoc file to learn its title/subtitle title = "" subtitle = "" File.open($options[:ad]).each_line do |line| line.chomp! break if line.empty? title = (line[/^=\s*(.+)$/, 1] || "") if title.empty? subtitle = (line[/^:subtitle:\s*(.+)$/, 1] || "") if subtitle.empty? end abort "'#{$options[:ad]}' has no title!" if title.empty? abort "'#{$options[:ad]}' has no subtitle!" if subtitle.empty? # convert AsciiDoc to DocBook5 with AsciiDoctor # note: common_adoc here is an attribute for AsciiDoc includes arguments = [ "-b docbook5", "-a common_adoc=#{$options[:p4]}/perforce/common_adoc", "-a assettype=#{$options[:type]}", "-o #{$options[:xml]}", $options[:ad], "2>&1" ] arguments.unshift "-v" if $options[:verbose] arguments = arguments.join(" ") emit "asciidoctor #{arguments}" results = `asciidoctor #{arguments}` abort "AsciiDoctor invocation failed with:\n#{results}" unless results.empty? # post-conversion processing emit "post-processing..." db = File.read($options[:xml]) # apply tagged directory replacements, to handle commonly included files # note: common-adoc here is for the docinfo file, which is XML. db = db.gsub("@common-xml@", "#{$options[:p4]}/perforce/common_xml") db = db.gsub("@common-adoc@", "#{$options[:p4]}/perforce/common_adoc") db = db.gsub("@guides-dir@", "#{$options[:p4]}/..") # fixup line spacing for preformatted blocks db = db.gsub(/<screen([^>]*)>/, "<screen\\1>\n") db = db.gsub(/<programlisting([^>]*)>/, "<programlisting\\1>\n") # place the title/subtitle into the correct XML dom location. db = db.gsub("<title>#{title}</title>", "") #db = db.gsub("<subtitle>#{subtitle}</subtitle>", "") # if a dbhtml processing instruction exists, the document is likely trying to # assert which content appears in index.html. That means that the "book" content # needs to move out of the way, into copyright.html. dbhtml = (db =~ /<\?dbhtml\s+filename="[^"]+"\?>/) ? '<?dbhtml filename="copyright.html"?>' : "" db = db.gsub(/\<book (.+?)\>/, "<book \\1>#{dbhtml}<title>#{title}</title><subtitle>#{subtitle}</subtitle>") # output post-processed file emit "writing file..." File.write($options[:xml], db) emit "DocBook generation complete." # vim: set ts=2 sw=2 tw=80 ai si:
# | Change | User | Description | Committed | |
---|---|---|---|---|---|
#3 | 12836 | eedwards |
Arrange for the doc build infrastructure to pass the output type through to AsciiDoctor processing, so that output-format specific image handling can work. |
||
#2 | 12833 | eedwards |
Update the ruby post-processor for AsciiDoc guides so that any existing dbhtml processing instructions are identified, which causes a dbhtml PI to be injected immediately after the <book> tag. This allows AsciiDoc-based guides to specify which content should appear as index.html. The default index.html is generated when the dbhtml PI is not detected, and consists of the copyright statements. This includes the necessary update to the DVCS guide to make the Introduction chapter appear in index.html. |
||
#1 | 12830 | eedwards |
#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. |