5.2.2 Generating Files

Any node in a document has the ability to generate a new file. During document traversal, each node is queried for a filename. If a non-None is returned, a new file is created for the content of that node using the given filename. The querying for the filename is simply done by accessing the filename property of the node. This property is added to the node’s namespace during the mixin process. The default behavior for this property is to only return filenames for sections with a level less than the split-level given in the configuration (see section 2.1.5). The filenames generated by this routine are very flexible. They can be statically given names, or names based on the ID and/or title, or simply generically numbered. For more information on configuring filenames see section 2.1.5.

While the filenaming mechanism is very powerful, you may want to give your files names based on some other information. This is possible through the filenameoverride attribute. If the filenameoverride is set, the name returned by that attribute is used as the filename. The string in filenameoverride is still processed in the same way as the filename specifier in the configuration so that you can use things like the ID or title of the section in the overridden filename.

The string used to specify filenames can also contain directory paths. This is not terribly useful at the moment since there is no way to get the relative URLs between two nodes for linking purposes.

If you want to use a filename override, but want to do it conditionally you can use a Python property to do this. Just calculate the filename however you wish, if you decide that you don’t want to use that filename then raise an AttributeError exception. An example of this is shown below.

class mymacro{Command):
    args = '[ filename:str ] self'
    @property
    def filenameoverride(self):
        # See if the attributes dictionary has a filename
        if self.attributes['filename'] is not None:
            return self.attributes['filename']
        raise AttributeError, 'filenameoverride'

Note: The filename in the filenameoverride attribute must contain any directory paths as well as a file extension.