PPTools/Ppgen/Tutorial/Ini file

Purpose

Starting with version 3.54l ppgen supports an additional input file, by default named ppgen.ini and located in either the same directory as the ppgen.py program or in the directory holding the project source file (xxx-src.txt). This file is not shipped by ppgen, so if you want to use it you'll need to create it yourself. A sample file (ppgen-sample.ini) is provided to show you the basic format. You can also tell ppgen to use a different file, by providing a suffix for the first part of the name. For example, you might specify your ppgen command as

 ppgen.py -i project1-src.txt -ini proj1

which would cause ppgen to look for ppgen-proj1.ini instead of ppgen.ini.

Alternatively, if you have a .ini file that you usually use, but for some reason you want to run ppgen without it, you can specify that by specifying

 ppgen.py -i project-src.txt -ini none

ppgen uses at most one .ini file in each run.

You might want to use ppgen.ini if you have a special set of .de overrides for the h1 through h6 HTML elements that you want to apply to all your projects, or if you have a common set of .nr directives that you issue for your projects. By placing the overrides in a ppgen.ini file you can ensure they are always used, without needing to physically place them in each project source file.

File Structure

The full format of the file is explained in the Python documentation for configparser. But in simple terms, the file has two sections, each with a header. The supported headers are [CSS] and [Nregs]. Within each section you may provide statements in the form

 keyword = value
or
 keyword: value

or

 # comment

or

 ; comment

(Note: Comments can not follow other data on a line.)

A typical file might look like:

 ; Comment to explain the purpose of the file
 [CSS]
 ; comment to explain the CSS that follows
 h1: data to replace ppgen's normal CSS for the h1 element
 ...
 [Nregs]
 ; comment to explain the statements that follow. In this example,
 ; the following statement is the equivalent of entering ".nr nfl 1"
 ; in the ppgen source file
 nfl = 1

Sections may be empty, or omitted. They may appear in any order.

Defaults

ppgen does not supply a default ppgen.ini file, so if you want one you'll need to create it yourself. You can examine ppgen-sample.ini to see the structure of a working file.

Though it does not supply a default file, ppgen operates by default as though it were using a ppgen.ini file with the following content:

 [CSS]
 
 ; At this time ppgen only supports the CSS for the h1-h6 elements in this
 ; part of the ini file. The entries below are what ppgen uses by default.
  
 
 h1: text-align: center; font-weight: normal; font-size: 1.4em;
 h2: text-align: center; font-weight: normal; font-size: 1.2em;
 h3: text-align: center; font-weight: normal; font-size: 1.2em;
 h4: text-align: center; font-weight: normal; font-size: 1.0em;
 h5: text-align: center; font-weight: normal; font-size: 1.0em;
 h6: text-align: center; font-weight: normal; font-size: 1.0em;

Example

Situation 1

Suppose you wanted to make your h2 headers bold. As you can see above, ppgen gives them a normal weight by default, which is different than a browser would normally do for an h2 heading. You have several choices:

You could simply specify each of your .h2 headers as follows in your source file:

 .h2
 <b>Chapter Header</b>

That's perhaps more work than you want to do, so you might automate it with a macro that generated that for you. But even then, using <b> will give you headers like =Chapter Header= in the text file, which you might not want. You can get around that by using <B>Chapter Header</B> but that still may be more work than you want to do.

Alternatively, you could specify it by using the .de directive:

 .de h2 {font-weight: bold}

That will work, but you need to remember to put it in each of your source files. Additionally, it has a problem that is not obvious with this example, so let's look at another example.

Situation 2

Suppose you didn't like centered headers, but wanted them left-aligned. As above, that seems fairly simple to do:

 .de h2 {text-align: left}

That will work just fine for your HTML. However, in the text file your .h2 headers will still be centered, because .de affects only the HTML output. This means that .de does not provide a complete override mechanism since it will leave your text and HTML files looking quite different.

You could get around that by specifying each header as:

.h2
 <al=l>Chapter Heading

Again, you would probably want to automate that with a macro to save work, but it would left-align all the h2 headers, and you would not need the .de statement.

Situation 3

Suppose you wanted to go further and override ppgen's CSS definitions for all the headers (h1 through h6( so your HTML would be displayed using the default parameters supplied by the user's browser. That's fairly straightforward, once you figure out what they all are. (Hint: w3schools has a page that will show you how most browsers will display the h1 through h6 headers.) You could simply copy that data, and use .de:

 .de h1 {font-weight: bold; font-size: 2em;}
 .de h2 {font-weight: bold; font-size: 1.5em;}
 etc.

Again, you would need to put those .de statements into each of your project source files. If you wanted both bold text for the HTML headings and left-aligned headings for text and HTML you would also need to use <al=l> on each of your headings.

The ppgen.ini file provides a simpler solution.

The Simpler Solution (FSVO simple)

Using a ppgen.ini file you could solve all of those problems:

 [CSS]
 h1: font-weight: bold; font-size: 2em;
 h2: font-weight: bold; font-size: 1.5em;
 etc.

This will accomplish the following:

1. ppgen will use those statements for each of your projects. You won't need to remember to put them in each source file.
2. As with .de, it affects the font-weight of the HTML without putting = signs around the headers in the text output, and without having to put <b> or <B> around the headers in the source file.
3. Perhaps most importantly: ppgen will automatically honor the text-alignment specified in your h1, h2, etc. definitions for both the HTML and text output. Since we didn't specify a text-alignment, that's the same as saying "text-align: left" and so the headers will be left-aligned, by default, in both the HTML and text output. However, if you need some header to behave differently, you can still use <al=c> or <al=r> on the header to provide that function.

Cautionary Note

If you copy that h1-h6 data from the w3schools page to make your headers look like most browsers would display them, you may want to omit the margin specifications (especially margin-top and margin-bottom) as the spacing around headings is controlled in other ways by ppgen. I don't know for sure that specifying the top- and bottom-margins would cause an issue, but it might. So I would omit them.