cl2xhtml

(Convert a GNU-style ChangeLog to XHTML Strict)

SYNOPSIS

cl2xhtml [-hv] -n name -s style [input]

DESCRIPTION

cl2xhtml converts a GNU-style ChangeLog to XHTML Strict, marking the various syntactic elements of the ChangeLog entries so that a style sheet can apply syntax highlighting or other desired formatting. Line breaks before entries for a new file or a new function are preserved, as are paragraph breaks in the ChangeLog. The e-mail address is stripped (the new-style date entry format is expected).

The -n option should be used to tell cl2xhtml which package's ChangeLog it is formatting. Currently, the -s option must also be used to specify the style sheet for the generated XHTML.

ChangeLog data is read from input, or from standard input if no input argument is given. XHTML is written to standard output. The output is formatted as a description list, since that maintains the indentation of entries on most browsers.

cl2xhtml assumes that the ChangeLog is encoded in UTF-8 and specifies a character set of UTF-8 in its XHTML output.

OPTIONS

-h, --help

Print brief usage information and exit.

-n name, --name=name

Specifies the name of the program that the log data is for, used by cl2xhtml to create the page title and top heading.

-s style, --style=style

Specifies the style sheet to which the generated XHTML page should refer. This should be a URL (possibly relative to the location where the XHTML page will be placed), not just a file name.

--viewcvs=url

Link file names to the ViewCVS page for that file and versions to the ViewCVS diff page for that version. Requires the revision numbers appear in the ChangeLog in paretheses after the file names to do the version links. (This is the output format of cvs2cl with the --revisions option.)

-v, --version

Print the version of cl2xhtml and exit.

EXAMPLES

Generate the XHTML-formatted ChangeLog for a package named podlators and save it into a file called changes.html:

    cl2xhtml -n podlators -s '/styles/change.css' ChangeLog > changes.html

The generated XHTML will refer to /styles/change.css as the URL to the style sheet.

BUGS

This program is very picky about format and may not fully support all ChangeLog conventions. Please let me know if there's any specific feature that you've missed.

Currently, this program just throws uncaught exceptions if anything goes wrong, which is less than ideal. At least the common errors should probably be caught and result in good diagnostic output.

There's no way not to generate a reference to a style sheet.

The generated XHTML is extremely ugly.

The parsing code is very difficult to maintain, and needs to be rewritten into a full ChangeLog parser and an HTML output layer that prints out an HTML representation of a parsed entry.

SEE ALSO

cvs2cl(1)

The GNU Coding Standards, <http://www.gnu.org/prep/standards/>. This may be available on your system as the info page standards. This document specifies the format of the ChangeLog file.

The XHTML 1.0 standard at <http://www.w3.org/TR/xhtml1/>.

Current versions of this program are available from my web tools page at <http://www.eyrie.org/~eagle/software/web/>.

AUTHOR

Russ Allbery <rra@stanford.edu>

COPYRIGHT AND LICENSE

Copyright 2002, 2003, 2006, 2008, 2013 Russ Allbery <rra@stanford.edu>

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.

Last spun 2013-07-01 from POD modified 2013-01-04