Synopsis 0.5 - User Manual

New HTML Page

You can add a new type of HTML output to an existing HTML setup by creating or modifying a Page object. Like Linker Operations, the HTML Pages are specified with import specifications, allowing you to easily write your own. See the Page class for a list of the interface methods you can implement, and the base methods you can use. The mundane stuff like opening files and creating headers is all done for you, so you only have to take the AST and make the interesting bits!

A lot of the customizability of the HTML formatter is managed automatically, by having the Pages register themselves for various things:

Page.register(self)

Override this method to do the registration

config.set_contents_page(self, page)

Call this with the name of your main page (string ending in ".html") to register for the contents page, which is the top-left frame. If you are the first page to call this method, you will get to be the contents page - and keep it.

config.set_index_page(self, page)

Call this with the name of your main page (string ending in ".html") to register for the index page, which is the left frame. If you are the first page to call this method, you will get to be the index page - and keep it.

config.set_main_page(self, page)

Call this with the name of your main page (string ending in ".html") to register for the main page, which is the main frame, or start page if you're not using frames. If you are the first page to call this method, you will get to be the main page - and keep it. Note that if you get to be the main page, the FileLayout will return "index.html" for your main page (the one you gave to this method) for most methods of FileLayout.

PageManager.addRootPage(self, file, label, target, visibility)

Call this to add your page to the list of main pages at the top of every generated page. file is the filename to be linked to, label is the text to show, target is the frame to display in ("contents", "index", "main", or "_top" for a new window). visibility is 1 for just the main pages, 2 for all pages (including the smaller ones like ModuleListing).

Page.register_filenames(self, start)

Override this method to register filenames based on the target AST. "start" is the start node of the AST; typically the global namespace, but may be some other scope based on configuration and command line options.

PageManager.register_filename(self, filename, page, scope)

Call this for each file you can generate to register yourself for generating that file. This function is used by the FileSource and RawFilePages pages to compete for who gets to generate the output for that file. Use the filename_info() method to check if you got it or not. "scope" is any data you need to find out what makes that filename. It is called "scope" for the general case of it being an AST node (of which only Scopes usually have pages!). This facility is also used by the GUI to generate files on the fly when the user clicks a link! You should only call this method from the register_filenames() method of your Page class, not from the register() method!

The best way to figure this out is to study the existing Pages.