[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Groff-commit] groff ChangeLog tmac/groff_man.man tmac/groff_t...
|
From: |
Werner LEMBERG |
|
Subject: |
[Groff-commit] groff ChangeLog tmac/groff_man.man tmac/groff_t... |
|
Date: |
Tue, 20 Feb 2007 19:08:44 +0000 |
CVSROOT: /cvsroot/groff
Module name: groff
Changes by: Werner LEMBERG <wl> 07/02/20 19:08:44
Modified files:
. : ChangeLog
tmac : groff_man.man groff_trace.man
Log message:
* tmac/groff_man.man: Revised to improve visual appearance.
Reduce use of future tense.
* tmac/groff_trace.man: Revosed to improve visual appearance.
CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/groff/ChangeLog?cvsroot=groff&r1=1.1074&r2=1.1075
http://cvs.savannah.gnu.org/viewcvs/groff/tmac/groff_man.man?cvsroot=groff&r1=1.33&r2=1.34
http://cvs.savannah.gnu.org/viewcvs/groff/tmac/groff_trace.man?cvsroot=groff&r1=1.6&r2=1.7
Patches:
Index: ChangeLog
===================================================================
RCS file: /cvsroot/groff/groff/ChangeLog,v
retrieving revision 1.1074
retrieving revision 1.1075
diff -u -b -r1.1074 -r1.1075
--- ChangeLog 19 Feb 2007 22:17:35 -0000 1.1074
+++ ChangeLog 20 Feb 2007 19:08:44 -0000 1.1075
@@ -1,23 +1,18 @@
-2007-02-19 Eric S. Raymond <address@hidden>
-
- * tmac/groff.man: This page is now viewer-portable.
+2007-02-20 Werner LEMBERG <address@hidden>
- * tmac/groff.man: Eliminate use of .eo/.ec.
+ * tmac/groff_man.man: Revised to improve visual appearance.
+ Reduce use of future tense.
- * tmac/groff.man: Second step towards eliminating use of .eo/.ec.
+ * tmac/groff_trace.man: Revosed to improve visual appearance.
- * tmac/groff.man: Fix some minor rendering bugs that don't
- show up readily under eyeball inspection but do when the
- formatted new version is diffed against an old one.
-
- * tmac/groff.man: Surround args 2 through N of each .REQ macro
- with quotes. This will enable us not to rely on the shift
- request, which is nonportable.
+2007-02-19 Eric S. Raymond <address@hidden>
- * tmac/groff.man: First step towards eliminating use of .eo/.ec.
+ Make groff.man viewer-portable.
- * tmac/groff.man: Get rid of the big, ugly, and totally
- nonportable ExecFF macro. The code is simpler without it.
+ * tmac/groff.man: Eliminate use of .eo/.ec.
+ (.REQ): Surround args 2 through N with quotes. This will enable us
+ not to rely on the shift request, which is nonportable.
+ (ExecFF): Remove. The code is simpler without it.
2007-02-18 Eric S. Raymond <address@hidden>
@@ -31,20 +26,18 @@
2007-02-15 Eric S. Raymond <address@hidden>
* contrib/groffer/perl/groffer.man, contrib/groffer/perl/groffer.man:
- Fix non-portable if expressions.
+ Fix non-portable `if' expressions.
2007-02-13 Eric S. Raymond <address@hidden>
- * contrib/groffer/perl/groffer.man, contrib/groffer/perl/groffer.man:
- Replace ShellCommand with .EX/.EE pairs. Don't use .TP for examples,
- as some viewers won't handle a display macro as a tag line. Use
- .SY/.OP/.YS rather than elaborate custom macros. This was the
- hard part, the rest will be cleanup.
+ Use an-ext.tmac macros in groffer.man.
- * contrib/groffer/perl/groffer.man, contrib/groffer/perl/groffer.man:
- Begin adapting this page to use an-ext.tmac macros. So far this
- is just changing .TP to .TQ, fixing .MTO and .URL uses,
- and removing some unused code. The hard part comes next.
+ * contrib/groffer/perl/groffer.man,
+ contrib/groffer/perl/groffer.man: Replace ShellCommand with .EX/.EE
+ pairs.
+ Don't use .TP for examples, as some viewers won't handle a display
+ macro as a tag line. Use .SY/.OP/.YS rather than elaborate custom
+ macros.
2007-02-12 Werner LEMBERG <address@hidden>
Index: tmac/groff_man.man
===================================================================
RCS file: /cvsroot/groff/groff/tmac/groff_man.man,v
retrieving revision 1.33
retrieving revision 1.34
diff -u -b -r1.33 -r1.34
--- tmac/groff_man.man 6 Feb 2007 09:27:19 -0000 1.33
+++ tmac/groff_man.man 20 Feb 2007 19:08:44 -0000 1.34
@@ -1,5 +1,5 @@
.ig
-Copyright (C) 1999-2000, 2001, 2002, 2003, 2004, 2005
+Copyright (C) 1999-2000, 2001, 2002, 2003, 2004, 2005, 2007
Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this
@@ -33,23 +33,18 @@
.
.SH SYNOPSIS
.
-.B groff
-.B \-man
-[
-.IR options .\|.\|.\&
-]
-[
-.IR files .\|.\|.\&
-]
-.br
-.B groff
-.B \-m\ man
-[
-.IR options .\|.\|.\&
-]
-[
-.IR files .\|.\|.\&
-]
+.SY "groff\ \-man"
+.RI [ options
+.IR .\|.\|.\& ]
+.RI [ files
+.IR .\|.\|.\& ]
+.
+.SY "groff\ \-m\ man"
+.RI [ options
+.IR .\|.\|.\& ]
+.RI [ files
+.IR .\|.\|.\& ]
+.YS
.
.
.\" -----------------------------------------------------------------
@@ -59,7 +54,7 @@
The
.B man
macros used to generate
-.I \%man\~pages
+.I man\~pages
with
.I groff
were written by James Clark.
@@ -79,7 +74,7 @@
.
.TP
.B \-rcR=1
-This option (the default if in nroff mode) will create a single, very
+This option (the default if in nroff mode) creates a single, very
long page instead of multiple pages.
.
Say
@@ -89,7 +84,7 @@
.TP
.B \-rC1
If more than one manual page is given on the command line, number the
-pages continuously, rather than starting each at\ 1.
+pages continuously, rather than starting each at\~1.
.
.TP
.B \-rD1
@@ -108,12 +103,12 @@
.BI \-rHY= flags
Set hyphenation flags.
.
-Possible values are 1\ to hyphenate without restrictions, 2\ to not
-hyphenate the last word on a page, 4\ to not hyphenate the last two
-characters of a word, and 8\ to not hyphenate the first two characters
+Possible values are 1\~to hyphenate without restrictions, 2\~to not
+hyphenate the last word on a page, 4\~to not hyphenate the last two
+characters of a word, and 8\~to not hyphenate the first two characters
of a word.
.
-These values are additive; the default is\ 14.
+These values are additive; the default is\~14.
.
.TP
.BI \-rIN= width
@@ -152,18 +147,18 @@
direct initialization of the `LL' register should
.I always
be preferred to the use of such a request.
-In particular, note that a `.ll\ 65n' request will
+In particular, note that a `.ll\ 65n' request does
.I not
preserve the normal
.I nroff
default line length,
(the
.B man
-default initialization to 78n will prevail),
+default initialization to 78n prevails),
whereas,
the `-rLL=65n' option, or an equivalent `.nr\ LL\ 65n'
request preceding the use of the `TH' macro,
-.I will
+.I does
set a line length of 65n.
.
.TP
@@ -175,9 +170,9 @@
.
.TP
.BI \-rP nnn
-Enumeration of pages will start with
+Enumeration of pages start with
.I nnn
-rather than with\ 1.
+rather than with\~1.
.
.TP
.BI \-rS xx
@@ -185,7 +180,7 @@
.I xx
points
.RI ( xx
-can be 10, 11, or\ 12) rather than 10\ points.
+can be 10, 11, or\~12) rather than 10\~points.
.
.TP
.BI \-rSN= width
@@ -195,7 +190,7 @@
.
.TP
.BI \-rX nnn
-After page\ \c
+After page\~\c
.IR nnn ,
number pages as
.IR nnn a,
@@ -203,7 +198,7 @@
.IR nnn c,
etc.
.
-For example, the option `\-rX2' will produce the following page
+For example, the option `\-rX2' produces the following page
numbers: 1, 2, 2a, 2b, 2c, etc.
.
.
@@ -216,19 +211,19 @@
For further customization, put additional macros and requests into the
file
.B man.local
-which will be loaded immediately after the
+which is loaded immediately after the
.B man
package.
.
.TP
-.BI .TH " title section \fB[\fPextra1\fB]\fP \fB[\fPextra2\fB]\fP
\fB[\fPextra3\fB]"
+.BI .TH " title section \fR[\fPextra1\fR]\fP \fR[\fPextra2\fR]\fP
\fR[\fPextra3\fR]"
Set the title of the
.I man\~page
to
.I title
and the section to
.IR section ,
-which must take on a value between 1 and\ 8.
+which must take on a value between 1 and\~8.
.
The value
.I section
@@ -244,9 +239,9 @@
in parentheses immediately appended to
.IR title .
.I extra1
-will be positioned in the middle of the footer line.
+is positioned in the middle of the footer line.
.I extra2
-will be positioned at the left in the footer line (or at the left on
+is positioned at the left in the footer line (or at the left on
even pages and at the right on odd pages if double-sided printing is
active).
.I extra3
@@ -256,7 +251,7 @@
For HTML output, headers and footers are completely suppressed.
.
.IP
-Additionally, this macro starts a new page; the new line number is\ 1
+Additionally, this macro starts a new page; the new line number is\~1
again (except if the `-rC1' option is given on the command line) --
this feature is intended only for formatting multiple
.IR \%man\~pages ;
@@ -267,7 +262,7 @@
macro at the beginning of the file.
.
.TP
-.BI ".SH [" "text for a heading" ]
+.BI .SH " \fR[\fPtext for a heading\fR]\fP"
Set up an unnumbered section heading sticking out to the left.
.
Prints out all the text following
@@ -284,7 +279,7 @@
text is reset to the default values.
.
.TP
-.BI ".SS [" "text for a heading" ]
+.BI .SS " \fR[\fPtext for a heading\fR]\fP"
Set up a secondary, unnumbered section heading.
.
Prints out all the text following
@@ -301,7 +296,7 @@
text is reset to the default values.
.
.TP
-.BI ".TP [" nnn ]
+.BI .TP " \fR[\fPnnn\fR]\fP"
Set up an indented paragraph with label.
.
The indentation is set to
@@ -329,8 +324,8 @@
paragraph begins on the line following the label, entirely indented.
.
Note that neither font shape nor font size of the label is set to a
-default value; on the other hand, the rest of the text will have
-default font settings.
+default value; on the other hand, the rest of the text has default
+font settings.
.
.IP
The
@@ -341,18 +336,25 @@
.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.
+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,
+troff.
+.
+To be certain your page will be portable to those systems,
copy its definition from the
-.B an-ext.tmac
+.B \%an-ext.tmac
file of a
.BR groff
installation.
+.
.TP
.B .LP
.TQ
@@ -372,7 +374,7 @@
Finally, the current left margin and the indentation are restored.
.
.TP
-.BI ".IP [" designator "] [" nnn ]
+.BI .IP " \fR[\fPdesignator\fR]\fP \fR[\fPnnn\fR]\fP"
Set up an indented paragraph, using
.I designator
as a tag to mark its beginning.
@@ -408,11 +410,13 @@
is one of the three macros used in the
.B man
package to format lists.
+.
.IP \(bu 4
.B HP
is another.
.
This macro produces a paragraph with a left hanging indentation.
+.
.IP \(bu 4
.B TP
is another.
@@ -422,7 +426,7 @@
.RE
.
.TP
-.BI ".HP [" nnn ]
+.BI .HP " \fR[\fPnnn\fR]\fP"
Set up a paragraph with hanging left indentation.
.
The indentation is set to
@@ -438,7 +442,7 @@
Font size and face are reset to its default values.
.
The following paragraph illustrates the effect of this macro with
-hanging indentation set to\ 4 (enclosed by
+hanging indentation set to\~4 (enclosed by
.B .RS
and
.B .RE
@@ -452,17 +456,21 @@
.
As you can see, it produces a paragraph where all lines but the first
are indented.
+.
.RE
.IP
-Use of this presentation-level macro is deprecated. While it is
-universally portable to legacy Unix systems, a hanging indent cannot
-be expressed naturally under HTML and many HTML-based manual viewers
-simply interpret it as a starter for a normal paragraph. Thus, any
-information or distinction you tried to express with the indentation
-may be lost.
+Use of this presentation-level macro is deprecated.
+.
+While it is universally portable to legacy Unix systems, a hanging
+indentation cannot be expressed naturally under HTML, and many
+HTML-based manual viewers simply interpret it as a starter for a
+normal paragraph.
+.
+Thus, any information or distinction you tried to express with the
+indentation may be lost.
.
.TP
-.BI ".RS [" nnn ]
+.BI .RS " \fR[\fPnnn\fR]\fP"
This macro moves the left margin to the right by the value
.I nnn
if specified (default unit is `n'); otherwise it is set to the
@@ -481,7 +489,7 @@
macro can be nested.
.
.TP
-.BI ".RE [" nnn ]
+.BI .RE " \fR[\fPnnn\fR]\fP"
This macro moves the left margin back to level
.IR nnn ,
restoring the previous left margin.
@@ -490,26 +498,34 @@
.
The first level (i.e., no call to
.B RS
-yet) has number\ 1, and each call to
+yet) has number\~1, and each call to
.B RS
-increases the level by\ 1.
+increases the level by\~1.
.
.TP
-.B EX
+.B .EX
.TQ
-.B EE
-Example/End Example. After
+.B .EE
+Example/End Example.
+.
+After
.BR EX ,
-filling is disabled and the font is set to constant-width. This is
-useful for formatting code, command, and configuration-file examples.
+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
+.
+.IP
These macros are defined on many (but not all) 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
+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.
@@ -534,7 +550,7 @@
.BR RE ,
.BR EX ,
and
-.BR EE
+.B EE
also cause a break but no insertion of vertical space.
.
.
@@ -542,15 +558,15 @@
.
.SH "MACROS TO SET FONTS"
.
-The standard font is Roman; the default text size is 10\ point.
+The standard font is Roman; the default text size is 10\~point.
.
.TP
-.BI ".SM [" text ]
+.BI .SM " \fR[\fPtext\fR]\fP"
Causes the text on the same line or the text on the next input line to
appear in a font that is one point size smaller than the default font.
.
.TP
-.BI ".SB [" text ]
+.BI .SB " \fR[\fPtext\fR]\fP"
Causes the text on the same line or the text on the next input line to
appear in boldface font, one point size smaller than the default font.
.
@@ -562,9 +578,11 @@
The text must be on the same line as the macro call.
.
Thus
+.
.RS
.IP
\&.BI this "word and" that
+.
.PP
would cause `this' and `that' to appear in bold face, while `word and'
appears in italics.
@@ -605,7 +623,7 @@
The text must be on the same line as the macro call.
.
.TP
-.BI ".B [" text ]
+.BI .B " \fR[\fPtext\fR]\fP"
Causes
.I text
to appear in bold face.
@@ -614,7 +632,7 @@
of the next input line appears in bold face.
.
.TP
-.BI ".I [" text ]
+.BI .I " \fR[\fPtext\fR]\fP"
Causes
.I text
to appear in italic.
@@ -626,155 +644,210 @@
.\" -----------------------------------------------------------------
.
.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
+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.
-
+.
+.PP
+Using these macros helps ensure that you get hyperlinks when your
+manual page is rendered in a browser or other program that is
+Web-enabled.
+.
.TP
-.B UR
+.BI .UR " URL"
.TQ
-.B UE
-Wrap a World Wide Web hyperlink. The argument to the
+.BI .UE " \fR[\fPpunctuation\fR]\fP"
+Wrap a World Wide Web hyperlink.
+.
+The argument to
.B UR
is the URL; thereafter, lines until
.B UE
-are collected and used as the link text. Any argument to the
+are collected and used as the link text.
+.
+Any argument to the
.B UE
macro is pasted to the end of the text.
-On a device that is not
-a browser,
-
+.
+On a device that is not a browser,
+.
+.RS
+.IP
.EX
this is a link to
-\&.UR http:\&//randomsite,org/fubar
+\&.UR http://\e:randomsite.org/\e: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".
-
+.RE
+.
+.IP
+usually displays like this: \[lq]this is a link to some random
+site <http://\:randomsite.org/\:fubar>, given as an example\[rq].
+.
+.IP
+The use of
+.B \e:
+to insert hyphenless breakpoints is a groff extension and can
+be omitted.
+.
.TP
-.B MT
+.BI .MT " address"
.TQ
-.B ME
-Wrap an email address. The argument of MT is the address; text
-following, until
+.BI .ME " \fR[\fPpunctuation\fR]\fP"
+Wrap an email address.
+.
+The argument of
+.B MT
+is the address; text following, until
.BR ME ,
-is a name to be associated with the address. Any argument to the
+is a name to be associated with the address.
+.
+Any argument to the
.B ME
-macro is pasted to the end of the link text. On a device that is not
-a browser,
-
+macro is pasted to the end of the link text.
+.
+On a device that is not a browser,
+.
+.RS
+.IP
.EX
contact
-\&.UR address@hidden,net
+\&.UR address@hidden:fubar.net
Fred Foonly
\&.UE
for more information
.EE
-
-will usually display like this: "contact Fred Foonly
-<address@hidden> for more information".
-
+.RE
+.
+.IP
+usually displays like this: \[lq]contact Fred Foonly
+<address@hidden:fubar.net> for more information\[rq].
+.
+.IP
+The use of
+.B \e:
+to insert hyphenless breakpoints is a groff extension and can
+be omitted.
+.
+.
.\" -----------------------------------------------------------------
.
.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
+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 browsers in recognizing
-command synopses and treating them differently from running text.
+.
+.PP
+These macros are a convenience for authors.
+They also assist automated translation tools and help browsers 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
+.BI .SY " command"
+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.
+is set with a hanging indentation with the width of
+.I command
+plus a space.
+.
+This produces the traditional look of a Unix command synopsis.
+.
+.TP
+.BI .OP " key value"
+Describe an optional command argument.
+.
+The arguments of this macro are set surrounded by option braces
+in the default Roman font; the first argument is printed with
+a bold face, while the second argument is typeset as italic.
+.
.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
+.B .YS
+This macro restores normal indentation at the end of a command
+synopsis.
+.
+.PP
Here is a real example:
-
+.
+.IP
.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
+\&.OP \e-abcegiklpstzCEGNRSUVXZ
+\&.OP \e-d cs
+\&.OP \e-f fam
+\&.OP \e-F dir
+\&.OP \e-I dir
+\&.OP \e-K arg
+\&.OP \e-L arg
+\&.OP \e-m name
+\&.OP \e-M dir
+\&.OP \e-n num
+\&.OP \e-o list
+\&.OP \e-P arg
+\&.OP \e-r cn
+\&.OP \e-T dev
+\&.OP \e-w name
+\&.OP \e-W name
\&.RI [ file
-\&.IR ... ]
+\&.IR .\e|.\e|. ]
\&.YS
.EE
-
+.
+.PP
produces the following output:
-
+.
+.RS
+.PP
.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
+.OP \-abcegiklpstzCEGNRSUVXZ
+.OP \-d cs
+.OP \-f fam
+.OP \-F dir
+.OP \-I dir
+.OP \-K arg
+.OP \-L arg
+.OP \-m name
+.OP \-M dir
+.OP \-n num
+.OP \-o list
+.OP \-P arg
+.OP \-r cn
+.OP \-T dev
+.OP \-w name
+.OP \-W name
.RI [ file
-.IR ... ]
+.IR .\|.\|. ]
.YS
-
-Note the use of
+.RE
+.
+.PP
+If necessary, you might use
.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.
+requests to control line breaking.
+.
+You can insert plain text as well; this looks like the traditional
+(unornamented) syntax for a required command argument or filename.
+.
.
.\" -----------------------------------------------------------------
.
@@ -787,29 +860,35 @@
.
.TP
.B .DT
-Set tabs every 0.5 inches.
+Set tabs every 0.5\~inches.
.
Since this macro is always called during a
.B TH
request, it makes sense to call it only if the tab positions have been
changed.
-.sp
-Use of this presentation-level macro is deprecated. It translates
-poorly to HTML, under which exact whitespace control and tabbing are not
-readily available. Thus, information or distinctions that you use
+.
+.IP
+Use of this presentation-level macro is deprecated.
+.
+It translates poorly to HTML, under which exact whitespace control
+and tabbing are not readily available.
+.
+Thus, information or distinctions that you use
.B DT
-to express are likely to be lost. If you feel tempted to use it,
-you should probably be composing a table using
-.BR tbl (1)
+to express are likely to be lost.
+.
+If you feel tempted to use it, you should probably be composing a
+table using
+.BR @address@hidden (@MAN1DIR@)
markup instead.
.
.TP
-.BI ".PD [" nnn ]
+.BI .PD " \fR[\fPnnn\fR]\fP"
Adjust the empty space before a new paragraph or section.
.
The optional argument gives the amount of space (default unit is `v');
-without parameter, the value is reset to its default value (1\ line in
-nroff mode, 0.4v\ otherwise).
+without parameter, the value is reset to its default value (1\~line in
+nroff mode, 0.4v\~otherwise).
.
This affects the macros
.BR SH ,
@@ -823,15 +902,19 @@
.BR IP ,
and
.BR HP .
-.sp
-Use of this presentation-level macro is deprecated. It translates
-poorly to HTML, under which exact control of inter-paragraph spacing
-is not readily available. Thus, information or distinctions that you use
+.
+.IP
+Use of this presentation-level macro is deprecated.
+.
+It translates poorly to HTML, under which exact control of
+inter-paragraph spacing is not readily available.
+.
+Thus, information or distinctions that you use
.B PD
to express are likely to be lost.
.
.TP
-.BI ".AT [" system " [" release ]]
+.BI .AT " \fR[\fPsystem \fR[\fPrelease\fR]]\fP"
Alter the footer for use with \f[CR]AT&T\f[]
.IR \%man\~pages .
This command exists only for compatibility; don't use it.
@@ -841,9 +924,9 @@
info manual for more.
.
.TP
-.BI ".UC [" version ]
+.BI .UC " \fR[\fPversion\fR]\fP"
Alter the footer for use with \f[CR]BSD\f[]
-.IR \%man\~pages .
+.IR man\~pages .
This command exists only for compatibility; don't use it.
.
See the
@@ -851,19 +934,20 @@
info manual for more.
.
.TP
-.B ".PT"
+.B .PT
Print the header string.
.
Redefine this macro to get control of the header.
.
.TP
-.B ".BT"
+.B .BT
Print the footer string.
.
Redefine this macro to get control of the footer.
.
.PP
The following strings are defined:
+.
.TP
.B \e*S
Switch back to the default font size.
@@ -898,10 +982,12 @@
is needed, it has become usage to make the first line of the
.I \%man\~page
look like this:
+.
.PP
.RS
.BI '\e"\ word
.RE
+.
.PP
Note the single space character after the double quote.
.I word
@@ -929,46 +1015,57 @@
.B man
macros with individual
.I groff
-requests where necessary. See the
+requests where necessary.
+.
+See the
.I groff
info pages for a complete reference of all requests.
-.LP
-Note, however, that using raw troff requests is likely to make your page
-render poorly on the (increasingly common) class of viewers that
-render it to HTML. Troff requests make implicit assumptions about
-things like character and page sizes that may break in an HTML
-environment; also, many of these viewers don't interpret the full
-troff vocabulary, a problem which can lead to portions of your
-text being silently dropped.
-.LP
+.
+.PP
+Note, however, that using raw troff requests is likely to make your
+page render poorly on the (increasingly common) class of viewers that
+render it to HTML.
+.
+Troff requests make implicit assumptions about things like character
+and page sizes that may break in an HTML environment; also, many of
+these viewers don't interpret the full troff vocabulary, a problem
+which can lead to portions of your text being silently dropped.
+.
+.PP
For portability to modern viewers, it is best to write your page
-entirely in the requests described on this page. Further, it is best
-to completely avoid those we have described as 'presentation-level'
+entirely in the requests described on this page.
+.
+Further, it is best to completely avoid those we have described as
+`presentation-level'
.RB ( HP ,
.BR PD ,
and
.BR DT ).
-.LP
+.
+.PP
The macros we have described as extensions
-.RB ( EX/EE ,
-.BR SY/OP/YS ,
-.BR UR/UE ,
+.RB ( .EX / .EE ,
+.BR .SY / .OP / .YS ,
+.BR .UR / .UE ,
and
-.BR MT/ME )
+.BR .MT / .ME )
should be used with caution, as they may not yet be built in to
-some viewer that is important to your audience. If in doubt, copy
-the implementation onto your page.
+some viewer that is important to your audience.
+.
+If in doubt, copy the implementation onto your page.
+.
.
-
.\" -----------------------------------------------------------------
.
.SH FILES
+.
.TP
.B man.tmac
.TQ
.B an.tmac
These are wrapper files to call
.BR andoc.tmac .
+.
.TP
.B andoc.tmac
This file checks whether the
@@ -976,27 +1073,32 @@
macros or the
.B mdoc
package should be used.
+.
.TP
.B an-old.tmac
Most
.B man
macros are contained in this file.
+.
.TP
.B an-ext.tmac
-The extension macro definitions forx
-.BR \&.SY ,
-.BR \&.OP ,
+The extension macro definitions for
+.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
+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.
@@ -1023,10 +1125,12 @@
.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
Index: tmac/groff_trace.man
===================================================================
RCS file: /cvsroot/groff/groff/tmac/groff_trace.man,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -b -r1.6 -r1.7
--- tmac/groff_trace.man 6 Feb 2007 09:27:41 -0000 1.6
+++ tmac/groff_trace.man 20 Feb 2007 19:08:44 -0000 1.7
@@ -3,12 +3,12 @@
File position: <groff-source>/tmac/groff_trace.man
-Last update: 23 Oct 2006
+Last update: 20 Feb 2007
This file is part of groff, the GNU roff type-setting system.
-Copyright (C) 2002, 2006 Free Software Foundation, Inc.
-written by Bernd Warken <address@hidden>
+Copyright (C) 2002, 2006, 2007 Free Software Foundation, Inc.
+written by Bernd Warken.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
@@ -19,20 +19,24 @@
A copy of the Free Documentation License is included as a file called
FDL in the main directory of the groff source package.
..
+.
.ds Ellipsis .\|.\|.\&\"
.
.TH GROFF_TRACE @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
+.
.SH NAME
groff_trace \- groff macro package trace.tmac
+.
.\" --------------------------------------------------------------------
.\" SH SYNOPSIS
.\" --------------------------------------------------------------------
.SH SYNOPSIS
.
-.SY groff
-.B -m trace
-.OP options\*[Ellipsis]
-.OP files\*[Ellipsis]
+.SY "groff \-m trace"
+.RI [ options
+.IR \*[Ellipsis] ]
+.RI [ files
+.IR \*[Ellipsis] ]
.YS
.
.\" --------------------------------------------------------------------
@@ -55,21 +59,21 @@
.P
This tracing process is activated by specifying the groff or troff
command line option
-.BR "-m\~trace" .
+.BR \-m\ trace .
This works also with the
.BR groffer (@MAN1EXT@)
viewer program.
.
A finer control can be obtained by including the macro file within the
document by the groff macro call
-.BR ".mso\~trace.tmac" .
+.BR .mso\ trace.tmac .
Only macros that are defined after this line are traced.
.
.
.P
If some other macro package should be traced as well it must be specified
after
-.BR "-m\~trace"
+.B \-m\ trace
on the command line.
.
.
@@ -87,7 +91,6 @@
.SH EXAMPLES
.\" --------------------------------------------------------------------
.
-.P
In the following examples, a roff fragment is fed into groff via
standard input.
.
@@ -101,7 +104,10 @@
.
.\" --------------------------------------------------------------------
.SS "Command line option"
+Example:
.
+.RS
+.P
.EX
\fIsh#\fP echo '.
> .de test_macro
@@ -115,6 +121,7 @@
*** de trace enter: test_macro "some" "dummy" "arguments"
*** trace exit: test_macro "some" "dummy" "arguments"
.EE
+.RE
.
.P
The entry and the exit of each macro call is displayed on the terminal
@@ -123,7 +130,10 @@
.
.\" --------------------------------------------------------------------
.SS "Nested macro calls"
+Example:
.
+.RS
+.P
.EX
\fIsh#\fP echo '.
> .de child
@@ -139,6 +149,7 @@
*** trace exit: child
*** trace exit: parent
.EE
+.RE
.
.P
This shows that macro calls can be nested.
@@ -148,7 +159,10 @@
.
.\" --------------------------------------------------------------------
.SS "Activating with .mso"
+Example:
.
+.RS
+.P
.EX
\fIsh#\fP echo '.
> .de before
@@ -164,6 +178,7 @@
*** de trace enter: after
*** trace exit: after
.EE
+.RE
.
.P
Here, the tracing is activated within the document, not by a command
@@ -191,7 +206,7 @@
to prevent too early expansion of the backslash. For example, this
macro call
.
-.P
+.IP
.EX
\&.foo \e\e\e\en[bar]
.EE
@@ -207,7 +222,7 @@
escape which is an escape character not interpreted in copy mode, for
example
.
-.P
+.IP
.EX
\&.foo \eEn[bar]
.EE
@@ -244,7 +259,7 @@
.SH AUTHOR
.\" --------------------------------------------------------------------
.
-Copyright (C) 2002 Free Software Foundation, Inc.
+Copyright (C) 2002, 2006, 2007 Free Software Foundation, Inc.
.
.P
This document is distributed under the terms of the FDL (GNU Free
@@ -261,10 +276,7 @@
.IR groff ,
the GNU roff distribution.
.
-It was written by
-.MT address@hidden
-Bernd Warken
-.ME .
+It was written by Bernd Warken.
.
.
.\" --------------------------------------------------------------------
@@ -275,28 +287,23 @@
.BR groff (@MAN1EXT@)
An overview of the groff system.
.
-.
.TP
.BR troff (@MAN1EXT@)
For details on option
-.BR -m .
-.
+.BR \-m .
.
.TP
.BR groffer (@MAN1EXT@)
A viewer program for all kinds of roff documents.
.
-.
.TP
.BR groff_tmac (@MAN5EXT@)
A general description of groff macro packages.
.
-.
.TP
.BR groff (@MAN7EXT@)
A short reference for the groff formatting language.
.
-.
.P
A complete reference for all parts of the groff system is found in the
groff
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Groff-commit] groff ChangeLog tmac/groff_man.man tmac/groff_t...,
Werner LEMBERG <=