README file for "mkreadmes" (version 1.0)

$Id: README,v 1.6 2012/03/09 13:15:36 conrads Exp $

Mkreadmes is designed to be a very fast, flexible and easy-to-use alternative
to the standard "make readmes" for building the README.html files for the
FreeBSD Ports Collection, building the files in a fraction of the time of the
standard method.

The program allows you to build the README.html files at any level within
the ports tree: top-level, category, or individual port, accepting any
number of command line arguments specifying category or port directories
to build from.  If no command line arguments are provided, the default
is to build the files for the entire ports tree.

The top-level ports directory defaults to the standard "/usr/ports", or
the current setting of the environment variable PORTSDIR, if defined.
The command line option "-p pathname" may also be used (which will also
override the PORTSDIR setting).

As an added convenience, the program will, by default, treat any relative
pathnames provided on the command line (except for "." and "..") as being
relative to the top-level ports directory, so to build the files for a
category, only the category's name is required, or category/port for an
individual port.  This behavior may be disabled by using the "-n" (normal)
option, causing relative pathnames to resolved in the usual fashion (though
I'm not sure why you'd want to do that).  :-)

In addition, the package provides an alternative set of template files
under ${PREFIX}/share/mkreadmes/Templates (the files used as a "blueprint"
for the output HTML files) which I consider to be an improvement over the
standard files under $PORTSDIR/Templates.  The program defaults to using
its own templates, but if you prefer to use the standard set (or another
set in some other location), use the command line option "-t pathname".

The "-v" option increases the program's level of verbosity.

At verbose=0, the only messages displayed are those that indicate which
category (or the top-level directory) is currently being built.  No message
is displayed for an individual port, unless only a single port is being built.

At verbose=1 (a single "-v"), the program will also display the current setting
of the top-level directory, and of the templates directory, and redisplay them
if they're changed (by using the "-p" or "-t" options more than once each).  A
message will also be displayed if the "-n" option is used.

At verbose=2 ("-vv"), the program will also display messages when the index
and/or template files are loaded.

Finally, at verbose=3 ("-vvv"), the program will also display the "Making
README.html for port..." messages for every port being built.

To silence all messages other than error messages, use the "-q" (quiet)
option.

For help, use the "-h" option.

I think you'll find mkreadmes a very pleasant alternative to the
painfully slow "make readmes".  Enjoy!

--
Conrad J. Sabatier <conrads@cox.net>
March 1, 2012

