secnum - Add section numbering to headings in HTML files

NAME

secnum - Add section numbering to headings in HTML files

SYNOPSIS

  secnum [options] <infile> [outfile]

DESCRIPTION

secnum adds section numbering to HTML files. Section numbers are added to existing heading tags. The numbers are calculated automatically based on the type of heading tag and the number of each type of heading already seen. No additional options or tags are required for secnum to work. Section numbers will be added to the headings of a specified HTML file, and the whole file (with numbered sections) written to a new file. If given the -toc option, secnum will create a table of contents, rather than a numbered HTML file.

secnum is a preprocessor. It must be run on the HTML file prior to making the HTML available for display.

By default, numbering starts with the <H2> tag and goes through <H6> No numbering is added for the <H6> tag. The -section option allows section numbering to start with heading tag <H1>, <H4>, or whatever heading tag the user wants.

If any heading levels are skipped, then secnum assumes that the skipped heading levels should be implied. For example, take the case of the next heading after an <H2> heading being an <H4> heading. The missing <H3> heading may be handled explicitly or implicitly. The explicit handling would skip the numbering, giving a section number like "1.0.1". Implicit handling for the missing heading level would result in a section number like "1.1.1". secnum provides implicit handling for missing heading levels. If the missing heading is later inserted, then all will be well, since secnum functions as a pre-processor and will account for the new header.

Given this set of heading tags:

    <h1>A Document</h1>
    <h2>A Section</h2>
    <h3>A Subsection</h3>
    <h4>A Subsubsection</h4>
    <h4>A Another Subsubsection</h4>
    <h3>Another Subsection</h3>
    <h4>And Still Another Subsubsection</h4>
    <h6>An Ill-advised, Skipped Sub6section</h6>
    <h2>Another Section</h2>

secnum will rewrite the heading text to be:

    <h1>A Document</h1>
    <h2>1 A Section</h2>
    <h3>1.1 A Subsection</h3>
    <h4>1.1.1 A Subsubsection</h4>
    <h4>1.1.2 Another Subsubsection</h4>
    <h3>1.2 Another Subsection</h3>
    <h4>1.2.1 And Still Another Subsubsection</h4>
    <h6>1.2.1.1.1 An Ill-advised, Skipped Subsection</h6>
    <h2>2 Another Section</h2>

The input file (infile) must be specified. The output file (outfile) is optional. If the outfile is not given, then the output filename is constructed from the input filename. If infile ends in ".html", ".HTML", ".htm", or ".HTM", then the secnum suffix is inserted before that dotted file extension. Otherwise, the secnum suffix is appended to the filename. The secnum suffix is -numbered. The command "secnum foo.html" will result in the foo-numbered.html as the output file.

The input HTML file may be modified in place if the -overwrite option is given and an output file is not specified. The command "secnum -overwrite foo.html" will result in the section-numbered HTML being written to foo.html. This is irreversible and should be used with caution. Once a file is overwritten, the section numbers are embedded in the original file.

secnum can be run in a simple daemon mode. This is useful while writing new HTML content. secnum will run continuously and periodically check if the specified file has been updated. If so, secnum will perform its regular header numbering and write the modified HTML to the specified output file. This may only be used when the input file and output files have different names.

Why A Preprocessor?

HTML does not provide a nice, easy method for providing automatically renumbered section headings. A variety of methods may be used to automatically add section numbers, each method with its own advantages and disadvantages.

- CSS can automatically add section numbers, but the section numbers aren't selectable in the browser, and skipped heading levels aren't handled nicely.

- Javascript and PHP can be added to handle automatic section numbers, but it is likely to add complexity to each numbered heading in each file. (The author is not a Javascript or PHP developer, so this assessment should be taken with a grain of salt.)

- secnum handles automatic section numbering, the resulting section numbers are selectable in the browser, and it does "The Right Thing" for skipped heading levels. However, it is a pre-processor and this isn't useful for live HTML files. (The author uses secnum during the writing of HTML-based documentation. After the documentation is finished, the unnumbered HTML is saved for later modification and the secnum-modified HTML is the version available for general use.)

Each method is useful in different situations. Use the method that best suits your own needs.

WARNINGS

Please be aware of the following when using secnum:

Care must be taken when using secnum as it is a simple parser. It only looks for the presence heading tags and it ignores all other parts of the file contents. secnum does not ensure the heading tags are not in quotes or comments.
secnum assumes the opening and closing heading tags are on the same line.
secnum assumes only one heading-tag group will be found on a line.
If errors are encountered, the output file will not be written. Currently, the only parsing error that secnum recognizes is when it finds mismatched heading tags (e.g., <H2> closed by </H4>.)

In time, secnum may be modified so the warnings will no longer be of concern.

OPTIONS

secnum takes the following options:

-daemon [sleeptime]

secnum

only

The sleeptime value is optional. If it isn't specified, then the default sleep time (10 seconds) will be used. If it is specified, then that will be used for the sleep time.

-daemon may not be used with the -overwrite option.

-depth max-depth

not

-depth 3

max-depth

-overwrite

-overwrite may not be used with the -daemon or -nohtml options.

-section heading-number

section-number

-start section-number

Currently, this is the initial section number only. Starting subsections are not modified by this option. This may change in the future.

-toc

secnum

The heading text is given exactly as it is found in the input file (with the inclusion of section numbering.) Any HTML -- links, bold tags, special characters, etc. -- are left as is and are not cleaned up for display.

-toc may not be used with the -overwrite option.

-verbose

-Version

secnum

-help

AUTHOR

Wayne Morrison, wayne@waynemorrison.com

LICENSE

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.