notes2html - Converts annotated Perl code to HTML with popup notes or footnotes
notes2html [options] [file]
Options:
--popups, -p display notes as popup windows
--footnotes, -f display notes as footnotes at end of document
--line-numbers, -l print line numbers for each line of code
--fold=n fold code lines longer than n columns (n >= 24)
--title, -t specify title for HTML document and popup notes
--outfile=file specify output file (otherwise stdout)
--help, -? brief help message
--man, -m documentation
--version, -V print program version
<TITLE>
and <H1> header; the string is also used in constructing the
title and header for popup notes. If this option is not specified
then the input file's filename will be used in titles and headers.
notes2html will read a Perl program annotated with inline notes and will create an HTML document that will display the original code with added note references that link to the notes themselves. The notes can be displayed either in separate popup windows or as footnotes at the end of the HTML document.
The syntax of the inline notes is intended to be reasonably simple yet
allow for special features where desired. It is also designed to be
unobtrusive: if you'd like you can leave the inline notes in the
program and they won't affect its execution; otherwise you can use
grep -v '^##' to produce a version of the program without the
notes. Here are some example inline notes to illustrate the syntax:
## This is an inline note referring to the Perl code line below
## that opens a file; inline notes are just Perl comments starting
## with two or more '#' characters and followed by at least one space.
## (You can also add an inline note to normal Perl comments as well.)
open ($ifh, $input_fn) or die "$cmd: cannot open $input_fn: $!";
## You can also provide more than one note reference for a given
## line of code.
### All you have to do is change the number of initial '#' characters.
while (<$ifh>) {
## Text paragraphs in notes are processed using Textile, so you can
## use simple markup, e.g., to emphasize *important things* or to
## cite documents like ??Programming in Perl??, or full HTML markup
## for such things as Perl expressions (like <code>$foo + 2</code>).
## A text paragraph is concluded with a "blank" comment as follows
## (or by a code line).
##
## You can also include preformatted text to refer to one or more
## lines of Perl code (or other content intended to be included
## verbatim) as part of the inline note; as with Pod, preformatted
## text is marked by indenting it more than a regular text paragraph.
##
## $str =~ s/($escape_re)/$escape{$1}/g;
##
## You can include URLs in the preformatted text and they will be
## automatically converted to links; for example, see
##
## http://www.example.com/an-example.html
## ftp://ftp.example.com/pub/foo.tar.gz
##
## You can also include HTML links in regular text paragraphs,
## either by using the standard HTML <A> tag or by using the
## Textile syntax "text of link":http://www.example.com/foo.html.
##
## You can include bulleted lists or numbered lists using
## the standard Textile markup conventions:
##
## * Bulleted list items start with '*'.
## * Don't indent them, or they'll be taken as preformatted text!
## ** You can have sublists...
## *** ...or even sub-sublists
##
## # Mark numbered list items with an initial '#'.
## # Textile will add numbers automatically.
##
## h3. A Final Note
##
## Last but not least, you can use "h3.", "h4.", etc., to provide
## a header for the beginning of an inline note and subheaders
## within it.
The inline notes do not appear as part of the Perl code in the generated HTML. Instead each code line with an inline note (or notes) preceding it is displayed with a righthand Perl comment including note references in the form '[123]'; the note number is either an internal link pointing to a footnote at the end of the document, or a link to display a popup window containing the note.
The generated HTML document and the popup note windows contain only
standard HTML, and should properly validate unless you've included
non-standard HTML markup in your inline notes. In particular, the
main HTML document should validate as HTML 4.01 Strict, while the
popup notes should validate as HTML 4.01 Transitional. (In popup notes
we use the TARGET attribute of the <A> tag, which is not
permitted under the HTML 4.01 Strict DTD.)
One common problem for HTML validation is including something in a
text paragraph that looks like an HTML tag, e.g., referring to a
filehandle <FOO>; in cases like that you'll need to use the
HTML character entities < and >, e.g., write
<FOO> instead. (Note that this is not a problem in
preformatted text, where the escaping of HTML special characters is
done automatically.)
We employ two separate approaches to storing note-related information and generating HTML for notes. When notes are to be displayed as footnotes (i.e., at the end of the HTML document) the approach is straightforward: save all notes in a Perl array as we encounter them in the input, and then iterate over the array to generate HTML for the notes after we have generated HTML for all the code lines.
The approach for handling popup notes is more complicated: As notes
are encountered we do not save them in Perl; rather we generate
JavaScript code to save the HTML for the notes in a JavaScript array
in the context of the HTML document itself. That array can then be
referenced in a JavaScript function popup_note invoked by the
onClick handler for the links associated with note references.
Another possible approach would be to pass the HTML for the note as a
JavaScript string literal directly to the popup_note function. This
would eliminate the need to use a JavaScript array but would introduce
a great deal of complexity in terms of how to properly escape
characters in the string literal, since the string literal would be
interpreted in a mixed HTML/JavaScript context (i.e., the onClick
attribute of an <A> tag). Using a JavaScript variable reduces
the complexity, since the literal is interpreted in more of a pure
JavaScript context (i.e., within an HTML comment between
<SCRIPT> and </SCRIPT> tags).
The content of popup notes does not display when using Microsoft Internet Explorer for Mac OS X. (Instead the word ``undefined'' is displayed where the note contents should be.)
It is not possible to specify the --fold option and let the number of columns default to some reasonable value (e.g., to 80 columns); you must always explicitly specify the number of columns. (This is due to the limitations of the Getopt::Long module.)
The code to recognize URLs in the preformatted parts of inline notes will not recognize URLs with embedded whitespace. Also, the code recognizes only a limited subset of the URI schemes recognized by the IANA (see http://www.iana.org/assignments/uri-schemes).
If a note is included at the very end of the program (i.e., there are no program lines after the note) then a reference to the note will never be printed. The workaround is to put a standard comment after the note.
For consistency of style notes2html generates an initial header for
each popup note using an <H2> tag, not an <H1> tag, to
match the <H2> tag used to introduce a footnote. (An <H1>
header is generated as a title for the code itself.) Using the
Textile markup h1. or h2. within inline notes will produce
headers which look odd and don't properly reflect structural markup
within the generated HTML; you should use only h3. (or higher)
headers within inline notes.
The interpolate subroutine within notes2html does not check to
see whether interpolated variables in the HTML template strings are
defined or not. This is an issue only if you modify notes2html to
change the template strings.
In several places (e.g., the folding algorithm) the code is somewhat kludgy and doesn't necessarily evince proper Perl style. Suggestions for improvement are welcome.
Here are some ideas for ways in which this program could be enhanced and extended:
Allow a note to refer to another note using a symbolic name that would
be converted to a note number in the generated HTML. Such references
should also produce properly behaving links; i.e., a link in a
footnote to another note should be an internal link, while a link in a
popup note to another note should pop up a new window. In the meantime
you can use the --line-numbers option and have a note refer to,
e.g., the note for line 123.
For more information on Textile markup see
http://www.textism.com/tools/textile
Note that Text::Textile does not implement the full Textile specification; for example, it does not support using Textile markup for mailto: URLs.
Version 0.94 (June 27, 2004).
Created by Frank Hecker <hecker@hecker.org>. A few bits of code were inspired by and/or adapted from Rael Dornfest's Blosxom code.
Copyright 2004 Frank Hecker
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the ``Software''), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED ``AS IS'', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.