hoe-manualgen: A hoe plugin for generating a manual.

Constants

DEFAULT_CONFIG: The default page configuration if none is specified.
PAGE_WITH_YAML_HEADER: Pattern to match a source page with a YAML header
TIDY_OPTIONS: Options to pass to libtidy

Attributes

basepath[R]: The relative path to the base directory, for prepending to page paths
catalog[R]: The PageCatalog to which the page belongs
config[R]: The page configuration, as read from its YAML header
filters[R]: The filters the page will use to render itself
layouts_dir[R]: The configured layouts directory as a Pathname object.
source[R]: The raw source of the page
sourcefile[R]: The Pathname object that specifys the page source file

Public Class Methods

anchor

new( catalog, sourcefile, layouts_dir, basepath='.' )

Create a new page-generator for the given sourcefile, which will use ones of the templates in layouts_dir as a wrapper. The basepath is the path to the base output directory, and the catalog is the PageCatalog to which the page belongs.

# File lib/hoe/manualgen.rb, line 113
def initialize( catalog, sourcefile, layouts_dir, basepath='.' )
        @catalog     = catalog
        @sourcefile  = Pathname.new( sourcefile )
        @layouts_dir = Pathname.new( layouts_dir )
        @basepath    = basepath

        rawsource = nil
        if Object.const_defined?( :Encoding )
                rawsource = @sourcefile.read( :encoding => 'UTF-8' )
        else
                rawsource = @sourcefile.read
        end
        @config, @source = self.read_page_config( rawsource )

        super()
end

Public Instance Methods

anchor

cleanup( source )

Clean up and return the given HTML source.

# File lib/hoe/manualgen.rb, line 216
def cleanup( source )
        require 'tidy'

        Tidy.open( TIDY_OPTIONS ) do |tidy|
                tidy.options.output_xhtml = true

                xml = tidy.clean( source )
                errors = tidy.errors
                error_message( errors.join ) unless errors.empty?
                warn tidy.diagnostics if $DEBUG
                return xml
        end
rescue LoadError => err
        $stderr.puts "No cleanup: " + err.message
        return source
end

anchor

generate( metadata )

Generate HTML output from the page and return it.

# File lib/hoe/manualgen.rb, line 158
def generate( metadata )
        # $stderr.puts "Config is: %p" % [@config],
        #    "Source is: %p" % [ @source[0,100] ]
        @filters = self.load_filters( @config['filters'] )

        content = self.generate_content( @source, metadata )

        layout = self.config['layout'].sub( /\.erb$/, '' )
        templatepath = @layouts_dir + "#{layout}.erb"
        template = nil
        if Object.const_defined?( :Encoding )
                template = ERB.new( templatepath.read(:encoding => 'UTF-8') )
        else
                template = ERB.new( templatepath.read )
        end

        page = self
        html = template.result( binding() )

        # Use Tidy to clean up the html if 'cleanup' is turned on, but remove the Tidy
        # meta-generator propaganda/advertising.
        html = self.cleanup( html ).sub( %r:<meta name="generator"[^>]*tidy[^>]*/>:im, '' ) if
                self.config['cleanup']

        return html
end

anchor

generate_content( input, metadata )

Run the various filters on the given input and return the transformed content.

# File lib/hoe/manualgen.rb, line 194
def generate_content( input, metadata )
        return @filters.inject( input ) do |source, filter|
                filter.process( source, self, metadata )
        end
end

anchor

load_filters( filterlist )

Get (singleton) instances of the filters named in filterlist and return them.

# File lib/hoe/manualgen.rb, line 235
def load_filters( filterlist )
        filterlist.flatten.collect do |key|
                raise ArgumentError, "filter '#{key}' didn't load correctly" unless
                        Hoe::ManualGen::PageFilter.derivatives.key?( key )
                Hoe::ManualGen::PageFilter.derivatives[ key ].instance
        end
end

anchor

make_index_html()

Build the index relative to the receiving page and return it as a String

# File lib/hoe/manualgen.rb, line 245
def make_index_html
        items = [ '<div class="index">' ]

        @catalog.traverse_page_hierarchy( self ) do |type, title, path|
                case type
                when :section
                        items << %Q{<div class="section">}
                        items << %Q{<h3><a href="#{self.basepath + path}/">#{title}</a></h3>}
                        items << '<ul class="index-section">'

                when :current_section
                        items << %Q{<div class="section current-section">}
                        items << %Q{<h3><a href="#{self.basepath + path}/">#{title}</a></h3>}
                        items << '<ul class="index-section current-index-section">'

                when :section_end, :current_section_end
                        items << '</ul></div>'

                when :entry
                        items << %Q{<li><a href="#{self.basepath + path}.html">#{title}</a></li>}

                when :current_entry
                        items << %Q{<li class="current-entry">#{title}</li>}

                else
                        raise "Unknown index entry type %p" % [ type ]
                end

        end

        items << '</div>'

        return items.join("\n")
end

anchor

read_page_config( source )

Trim the YAML header from the provided page source, convert it to a Ruby object, and return it.

# File lib/hoe/manualgen.rb, line 203
def read_page_config( source )
        unless source =~ PAGE_WITH_YAML_HEADER
                return DEFAULT_CONFIG.dup, source
        end

        pageconfig = YAML.load( $1 )
        source = $2

        return DEFAULT_CONFIG.merge( pageconfig ), source
end

anchor

title()

Return the page title as specified in the YAML options

# File lib/hoe/manualgen.rb, line 187
def title
        return self.config['title'] || self.sourcefile.basename
end