NAME

make-readmes -- generate README.html files from cached data

SYNOPSIS

make-readmes [-hvqw] [-c dir] [-t directory] [-d directory]

DESCRIPTION

make-readmes processes the cached port description data into README.html files, populating a directory structure paralleling the ports directory tree. The cache contains a record of the one-line description of all ports generated by "make describe", indexed by the port origin directory. It also contains a record of which Makefiles are included by the port's Makefile, but that information is not used by make-readmes.

make-readmes follows the "SUBDIR" variable settings from the top level /usr/ports/Makefile via the per-category makefiles to individual ports, creating the corresponding directory heirarchy as it goes, and editing data read from the cache into the README.html template files it outputs.

Configuration Files

make-readmes shares configuration files with portindex, cache-init, cache-update and find-updated. Any configuration settings are taken from the following locations, where the later items on this list override the earlier:

Built-in settings from the FreeBSD::Portindex::Config perl module.
The system wide configuration file /usr/local/etc/portindex.cfg
The per-user configuration file ${HOME}/.portindexrc (ignored if the program is being run by the superuser)
The local configuration file, found in the current working directory of the cache-init process ./.portindexrc (ignored if the program is being run by the superuser)
The program command line.

All of the configuration files are optional. A summary of the resultant configuration options including the effect of any command line settings is printed as part of the help text when portindex is invoked with the "-h" option.

OPTIONS

-h
--help: Print a brief usage message and a summary of the configuration settings after command line processing and then exit.
-v
--verbose: Turn on verbose output printed to "STDERR". This is the default.
-w
--warnings: Turn on warning messages about duplicate ports and ports unreferenced from their catergory Makefile. Default: off.
-nowarnings: Turn off warning messages. This is the default.
-q
--quiet
--noverbose: Turn off verbose output to "STDERR". Using both the -v amd -q options together does not make any sense, but neither does it generate an error. The last mentioned of the two options will prevail.
-c dir
--cache-dir=dir: The location of the portindex data cache, by default /var/db/portindex.
-C file
--cache-file=file: Berkeley DB Btree file containing the cached and post-processed values of a number of "make" variables for all of the ports in the tree. This file name will be relative to the cache directory (-c option above) unless an absolute path is given. Defaults to portindex-cache.db.
-t directory
--template-dir=directory: Directory containing the templates for the README.html files for the top of the tree, for each category and for each different port. Default: "$PORTSDIR/Templates"
-d directory
--output-directory=directory: Top-level directory beneath which to create a copy of the ports directory tree containing the generated README.html files. Will create the top-level directory so long as the directory above that already exists. Any pre-existing README.html files will be overwritten. Default: ./ports in the current working directory.

FILES

/usr/ports: The default ports directory.
/var/db/portindex: The location of the data cache.
portindex-cache.db: Btree file containing cached "make describe" output.
__db.001, __db.002, __db.003: Files used as part of the internal workings of BerkeleyDB, for memory pool management and DB locking. Will be recreated automatically if deleted.
portindex-timestamp: This file contains the last time and date that the cache was updated or modified.
/usr/local/etc/portindex.cfg: System-wide configuration file.
${HOME}/.portindexrc: Per-user configuration file
./.portindexrc: Local configuration file

BUGS

Unless the "--crunch-whitespace" option is given, make-readmes extracts the "COMMENT" lines from the "make describe" output exactly as shown. "make readmes" collapses multiple spaces to single.