makepage.py

[Name] [Synopsis] [Description] [Options] [Files] [See also] [Bugs] [Author] [History]

Name

makepage.py - create HTML pages from description files

Synopsis

python makepage.py [options] inputfile outputfile

Description

makepage.py takes a specially formatted input file and a HTML format file and generates a HTML file from them. This approach makes little sense if you need the layout for a single HTML file, but is very helpful if you need many pages with the same layout.

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.

Options

Supported options are:
-Cshow copyright information
-h, -?show usage help
-ffileuse file to customize HTML layout
-Ttitleuse title as title (in the HTML head). By default, the title in the description file is used here.
-Kkeywordsuse keywords for keywords tag in HTML head.
-Ddescription  use description for description tag in HTML head.

Files

Document description file

This is the inputfile for the program. (The outputfile gets the generated HTML content.) You may use a hyphen for input and output file to use standard input and standard output, respectively. For an example of a description file you may look at makepage.desc (select ``view source'' from your browser's menu). The usual format of the file is described below.
<<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>

html_format.py

This file contains information on how the generated HTML file should look like. Provided is a default file html_format.py. You can't avoid that it is loaded but you can change everything in it by loading another format file after it with the -f file option.

Your own format file

As said above, you can use any name for a custom format file and pass it to makepage.py via the -f option.

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.

text_areas.py

This file contains the definitions of the text compartments that can be used in the description file. You only have to know that it's a part of the package, unless you want to modify the program.

Of course, you can use text_areas.py in your own Python programs. :-)

See also

text_areas.py

Bugs

Special labes can't be nested. For example,
<<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>

Author

Stefan Schwarzer <s.schwarzer@ndh.net>

History


Top Top of this page