MAKEMANENT(1)

NAME
makemanent - make man entities

SYNOPSIS
makemanent [- -usegroups] [- -cutoff [[CC]YY] MMDDhhmm[.SS]] [- -entityfile entityfile] [- -mandir mandir]

DESCRIPTION
The makemanent utility creates SGML entity definitions suitable for use in the "Docbook Manual Page Entities" document used by the FreeBSD Documentation Projekt ("manpage entities"). The manpage entitiy definitions are displayed on the standard output, one complete entity defintion per line. Warnings and progress messages are sent to standard error.

Invoking makemanent without options will create manpage entity definitions for all on-line manual pages found in /usr/share/man/man* unless the manpage entity was already defined in /usr/doc/share/sgml/man-refs.ent.

--cutoff timestamp
    Ignore manual pages that haven't been modified since timestamp. timestamp must be a valid argument for the -t option of touch(1).

--entityfile entityfile
    read manpage entity defintions from entityfile instead of /usr/doc/share/sgml/man-refs.ent.

--includeold
    Print the old manpage entity defintions as well.

--mandir mandir
    Directory to search instead of /usr/share/man/man*.

--usegroup
    Use manual page groups instead of single files during dupe detection.

makemanent uses the perl Getopt::Long(3) package to process its commandline and benefits from the typical features of this package:

•   The second dash is optional

•   Option names may be abbreviated to uniqueness ( -c, -e, -i, -m, -u)

•   The - -manpage and - -entityfile options can be specified more than once to search additional directories and entity definition files.

  Usefull Invocations

•   Use makemanent --includeold as a filter command when editing /usr/doc/share/sgml/man-refs.ent to replace the current list of manpage entites with an updated list. You may want to pipe the output through sortmanent(1) to get the sorting order of the original.

•   Use makemanent --entityfile -/dev/null to create a list of manpage entity definition for one directory.

•   Use makemanent --includeold --mandir /nonexistant --entityfile file1 to extract the manpage entity definitions from file1.

•   Add further --entityfile file statements to join the contents of several files with manpage entity definitions. Manpage entity defintions defined in two or more files will be printed only once.

  The Gory Details of the Entity Generation Process
After the comand line has been parsed, makemanent starts to scan the entityfile(s) for manpage entity definition. The scanner is extremly strict. Lines NOT starting with the string ‘<!ENTITY man.’ are ignored. All other lines are parsed to gather the name of the general entity and its value. There must be exactly one space between the name of the entity and the value and the value must match the perl regular expression
    ^"<citerefentry/<refentrytitle/([^/]+)/<manvolnum/([0-9nl])//"$
(all escapes removed) to be accepted. Lines that do not conform to this format cause a warning message to be displayed and the entity definition is ignored.

If the line conformes to this format, the substring matched by the first parenthesized subexpression is used as the command name and the substring matched by the second parenthesized subexpression is used as the manual volume. The set of entity name, command name, and manual volume is stored in a list of old entites.

Unaccessable files cause a non-fatal error, a warning is printed to stderr.

  The Search for Filenames
For each mandir specified, makemanent will execute find(1) to find all files in and below that mandir. If makemanent cannot execute find(1) for any reason, a warning message will be displayed and the directory is skipped.

Any directory prefixes and the suffixes ‘aout’ and ‘gz’ are removed from the filenames returned by find(1). If the remainder of the filename matches the regular expression ^.*.[0-9nl]$, the file is treated as a manual page and the filename is used as key in a hash containing the new manaul pages. This way, duplicates are automatically removed.

  Keeping Things Fresh
If the option --cutoff was specified on the command line, makemanent will call touch(1) to create the file /tmp/mme-mark.<process-id> using the supplied timestamp as the files' modification time. The file is used for the -newer command of find(1) during the search. It will be created before the first execution of find(1) and will be removed when the last find(1) process has terminated.

  Entity Name Generation
After all mandirs have been searched, the filenames are converted into manpage entities. Every entry in the list of filenames had to match the regular expression ^(.*).([0-9nl])$ to enter this list. The substring matched by the first parenthesized subexpression is used as the command and the substring matched by the second parenthesized subexpression is used as the volume of this manual page. These values are used to create the inital name of the new manpage entity,
    man.<command>.<volume>
If the name contains characters not allowed in a general entity name, these characters will be replaced by a dot (‘’)..

  Duplicate Detection and Removal
If the new entity is a key in the hash of old entity names, the new entity will be dropped.

  Entity Value Generation
Otherwise, the value of the new general entity is created. The default entity value is
    <citerefentry/<refentrytitle/<command>/<manvolnum/<volume>//
The entity name and the entity are value used as key and value in a seperate hash containing all new manpage entites.

  Final Assembly
The last step is the creation of a legal entry for the "Docbook Manual Page Entities" document. The makemanent utility prints the sequence
    <!ENTITY hash-key "hash-value"\n
for each key found in the hash of new entities. If --includeold was specified on the command line, the process is repeated for the hash containing the old manpage entities.

  Manual Group Mode
In manual group mode, manual pages installed under many different names receive special treatment. During the search, find(1) is called with the option ‘-ls’ instead of the usual ‘-print’ to get the name and the inode number of the file. Prefix and suffixes are stripped from the filename like in normal mode. The inode number of the file is used as the key for the hash of new filenames.

If the key is not present in the hash, inode number and file name are used as key and value of a entry. If the key is present in the hash, the corresponding value is treated as a list of filenames, seperated by single spaces. If the filename is not present in the list, it is appended to the list and list is stored as the new hash value. The list of filenames is called the ‘manual group’ for the remainder of this document, and the term ‘member of a manual group’ refers to one of the filenames in the list.

When generating entity names, a seperate enity name is generated for each member of a manual group. If a manual group has only one member, it is treated like a normal filename and an entity value is generated. The entity name and the entity value are used as key and value in the normal hash for new entities.

“True” manual groups (i.e. with more than one member) receive a different treatment. The entity names generated from the members of the manual group are checked againt the hash containing the old manpage entities. If one or more of the entity names are found in this hash, the whole group is dropped. The manual groups that survive this check are added to a special hash for new manual groups. The inode number is used as key for this group hash, the manual group is the value for the group hash. The entity values are not generated at this point.

During the final assembly phase, the manpage entites for the manual groups are printed last. Each manual group is preceeded by an extra newline and an SGML comment containing the key for the manual group and the number of members in this manual group.

The entity names and entity values are (re-)generated on the fly and printed to the standard output. The manpage entity definitions themselves are not modified.

  Using Manual Group Mode
Manaul group mode was implemented to handle cases like the manual page builtins.1, which is installed under eighty-four(!) different names. If --usegroups is specified and one of the entityfiles contains the manpage entity "man.builtins.1", makemanent will not create the other 83 manpage entities.

To use the manual group mode efficiently, makemanent should be started with the arguments
    --entityfile /dev/null --usegroups
and the ouput should be saved to a seperate file. Manual groups with only a few members should be left alone. Large manual groups should be reduced to their "important or usefull" members. The reduced list should be added to the main manpage entity definition file and further invocations of makemanent should aways include the argument --usegroup. This way, the discarded members of the manual page group will never be generated again.

DIAGNOSTICS
The makemanent utility exits 0 on success, and >0 if a unrecoverable error occurs.

COMPATIBILITY
The format of the entity definitions created by makemanent is indentical to the format used in the "Docbook Manual Page Entites" document created and used by the FreeBSD Documentation Project.

SEE ALSO
find(1), perl(1), sortmanent(1), touch(1), Getopt::Long(3), re_format(7)

HISTORY
The first version of makemanent utility was written in July 2000.

AUTHORS
The makemanent utility and this manual page were written by Udo Erdelhoff <ue@nathan.ruhr.de> or <Udo.Erdelhoff@gmx.net>

BUGS
Scanning directories living on different file systems while using manual page mode may lead to strange results. Entity names containing special characters may look strange.