1 files changed, 185 insertions, 0 deletions
diff --git a/manual/format.me b/manual/format.me
new file mode 100644
index 0000000..1261e21
--- /dev/null
+++ b/manual/format.me
@@ -0,0 +1,185 @@
+.\" Copyright (C), 1995, Graeme W. Wilford. (Wilf.)
+.\" Copyright (c) 2002 Colin Watson.
+.\"
+.\" You may distribute under the terms of the GNU General Public
+.\" License as specified in the file COPYING that comes with the
+.\" man-db distribution.
+.\"
+.\" Thu Sep 21 19:22:47 BST 1995  Wilf. (G.Wilford@ee.surrey.ac.uk) 
+.\" 
+.BS 1 "Formatting"
+.lp
+As already pointed out in the introduction, there are two primary
+formatters common to \*U: \*N and \*T.
+.lp
+In the following sections, I
+will use the term \*T to describe the typesetter formatter and \*N to
+describe the typewriter formatter.
+The term \*R will be used to describe a generic formatter.
+.BS 2 "\*G"
+.lp
+If using the \*G package, there is a further choice, \*G itself.
+Essentially, \*G forms a pipeline of processors including \*T and an output
+processor which translates the ditroff produced by \*T into the appropriate
+output format.
+The default output format, or device, for \*G is \*P.
+Anything else must be specified using the device argument.
+To illustrate \*G, the command
+.ip
+.bx "groff \-Tdvi /dev/null"
+.lp
+will form the following pipeline
+.ip
+troff \-Tdvi /dev/null | grodvi
+.lp
+If \*G is tied to
+.b man 's
+.b \-T
+option, it is still possible for
+.b man
+to produce ditroff via use of the
+.b \-Z
+option.
+.lp
+In \*G 1.09, \*N is bundled as a shell script that calls \*G, which in turn
+calls \*T with the default options
+.b "\-Wall \-mtty-char \-Tascii" ,
+passing the result through
+.b grotty
+before it finally reaches the screen.
+.lp
+It is imperative that the script does not pass pre-processing options
+to \*G's
+command line as
+.b man
+takes care of this separately.
+.BS 2 Devices
+.lp
+Both \*N and \*G may allow output device selection.
+As mentioned previously,
+classic \*N produces output suitable for a typewriter device, classic
+\*T produces output suitable for a
+.b C/A/T
+and \*G produces output suitable for a \*P interpreting device by default.
+.BS 2 "Macros"
+.lp
+There are several \*R macro sets in existence that are suitable for manual
+pages.
+Unfortunately, they tend to be incompatible with each other.
+.lp
+During configuration,
+.b configure
+will attempt to determine a suitable macro set for the local system's manual
+page collection.
+It attempts to use \*N with the following three macro packages:
+
+.TS
+center box tab(@);
+l | l | l .
+macro package@macro filename@nroff command
+_
+andoc@tmac.andoc or andoc.tmac@nroff \-mandoc
+an@tmac.an or an.tmac@nroff \-man
+doc@tmac.doc or doc.tmac@nroff \-mdoc
+.TE
+
+The first that succeeds is used.
+The
+.b andoc
+macro set is suitable for manual pages written using either
+.b an
+or
+.b doc
+macro commands, but not a combination of both.
+.lp
+.BS 2 "Pre-format processors (pre-processors)"
+.lp
+Manual pages may require pre-processing by any of the following
+
+.TS
+center box tab(@);
+l | l | l .
+Program@ID@Pre-processes
+_
+eqn@e@equations
+tbl@t@tables
+grap@g@graphs
+pic@p@pictures
+refer@r@A bibliography
+vgrind@v@program listings
+.TE
+
+It is possible to assign a default pre-processor list that all
+manual pages will be passed through prior to the primary formatter.
+By default, this is empty.
+To define a default list, edit
+.i include/manconfig.h
+and un-comment the following line
+.lp
+/* #define DEFAULT_MANROFFSEQ   "t" */
+.lp
+which will enable
+.b tbl
+processing by default.
+To change the list, replace the
+.b t
+with a suitable string of processor ID's.
+.lp
+Pre-process options may be provided at run time in various forms, but in
+general the pre-processors required by each manual page is indicated in the
+first line of the manual page itself.
+See
+.b man (1)
+for details.
+.lp
+If a manual page does not contain a pre-processor string in its first line,
+it will be scanned for well-known \*R requests used to pass input to
+certain pre-processors.
+Thus, the pre-processor string is often unnecessary for correct output,
+but should nevertheless be included for efficiency.
+.BS 2 "Format scripts"
+.lp
+It is very likely that alternate systems manual pages may require
+non-standard macro packages or possibly even special pre-processors.
+To tackle such problems, special format scripts may be created on a per
+manual hierarchy basis.
+.lp
+If the file
+.ip
+.i <manual_hierarchy>/mandb_nfmt
+.lp
+exists and is executable, it is expected to be able to correctly format a
+manual page originating from
+.i <manual_hierarchy>
+to its standard output.
+It will be supplied with either two or three arguments:
+.(l
+\(bu manual page filename
+\(bu pre-processor string
+\(bu output device (optional)
+.)l
+Similarly, if the option
+.b \-T\c
+.i <device>
+.r
+or
+.b \-t
+was supplied to
+.b man
+and the file
+.ip
+.i <manual_hierarchy>/mandb_tfmt
+.lp
+exists and is executable, it will be used in the same way.
+.lp
+An example of such a script, supplied by Markus Armbruster
+<armbru@pond.sub.org>, who provided support for external formatter scripts,
+can be found as
+.i tools/mandb_fmt\-script
+.lp
+The script can be used as both an \*N and \*T/\*G format script and can be
+installed as
+.i mandb_nfmt
+and hard linked to
+.i mandb_tfmt
+after modification appropriate for your particular site.