From e0023883c6d2e6745a19e4b48e186ed156c1fca8 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 17:19:27 +0200 Subject: Adding upstream version 2.11.2. Signed-off-by: Daniel Baumann --- manual/format.me | 185 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 185 insertions(+) create mode 100644 manual/format.me (limited to 'manual/format.me') diff --git a/manual/format.me b/manual/format.me new file mode 100644 index 0000000..1444685 --- /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 docs/COPYING.GPLv2 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 /mandb_nfmt +.lp +exists and is executable, it is expected to be able to correctly format a +manual page originating from +.i +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 +.r +or +.b \-t +was supplied to +.b man +and the file +.ip +.i /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 +, 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. -- cgit v1.2.3