.\" Copyright (c) 2000,2001 Udo Erdelhoff. All rights reserved.
.\" Written for the FreeBSD German Documentation Project
.\"
.\" Redistribution and use in source and compiled forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\"
.\"  1. Redistributions of source code must retain the above
.\"     copyright notice, this list of conditions and the following
.\"     disclaimer as the first lines of this file unmodified.
.\"
.\"  2. Redistributions in compiled form must reproduce the above
.\"     copyright notice, this list of conditions and the following
.\"     disclaimer in the documentation and/or other materials provided
.\"     with the distribution.
.\"
.\" THIS DOCUMENTATION IS PROVIDED BY UDO ERDELHOFF "AS IS" AND ANY EXPRESS
.\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
.\" DISCLAIMED. IN NO EVENT SHALL UDO ERDELHOFF BE LIABLE FOR ANY DIRECT,
.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
.\" IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF
.\" THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\" $Id: makemanent.1,v 1.10 2002/11/24 10:48:59 ue Exp $
.Dd July 22, 2000
.Dt MAKEMANENT 1
.Os FreeBSD
.Sh NAME
.Nm makemanent
.Nd make man entities
.Sh SYNOPSIS
.Nm
.Op Fl Fl usegroups
.Oo Fl Fl cutoff
.Oo Oo "\&CC" Oc Ns "\&YY" Oc
.No "MMDDhhmm" Ns Op ".SS"
.Oc
.Op Fl Fl entityfile Ar entityfile
.Op Fl Fl mandir Ar mandir
.Sh DESCRIPTION
The
.Nm
utility creates SGML entity definitions suitable for use in the
.Qq Docbook Manual Page Entities
document used by the
.Fx
Documentation Project
.Pq Qq 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.
.Pp
Invoking
.Nm
without options will create manpage entity definitions for all on-line manual
pages found in
.Pa /usr/share/man/man*
unless the manpage entity was already defined in
.Pa /usr/doc/share/sgml/man-refs.ent .
.Bl -tag -width "--entityfile entityfile"
.It Fl -cutoff Ar timestamp
Ignore manual pages that haven't been modified since
.Ar timestamp .
.Ar timestamp
must be a valid argument for the
.Fl t
option of
.Xr touch 1 .
.It Fl -entityfile Ar entityfile
read manpage entity defintions from
.Ar entityfile
instead of
.Pa /usr/doc/share/sgml/man-refs.ent .
.It Fl -includeold
Print the old manpage entity defintions as well.
.It Fl -mandir Ar mandir
Directory to search instead of
.Pa /usr/share/man/man* .
.It Fl -usegroup
Use manual page groups instead of single files during dupe detection.
.El
.Pp
.Nm
uses the perl
.Xr Getopt::Long 3
package to process its commandline and benefits from the typical features of
this package:
.Bl -bullet
.It
The second dash is optional
.It
Option names may be abbreviated to uniqueness
.Po
.Fl c ,
.Fl e ,
.Fl i ,
.Fl m ,
.Fl u
.Pc
.It
The
.Fl Fl manpage
and
.Fl Fl entityfile
options can be specified more than once to search additional directories
and entity definition files.
.El
.Ss Usefull Invocations
.Bl -bullet
.It
Use
.Nm
.Fl -includeold
as a filter command when editing
.Pa /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
.Xr sortmanent 1
to get the sorting order of the original.
.It
Use
.Nm
.Fl -entityfile /dev/null
to create a list of manpage entity definition for one directory.
.It
Use
.Nm
.Fl -includeold Fl -mandir Ar /nonexistant Fl -entityfile Ar file1
to extract the manpage entity definitions from
.Ar file1 .
.It
Add further
.Fl -entityfile Ar 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.
.El
.Ss The Gory Details of the Entity Generation Process
After the comand line has been parsed,
.Nm
starts to scan the entityfile(s) for manpage entity definition.
The scanner is extremly strict.
Lines NOT starting with the string
.Ql <!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 one of these perl regular expressions
.Dl ^"<citerefentry/<refentrytitle/([^/]+)/<manvolnum/([0-9nl])//"$
.Dl ^"<citerefentry vendor='.+'/<refentrytitle/([^/]+)/<manvolnum/([0-9nl])//"$
.Pq 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.
.Pp
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.
.Pp
Unaccessable files cause a non-fatal error, a warning is printed to stderr.
.Ss The Search for Filenames
For each
.Ar mandir
specified,
.Nm
will execute
.Xr find 1
to find all files in and below that
.Ar mandir .
If
.Nm
cannot execute
.Xr find 1
for any reason,
a warning message will be displayed and the directory is skipped.
.Pp
Any directory prefixes and the suffixes
.Ql aout
and
.Ql gz
are removed from the filenames returned by
.Xr 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.
.Ss Keeping Things Fresh
If the option
.Fl -cutoff
was specified on the command line,
.Nm
will call
.Xr touch 1
to create the file
.Pa /tmp/mme-mark.\<process-id\>
using the supplied
.Ar timestamp
as the files' modification time.
The file is used for the
.Fl newer
command of
.Xr find 1
during the search.
It will be created before the first execution of
.Xr find 1
and will be removed when the last
.Xr find 1
process has terminated.
.Ss Entity Name Generation
After all
.Pa 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,
.Dl man.\<command\>.\<volume\>
If the name contains characters not allowed in a general entity name,
these characters will be replaced by a dot
.Pq Ql \&. .
.Ss Duplicate Detection and Removal
If the new entity is a key in the hash of old entity names,
the new entity will be dropped.
.Ss Entity Value Generation
Otherwise, the value of the new general entity is created.
The default entity value is
.Dl \<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.
.Ss Final Assembly
The last step is the creation of a legal entry for the
.Qq Docbook Manual Page Entities
document.
The
.Nm
utility prints the sequence
.Dl \<!ENTITY Ar hash-key Qo Ar hash-value Qc Ns \en
for each key found in the hash of new entities.
If
.Fl -includeold
was specified on the command line,
the process is repeated for the hash containing the old manpage entities.
.Ss Manual Group Mode
In manual group mode,
manual pages installed under many different names receive special treatment.
During the search,
.Xr find 1
is called with the option
.Ql -ls
instead of the usual
.Ql -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.
.Pp
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
.Em 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
.Ql manual group
for the remainder of this document, and the term
.Ql member of a manual group
refers to one of the filenames in the list.
.Pp
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.
.Pp
.Dq True
manual groups
.Pq 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
.Em not
generated at this point.
.Pp
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.
.Pp
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.
.Ss Using Manual Group Mode
Manaul group mode was implemented to handle cases like the manual page
.Pa builtins.1 ,
which is installed under eighty-four(!) different names.
If
.Fl -usegroups
is specified and one of the
.Ar entityfiles
contains the manpage entity
.Qq man.builtins.1 ,
.Nm
will not create the other 83 manpage entities.
.Pp
To use the manual group mode efficiently,
.Nm
should be started with the arguments
.Dl Fl -entityfile Ar /dev/null Fl -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
.Qq important or usefull
members.
The reduced list should be added to the main manpage entity definition
file and further invocations of
.Nm
should aways include the argument
.Fl -usegroup .
This way, the discarded members of the manual page group will never be
generated again.
.Sh DIAGNOSTICS
The
.Nm
utility exits 0 on success, and >0 if a unrecoverable error occurs.
.Sh COMPATIBILITY
The format of the entity definitions created by
.Nm
is indentical to the format used in the
.Qq Docbook Manual Page Entites
document created and used by the
.Fx
Documentation Project.
.Sh SEE ALSO
.Xr find 1 ,
.Xr perl 1 ,
.Xr sortmanent 1 ,
.Xr touch 1 ,
.Xr Getopt::Long 3
.Sh HISTORY
The first version of
.Nm
utility was written in July 2000.
Vendor attribute support was added in November 2002.
.Sh AUTHORS
The
.Nm
utility and this manual page were written by
.An Udo Erdelhoff Aq ue@nathan.ruhr.de
.Sh BUGS
Scanning directories living on different file systems while using manual
group mode may lead to strange results.
Entity names containing several special characters may look strange.
The two regular expressions should be compacted into one