[Groff-commit] groff/tmac groff_man.man

[Eric S. Raymond]

CVSROOT:        /sources/groff
Module name:    groff
Changes by:     Eric S. Raymond <esr>   07/02/03 11:06:04

Modified files:
        tmac           : groff_man.man 

Log message:
        Document the extension macros.

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/groff/tmac/groff_man.man?cvsroot=groff&r1=1.26&r2=1.27

Patches:
Index: groff_man.man
===================================================================
RCS file: /sources/groff/groff/tmac/groff_man.man,v
retrieving revision 1.26
retrieving revision 1.27
diff -u -b -r1.26 -r1.27
--- groff_man.man       2 Feb 2007 23:07:39 -0000       1.26
+++ groff_man.man       3 Feb 2007 11:06:04 -0000       1.27
@@ -18,17 +18,11 @@
 the original English.
 ..
 .
-.de TQ
-.  br
-.  ns
-.  TP \\$1
-..
-.
 .
 .TH GROFF_MAN @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
 .
 .
-.\" -----------------------------------------------------------------
+.\" ----------------------------------------------------------------
 .
 .SH NAME
 .
@@ -344,6 +338,22 @@
 macro is the macro used for the explanations you are just reading.
 .
 .TP
+.B .TQ
+The 
+.B TQ
+macro sets up header continuation for a .TP macro.  With it, you can
+stack up any number of labels (such as in a glossary, or list of
+commands) before beginning the indented paragraph.  For an example, 
+look just past the next paragraph.
+.IP
+This macro is not defined on legacy Unix systems running classic
+troff. To be certain your page will be portable to those systems, 
+copy its definition from the
+.B an-ext.tmac
+file of a 
+.BR groff 
+installation.
+.TP
 .B .LP
 .TQ
 .B .PP
@@ -477,6 +487,22 @@
 .B RS
 increases the level by\ 1.
 .
+.TP
+.B .EX/.EE
+Example/End Example. Between this pair of macros, filling is
+disabled and the font is set to constant-width.  This is useful for
+formatting code, command, and configuration-file examples.  The
+.B EE 
+macro restores the previous font.
+.sp
+This macro is defined on many (but not all) legacy Unix systems
+running classic troff. To be certain your page will be portable to
+those systems, copy its definition from the
+.B an-ext.tmac
+file of a 
+.BR groff 
+installation.
+.
 .PP
 To summarize, the following macros cause a line break with the
 insertion of vertical space (which amount can be changed with the
@@ -485,6 +511,7 @@
 .BR SH ,
 .BR SS ,
 .BR TP ,
+.BR TQ ,
 .B LP
 .RB ( PP ,
 .BR P ),
@@ -492,9 +519,11 @@
 and
 .BR HP .
 The macros
-.B RS
+.BR RS ,
+.BR RE ,
+.BR EX ,
 and
-.B RE
+.BR EE
 also cause a break but no insertion of vertical space.
 .
 .
@@ -585,6 +614,148 @@
 .
 .\" -----------------------------------------------------------------
 .
+.SH "MACROS TO DESCRIBE HYPERLINKS AND EMAIL ADDRESSES"
+
+The following macros are not defined on legacy Unix systems
+running classic troff. To be certain your page will be portable to
+those systems, copy their definitions from the
+.B an-ext.tmac
+file of a 
+.BR groff installation.
+
+Using these macros helps ensure that you will get hyperlinks when your
+manual page is rendered in a browser or other program that is Web-enabled.
+
+.TP
+.B UR/UE
+Wrap a World Wide Web hyperlink.  The argument to the
+.B UR
+is the URL; thereafter, lines until 
+.B UE
+are collected and used as the link text.  On a device that is not 
+a browser, 
+
+.EX
+this is a link to
+\&.UR http:\&//randomsite,org/fubar
+some random site
+\&.UE
+given as an example
+.EE
+
+will usually display like this: "this is a link to some random 
+site <http:\&//randomsite,org/fubar> given as an example".
+
+.TP
+.B MT/ME
+Wrap an email address.  The argument of MT is the address; text
+following, until
+.BR ME ,
+is a name to be associated with the address.  On a device that is not 
+a browser, 
+
+.EX
+contact
+\&.UR address@hidden,net
+Fred Foonly
+\&.UE
+for more information
+.EE
+
+will usually display like this: "contact Fred Foonly
+<address@hidden> for more information".
+
+.\" -----------------------------------------------------------------
+.
+.SH "MACROS TO DESCRIBE COMMAND SYNOPSES"
+.
+The following macros are not defined on legacy Unix systems
+running classic troff. To be certain your page will be portable to
+those systems, copy their definitions from the
+.B an-ext.tmac
+file of a 
+.BR groff installation.
+
+These macros are a convenience for authors.  They will also assist 
+automated translation tools and help broswers in recognizing 
+command synopses and treating them differently from running text.
+.
+.TP 
+.B SY
+Begin synopsis. Takes a single argument, the name of a command.  Text
+following, until closed by
+.BR YS ,
+will be set with a hanging indent with the width of the command name 
+plus a space.  This produces the traditional look of a Unix command
+synopsis.
+.TP
+.B OP
+Describe an optional command argument.  The arguments of this macro
+will be set surrounded by option braces in the default Roman font. 
+.TP
+.B YS
+This macro restores normal indentation at the end of a command synopsis. 
+.LP
+Here is a real example:
+
+.EX
+\&.SY groff
+\&.OP -abcegiklpstzCEGNRSUVXZ
+\&.OP -d cs
+\&.OP -f fam
+\&.OP -F dir
+\&.OP -I dir
+\&.br
+\&.OP -K arg
+\&.OP -L arg
+\&.OP -m name
+\&.OP -M dir
+\&.OP -n num
+\&.OP -o list
+\&.OP -P arg
+\&.br
+\&.OP -r cn
+\&.OP -T dev
+\&.OP -w name
+\&.OP -W name
+\&.RI [ file
+\&.IR ... ]
+\&.YS
+.EE
+
+produces the following output:
+
+.SY groff
+.OP -abcegiklpstzCEGNRSUVXZ
+.OP -d cs
+.OP -f fam
+.OP -F dir
+.OP -I dir
+.br
+.OP -K arg
+.OP -L arg
+.OP -m name
+.OP -M dir
+.OP -n num
+.OP -o list
+.OP -P arg
+.br
+.OP -r cn
+.OP -T dev
+.OP -w name
+.OP -W name
+.RI [ file
+.IR ... ]
+.YS
+
+Note the use of 
+.B br
+requests to control line breaking.  You can insert plain text as
+well; this will look like the traditional (unornamnted) syntax 
+for a required command argument or filename.
+.
+.\" -----------------------------------------------------------------
+.
 .SH "MISCELLANEOUS"
 .
 The default indentation is 7.2n in troff mode and 7n in nroff mode
@@ -727,10 +898,26 @@
 package should be used.
 .TP
 .B an-old.tmac
-All
+Most
 .B man
 macros are contained in this file.
 .TP
+.B an-ext.tmac
+The extension macro definitions forx
+.BR \&.SY , 
+.BR \&.OP , 
+.BR .YS , 
+.BR .TQ , 
+.BR .EX/.EE ,
+.BR .UR/.UE ,
+and
+.BR .MT/.ME 
+are contained in this file.  It is written in classic troff,
+and released for free re-use, and not copylefted; manual page authors
+concerned about portability to legacy Unix systems are encouraged to
+copy these definitions into their pages, and maintainers of troff
+or its workalikes are encouraged to re-use them.
+.TP
 .B man.local
 Local changes and customizations should be put into this file.
 .
@@ -763,12 +950,20 @@
 .
 .\" -----------------------------------------------------------------
 .
-.SH AUTHOR
+.SH AUTHORS
 .
 This manual page was originally written for the Debian GNU/Linux
-system by Susan G. Kleinmann <address@hidden>, corrected and updated
-by Werner Lemberg <address@hidden>, and is now part of the GNU troff
-distribution.
+system by 
+.MT address@hidden .
+Susan G. Kleinmann
+.ME
+It was corrected and updated by
+.MT address@hidden .
+Werner Lemberg
+.ME
+The extension macros were documented (and partly designed) by
+.MT address@hidden .
+Eric S. Raymond
 .
 .\" Local Variables:
 .\" mode: nroff