secnum [options] <infile> [outfile]
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>126.96.36.199.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.
- CSS can automatically add section numbers, but the section numbers aren't selectable in the browser, and skipped heading levels aren't handled nicely.
- 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.
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.
-overwrite may not be used with the -daemon or -nohtml options.
Currently, this is the initial section number only. Starting subsections are not modified by this option. This may change in the future.
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.
Copyright 2015 Wayne Morrison
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
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.