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

Constants

INDEX_PATH

Attributes

hierarchy[R]: The hierarchy of pages in the catalog, suitable for generating an on-page index
layoutsdir[R]: The Pathname location of look and feel templates.
pages[R]: An Array of all Page objects found
path_index[R]: An index of the pages in the catalog by Pathname
sourcedir[R]: The Pathname location of the .page files.
title_index[R]: An index of the pages in the catalog by title
uri_index[R]: An index of the pages in the catalog by the URI of their source relative to the source directory

Public Class Methods

anchor

new( sourcedir, layoutsdir )

Create a new PageCatalog that will load Page objects for .page files in the specified sourcedir.

# File lib/hoe/manualgen.rb, line 289
def initialize( sourcedir, layoutsdir )
        @sourcedir = sourcedir
        @layoutsdir = layoutsdir

        @pages       = []
        @path_index  = {}
        @uri_index   = {}
        @title_index = {}
        @hierarchy   = {}

        self.find_and_load_pages
end

Public Instance Methods

anchor

traverse_page_hierarchy( from=nil ) { |type, title, path| ... }

Traverse the catalog's hierarchy, yielding to the given builder block for each entry, as well as each time a sub-hash is entered or exited, setting the type appropriately. Valid values for type are:

:entry, :section, :section_end

If the optional from value is given, it should be the Page object which is considered “current”; if the from object is the same as the hierarchy entry being yielded, it will be yielded with the type set to one of:

:current_entry, :current_section, :current_section_end

each of which correspond to the like-named type from above.

# File lib/hoe/manualgen.rb, line 344
def traverse_page_hierarchy( from=nil, &builder ) # :yields: type, title, path
        raise LocalJumpError, "no block given" unless builder
        self.traverse_hierarchy( Pathname.new(''), self.hierarchy, from, &builder )
end

Protected Instance Methods

anchor

find_and_load_pages()

Find all .page files under the configured sourcedir and create a new Page object for each one.

# File lib/hoe/manualgen.rb, line 451
def find_and_load_pages
        Pathname.glob( @sourcedir + '**/*.page' ).each do |pagefile|
                path_to_base = @sourcedir.relative_path_from( pagefile.dirname )

                page = Page.new( self, pagefile, @layoutsdir, path_to_base )
                hierpath = pagefile.relative_path_from( @sourcedir )

                @pages << page
                @path_index[ pagefile ]     = page
                @title_index[ page.title ]  = page
                @uri_index[ hierpath.to_s ] = page

                # Place the page in the page hierarchy by using inject to find and/or create the
                # necessary subhashes. The last run of inject will return the leaf hash in which
                # the page will live
                section = hierpath.dirname.split[1..-1].inject( @hierarchy ) do |hier, component|
                        hier[ component ] ||= {}
                        hier[ component ]
                end

                section[ pagefile.basename('.page') ] = page
        end
end

anchor

handle_page_callback( path, page, from=nil ) { |:current_entry, title, path| ... }

Yield the specified page to the builder

# File lib/hoe/manualgen.rb, line 440
def handle_page_callback( path, page, from=nil )
        if from == page
                yield( :current_entry, page.title, path )
        else
                yield( :entry, page.title, path )
        end
end

anchor

handle_section_callback( path, section, from=nil, &builder )

Build up the data structures necessary for calling the builder callback for an index section and call it, then recurse into the section contents.

# File lib/hoe/manualgen.rb, line 407
def handle_section_callback( path, section, from=nil, &builder )
        from_current = false
        trace "Section handler: path=%p, section keys=%p, from=%s" %
                [ path, section.keys, from.sourcefile ]

        # Call the callback with :section -- determine the section title from
        # the 'index.page' file underneath it, or the directory name if no
        # index.page exists.
        if section.key?( INDEX_PATH )
                if section[INDEX_PATH].sourcefile.dirname == from.sourcefile.dirname
                        from_current = true
                        builder.call( :current_section, section[INDEX_PATH].title, path )
                else
                        builder.call( :section, section[INDEX_PATH].title, path )
                end
        else
                title = File.dirname( path ).gsub( /_/, ' ' )
                builder.call( :section, title, path )
        end

        # Recurse
        self.traverse_hierarchy( path, section, from, &builder )

        # Call the callback with :section_end
        if from_current
                builder.call( :current_section_end, '', path )
        else
                builder.call( :section_end, '', path )
        end
end

anchor

sort_hierarchy( hierarchy )

Return the specified hierarchy of pages as a sorted Array of tuples. Sort the hierarchy using the 'index' config value of either the page, or the directory's index page if it's a directory.

# File lib/hoe/manualgen.rb, line 371
def sort_hierarchy( hierarchy )
        hierarchy.sort_by do |subpath, page_or_section|

                # Directory
                if page_or_section.is_a?( Hash )

                        # Use the index of the index page if it exists
                        if page_or_section[INDEX_PATH]
                                idx = page_or_section[INDEX_PATH].config['index']
                                trace "Index page's index for directory '%s' is: %p" % [ subpath, idx ]
                                "%08d:%s" % [ idx || 0, subpath.to_s ]
                        else
                                trace "Using the path for the sort of directory %p" % [ subpath ]
                                subpath.to_s
                        end

                # Page
                else
                        if subpath == INDEX_PATH
                                trace "Sort index for index page %p is 0" % [ subpath ]
                                '0'
                        else
                                idx = page_or_section.config['index']
                                trace "Sort index for page %p is: %p" % [ subpath, idx ]
                                "%08d:%s" % [ idx || 0, subpath.to_s ]
                        end
                end

        end # sort_by
end

anchor

traverse_hierarchy( path, hash, from=nil, &builder )

Sort and traverse the specified hash recursively, yielding for each entry.

# File lib/hoe/manualgen.rb, line 355
def traverse_hierarchy( path, hash, from=nil, &builder )
        # Now generate the index in the sorted order
        sort_hierarchy( hash ).each do |subpath, page_or_section|
                if page_or_section.is_a?( Hash )
                        self.handle_section_callback( path + subpath, page_or_section, from, &builder )
                else
                        next if subpath == INDEX_PATH
                        self.handle_page_callback( path + subpath, page_or_section, from, &builder )
                end
        end
end