Furthermore, makepage.py generates labels and a contents line for all sections of a file at the top of each page to jump directly to a section without scrolling through the file. For example, this help file was generated with makepage.py from makepage.desc (perhaps you have to choose ``view source'' in your browser to see the description).
There is a default layout file (html_format.py) that can be ``overwritten'' partially or completely by a layout file supplied by you. That is, you shouldn't change html_format.py but instead provide your own additions.
|-C||show copyright information|
|-h, -?||show usage help|
|-f||file||use file to customize HTML layout|
|-T||title||use title as title (in the HTML head). By default, the title in the description file is used here.|
|-K||keywords||use keywords for keywords tag in HTML head.|
|-D||description||use description for description tag in HTML head.|
<<title Title of the HTML document>> <<text>> This is text before any section. A region introduced with <<text>> may also be put between sections. <<section The first section's title>> <<sectiontext>> This is a text which is at the same logical level as a subsection. You can abbreviate <<sectiontext>> as <<st>>. <<subsection Spam>> Here comes text contained in the subsection ``spam''. <<subsection Eggs>> And here comes the second subsection. <<section Common errors>> <<st>> It is a common error to begin the text area marks not in the leftmost column. There must be an empty line after each text area mark as seen in this example. <P> You can use usual HTML constructs in the different areas of the text. <P> There are also some more possibilities: <UL> <LI> You may use <<LINK url;text for the url>> to represent a hyperlink. If you write <<LINK url>>, the ``url'' part is also used for the text. <LI> <<B text>> is translated to <B>text</B>, the same holds for I, EM, STRONG etc. <LI> There are more special formats; you may also use <<PROG program name>>, <PROG>program name</PROG>, <<FILE filename>> or <FILE>filename</FILE>. </UL>
The file contains regular Python code and is read and interpreted by makepage during it's execution. If you know Python, simply look at html_format.py to see the possible formatting items. (A note: Though you may view the format file as a kind of configuration file, it is parsed directly by the Python interpreter. That means, if somebody would include harmful code, that would also be executed!)
If you don't know any Python, you should be able to figure out how the changes in your format file have to be written. Better, of course, is to go to the Python tutorial and start learning. :-) If you like the language (I do!), consider getting Learning Python.
As an example for a custom format file, there is a file debug.help in the distribution.
Of course, you can use text_areas.py in your own Python programs. :-)
<<LINK URL_to_file;<<FILE the_file>>>>won't work as expected. Workaround: use regular HTML code. For the above case you would write
<A HREF="url_to_file"><<FILE the_file>></A>