The Annoyance Filter.pdf - Fourmilab

214 DEVELOPMENT LOG ANNOYANCE-FILTER §256
to correct these items, and modified the Makefile.in targets to generate a first draft HTML in
annoyance−filter_man_raw.html, which is post-processed by the fixup program into the final annoyance−filter_ma
file, which is now included in the distribution by the dist target and copied to the Web directory by
publish, both of which targets generate it if necessary.
Added a mantroff target to Makefile.in to preview the troff format manual page using “groff␣−X”
(if available on the system—if not, don’t do that).
Wrote a docutil/cwebextract.pl Perl program which searches a CWEB file for a named section (which
can be a regular “@” section, so long as the search target appears on the same line as the “@”. If the
section is found (matching is case insensitive and the search target given on the command line matches
the first line containing a substring which it matches), the contents of the documentation section is
written to standard output, trimming leading and trailing blank lines. The end of the documentation
section is the next line which begins with an at sign or the end of file.
Moved the TEX definitions used to generate the options list to the top of annoyance−filter.w so they
don’t confuse the automatic extraction and translation process.
Modified docutil/cwebtex2man.pl to ignore TEX \bigskip commands, carefully avoiding generating
a nugatory .PP in the troff output due to two consecutive blank lines once the command has been
ignored.
Added the docutil directory and its contents to the distribution generation target in Makefile.in.
Generation of the “OPTIONS” section of the annoyance−filter.1 manual page from the corresponding
section of annoyance−filter.w is now completely Turbo Digital TM . The invariant parts of
the manual page are now defined in the “manual page macro” file annoyance−filter.manm. The
Makefile.in now understands that annoyance−filter.1 is generated by processing this file with
docutil/manm_expand.pl which expands \"%include statements in the macro file by extracting the
specified section from the named CWEB file with docutil/cwebextract.pl, translating it into manual
page troff with docutil/cwebtex2man.pl, and inserting it in the output file in place of the include
statement. This completely eliminates all manual labour when updating the options in the manual page
and guarantees that changes to the option documentation in annoyance−filter.w are propagated to
the manual page document. The same mechanism can be used for other common documentation as the
need arises.
2002 October 3
Subtly obfuscated the E-mail address to which bugs should be reported in the manual page so the
process of transforming it into HTML won’t result in a deadly mailto: link or a sniffable address in
the page. Visual fidelity for human readers is maintained.
Updated the Web document to reflect the existence of the HTML manual page and added links to it.
Added a reference to the PDF document to the “SEE ALSO” section of annoyance−filter.manm.
Fixed an embarrassing hyphenation of a file name by prefixing the offending word with the troff
“don’t hyphenate” escape “\%”. (Apparently, even in nh mode, troff will hyphenate a word which
contains an embedded hyphen unless you explicitly forbid it.)
Added the .w files to the winarch.zip archive used to transfer files to build for Win32. While they
aren’t strictly required, they’re awfully handy to have should you encounter compile errors, which are
reported with line numbers from the CWEB file. Looking it up while on Windows and patching the C++
file is a lot quicker than booting back into a real operating system to explore the problem.
In 〈 Check whether folder is a directory of messages 135 〉 there was an erroneous reference to dirFolder
not conditional on HAVE_DIRECTORY_TRAVERSAL—fixed.
The mailFolder constructor which accepts a file name in a string re-used the ifstream isc, which was
previously used only when reading compressed files. This caused compile errors on systems where