diff options
| -rw-r--r-- | ChangeLog | 14 | ||||
| -rw-r--r-- | Makefile.comm | 22 | ||||
| -rw-r--r-- | tmac/doc-common | 2 | ||||
| -rw-r--r-- | tmac/doc.tmac | 33 | ||||
| -rw-r--r-- | tmac/dvi.tmac | 1 | ||||
| -rw-r--r-- | tmac/groff_mdoc.man | 90 |
6 files changed, 109 insertions, 53 deletions
@@ -1,3 +1,17 @@ +2002-03-23 Phil Lobbes <phil@perkpartners.com> + + * Makefile.comm (.y.o): New rule for make on Solaris 2.5.1 -- the + internal .y.o rule took precendence over the .y.cc rule, compiling + the yacc files with gcc instead of g++. + +2002-03-23 Werner LEMBERG <wl@gnu.org> + + * tmac/dvi.tmac: Add replacement font for `CB'. + + * tmac/doc.tmac: s/request/macro/ in messages. + (doc-generic-macro): Improve error message. + * tmac/groff_mdoc.man: Minor improvements. + 2002-03-22 Werner LEMBERG <wl@gnu.org> * doc/groff.texinfo: Document possible conflict between `tr' and diff --git a/Makefile.comm b/Makefile.comm index 66c4b78d..291a94e3 100644 --- a/Makefile.comm +++ b/Makefile.comm @@ -112,6 +112,28 @@ extraclean: fi; \ fi +# The next rule is needed for make of Solaris 2.5.1 to override its +# built-in .y.o rule (which takes precedence over the .y.cc rule above). +.y.o: + if test -n "$(YTABH)"; then \ + $(YACC) $(YACCFLAGS) -d $<; \ + else \ + $(YACC) $(YACCFLAGS) $<; \ + fi + -test -f y.tab.h && mv y.tab.h y_tab.h + -test -f y.tab.c && mv y.tab.c y_tab.c + mv y_tab.c $(YTABC) +# Avoid ending up with two versions of $(YTABH). + if test -n "$(YTABH)"; then \ + if test -f $(srcdir)/$(YTABH); then \ + rm -f $(YTABH); \ + mv y_tab.h $(srcdir)/$(YTABH); \ + else \ + mv y_tab.h $(YTABH); \ + fi; \ + fi + $(COMPILE.cc) -o $@ $(YTABC) + version=`cat $(top_srcdir)/VERSION` # No additional number for the groff archive if revision is zero revision=`sed -e 's/^0$$//' -e 's/^[1-9].*$$/.&/' $(top_srcdir)/REVISION` diff --git a/tmac/doc-common b/tmac/doc-common index 3c588400..00fae8eb 100644 --- a/tmac/doc-common +++ b/tmac/doc-common @@ -151,7 +151,7 @@ .nr Xr 10n . . -.\" requests which must be processed after the closing delimiter of `Op' +.\" macros which must be processed after the closing delimiter of `Op' .\" and friends .ds doc-after-Ao .ds doc-after-Bo diff --git a/tmac/doc.tmac b/tmac/doc.tmac index 1fb07f33..3b640e75 100644 --- a/tmac/doc.tmac +++ b/tmac/doc.tmac @@ -547,7 +547,8 @@ . nr doc-arg-ptr +1 . ie (\n[doc-arg-limit] >= \n[doc-arg-ptr]) \{\ . if (\n[doc-type\n[doc-arg-ptr]] == 1) \{\ -. tm Usage: .\$0 \*[doc-\$0-usage] ... (#\n[.c]) +. tmc mdoc warning: Using a macro as first argument +. tm1 " cancels effect of .\$0 (#\n[.c]) . . \" the right action here would be to reset the argument counters . \" and bail out -- unfortunately, a small number of manual pages @@ -1939,7 +1940,7 @@ . doc-print-and-reset . \} . -. \" shall we finish .It request? +. \" shall we finish .It macro? . if !"\*[doc-macro-name]"It" \ . if \n[doc-in-list] \ . if !\n[doc-nesting-level] \ @@ -2025,7 +2026,7 @@ . .de Ap . ie !\n[doc-arg-limit] \ -. tm Usage: `Ap' cannot be first request on a line (no `.Ap') (#\n[.c]) +. tm Usage: `Ap' cannot be first macro on a line (no `.Ap') (#\n[.c]) . el \{\ . nop \)'\)\c . nr doc-arg-ptr +1 @@ -2378,7 +2379,7 @@ . . .\" NS doc-fontmode-font-stackXXX global register -.\" NS stack of saved current font values from `Bf' request +.\" NS stack of saved current font values from `Bf' macro .\" NS .\" NS limit: .\" NS doc-fontmode-depth @@ -2387,7 +2388,7 @@ . . .\" NS doc-fontmode-size-stackXXX global register -.\" NS stack of saved current size values from `Bf' request +.\" NS stack of saved current size values from `Bf' macro .\" NS .\" NS limit: .\" NS doc-fontmode-depth @@ -2429,7 +2430,7 @@ . el \{ .ie "\$1"-symbolic" \ . nop \*[doc-Sy-font]\c . el \{\ -. tmc mdoc warning: Unknown keyword `\$1' in .Bf request +. tmc mdoc warning: Unknown keyword `\$1' in .Bf macro . tm1 " (#\n[.c]) . \}\}\}\}\}\}\} . el \ @@ -2497,7 +2498,7 @@ . doc-set-hard-space . \} . el \{\ -. tm mdoc warning: Unknown keyword `\$1' in .Bk request (#\n[.c]) +. tm mdoc warning: Unknown keyword `\$1' in .Bk macro (#\n[.c]) . nr doc-keep-type 3 . \}\}\} . @@ -2678,7 +2679,7 @@ . \} . el \{\ . tm1 "mdoc warning: Unknown keyword `\$1' (or missing display type) -. tm1 " in .Bd request (#\n[.c]) +. tm1 " in .Bd macro (#\n[.c]) . nr doc-reg-Bd 0 . \}\}\}\}\} . @@ -2806,7 +2807,7 @@ . tm mdoc warning: .Bd `-file' keyword requires argument (#\n[.c]) . \} . el \ -. tm mdoc warning: Unknown keyword `\$1' in .Bd request (#\n[.c]) +. tm mdoc warning: Unknown keyword `\$1' in .Bd macro (#\n[.c]) . \}\} . . if (\n[doc-reg-ddBa] < \n[.$]) \{\ @@ -2963,7 +2964,7 @@ . \} . el \{\ . tm1 "mdoc warning: Unknown list type `\$1' (or missing list type) -. tm1 " in .Bl request +. tm1 " in .Bl macro . tm . nr doc-arg-ptr 0 . \}\}\}\}\}\}\}\}\}\}\} @@ -3073,7 +3074,7 @@ . nr doc-list-indent-stack\n[doc-list-depth] +\n[doc-reg-dBla1]n . \} . el \ -. tm mdoc warning: `-nested' allowed with nested .Bl requests only (#\n[.c]) +. tm mdoc warning: `-nested' allowed with nested .Bl macros only (#\n[.c]) . \} . . el \{ .ie "\*[doc-arg\n[doc-arg-ptr]]"-width" \{\ @@ -3245,7 +3246,7 @@ . \} . el \{\ . tmc mdoc warning: Unknown keyword `\*[doc-arg\n[doc-arg-ptr]]' -. tm1 " in .Bl request (#\n[.c]) +. tm1 " in .Bl macro (#\n[.c]) . \}\} . . if (\n[doc-arg-limit] > \n[doc-arg-ptr]) \ @@ -3669,7 +3670,7 @@ . . ie (\n[doc-reg-It] == 1) \{\ . if \n[.$] \{\ -. tm1 "mdoc warning: .It requests in lists of type `\*[doc-str-It]' +. tm1 "mdoc warning: .It macros in lists of type `\*[doc-str-It]' . tm1 " don't take arguments (#\n[.c]) . \}\} . el \{\ @@ -3696,13 +3697,13 @@ . doc-print-recursive . \}\}\} . el \{\ -. tm1 "mdoc warning: .It requests in lists of type `\*[doc-str-It]' +. tm1 "mdoc warning: .It macros in lists of type `\*[doc-str-It]' . tm1 " require arguments (#\n[.c]) . \} . \} . . \" the previous call of `.doc-print-recursive' can contain calls to -. \" opening requests like `.Ao'; we then defer the call of `doc-xxx-list' +. \" opening macros like `.Ao'; we then defer the call of `doc-xxx-list' . if !\n[doc-nesting-level] \ . doc-\*[doc-str-It] .. @@ -5037,7 +5038,7 @@ . . .\" Very crude references: Stash all reference info into boxes, print out -.\" reference on .Re request and clean up. Ordering very limited, no fancy +.\" reference on .Re macro and clean up. Ordering very limited, no fancy .\" citations, but can do articles, journals, and books -- need to add .\" several missing options (like city etc). Should be able to grab a refer .\" entry, massage it a wee bit (prefix a `.' to the %[A-Z]) and not worry diff --git a/tmac/dvi.tmac b/tmac/dvi.tmac index 1ed45706..39e2d7d0 100644 --- a/tmac/dvi.tmac +++ b/tmac/dvi.tmac @@ -7,6 +7,7 @@ .ftr C CW .ftr CO CWI .ftr CI CWI +.ftr CB CW .ftr TT CW .ftr H HR . diff --git a/tmac/groff_mdoc.man b/tmac/groff_mdoc.man index c13ad1f7..7fab34fe 100644 --- a/tmac/groff_mdoc.man +++ b/tmac/groff_mdoc.man @@ -102,7 +102,7 @@ options, function names, function parameters, pathnames, variables, cross references to other manual pages, and so on. These domain items have value for both the author and the future user of the manual page. -It is hoped the consistency gained across the manual set will provide easier +Hopefully, the consistency gained across the manual set will provide easier translation to future documentation tools. .Pp Throughout the @@ -245,7 +245,7 @@ as follows: The .Nm \-mdoc package attempts to simplify the process of writing a man page. -Theoretically, one should not have to learn the dirty details of +Theoretically, one should not have to learn the tricky details of .Tn GNU .Xr troff 1 to use @@ -265,10 +265,10 @@ a macro is called by placing a .Ql .\& (dot character) at the beginning of a line followed by the two-character (or three-character) name for the macro. -There can be space characters between the dot and the macro name (but +There can be space or tab characters between the dot and the macro name. +Arguments may follow the macro separated by spaces (but .Em no tabs). -Arguments may follow the macro separated by spaces (again, no tabs). It is the dot character at the beginning of the line which causes .Tn GNU .Xr troff 1 @@ -281,11 +281,8 @@ a macro invocation, precede the .Ql .\& (dot) with the .Ql \e& -escape sequence. -The -.Ql \e& -translates literally to a zero-width space, and is never displayed in -the output. +escape sequence which translates literally to a zero-width space, and is +never displayed in the output. .Pp In general, .Tn GNU @@ -307,14 +304,13 @@ argument lists are .Em parsed for callable macro names. This means an argument on the argument list which matches a general text or -manual domain macro name and is determined to be callable will be executed -or called when it is processed. +manual domain macro name (and which is defined to be callable) will be +executed or called when it is processed. In this case the argument, although the name of a macro, is not preceded by a .Ql .\& (dot). -It is in this manner that many macros are nested; for example the -option macro, +This makes it possible to nest macros; for example the option macro, .Ql .Op , may .Em call @@ -361,15 +357,22 @@ are parsed, but as it was cumbersome to constantly refer to macros as being callable and being able to call other macros, the term parsed has been used. . +.Pp +In the following, we call an +.Nm \-mdoc +macro which starts a line (with a leading dot) a +.Em command +if this distinction is necessary. +. .Ss "Passing Space Characters in an Argument" . Sometimes it is desirable to give as an argument a string containing one or -more blank space characters. -This may be necessary to specify arguments to macros which expect particular -arrangement of items in the argument list. Additionally, it makes +more blank space characters, say, to specify arguments to commands which +expect particular arrangement of items in the argument list. +Additionally, it makes .Nm \-mdoc working faster. -For example, the function macro +For example, the function command .Ql .Fn expects the first argument to be the name of a function and any remaining arguments to be function parameters. @@ -438,7 +441,7 @@ It is a wise preventive measure to globally remove all blank spaces from .Ao blank-space Ac Ns Ao end-of-line Ac character sequences. -Should the need arise to force a blank character at the end of a line, it +Should the need arise to use a blank character at the end of a line, it may be forced with an unpaddable space and the .Ql \e& escape character. @@ -559,33 +562,33 @@ extension); the rest of such a line is ignored. The body of a man page is easily constructed from a basic template: . .Bd -literal -offset indent -\&.\e" The following requests are required for all man pages. +\&.\e" The following commands are required for all man pages. \&.Dd Month day, year \&.Os [OPERATING_SYSTEM] [version/release] \&.Dt DOCUMENT_TITLE [section number] [architecture/volume] \&.Sh NAME \&.Nm name \&.Nd one line description of name -\&.\e" This next request is for sections 2 and 3 only. +\&.\e" This next command is for sections 2 and 3 only. \&.\e" .Sh LIBRARY \&.Sh SYNOPSIS \&.Sh DESCRIPTION -\&.\e" The following requests should be uncommented and +\&.\e" The following commands should be uncommented and \&.\e" used where appropriate. \&.\e" .Sh IMPLEMENTATION NOTES -\&.\e" This next request is for sections 2, 3 and 9 function +\&.\e" This next command is for sections 2, 3 and 9 function \&.\e" return values only. \&.\e" .Sh RETURN VALUES -\&.\e" This next request is for sections 1, 6, 7 and 8 only. +\&.\e" This next command is for sections 1, 6, 7 and 8 only. \&.\e" .Sh ENVIRONMENT \&.\e" .Sh FILES \&.\e" .Sh EXAMPLES -\&.\e" This next request is for sections 1, 6, 7, 8 and 9 only +\&.\e" This next command is for sections 1, 6, 7, 8 and 9 only \&.\e" (command return values (to shell) and \&.\e" fprintf/stderr type diagnostics). \&.\e" .Sh DIAGNOSTICS \&.\e" .Sh COMPATIBILITY -\&.\e" This next request is for sections 2, 3 and 9 error +\&.\e" This next command is for sections 2, 3 and 9 error \&.\e" and signal handling only. \&.\e" .Sh ERRORS \&.\e" .Sh SEE ALSO @@ -596,7 +599,7 @@ The body of a man page is easily constructed from a basic template: .Ed .Pp . -The first items in the template are the macros +The first items in the template are the commands .Ql .Dd , .Ql .Os , and @@ -605,7 +608,7 @@ the document date, the operating system the man page or subject source is developed or modified for, and the man page title (in .Em upper case ) along with the section of the manual the page belongs in. -These macros identify the page and are discussed below in +These commands identify the page and are discussed below in .Sx TITLE MACROS . .Pp The remaining items in the template are section headers @@ -653,6 +656,21 @@ Example: .Pp Except stated explicitly, all macros are parsed and callable. .Pp +Note that a macro takes effect up to the next nested macro. +For example, +.Ql ".Ic foo Aq bar" +doesn't produce +.Sq Ic "foo <bar>" +but +.Sq Ic foo Aq bar . +Consequently, a warning message is emitted for most commands if the first +argument is a macro itself since it cancels the effect of the calling +command completely. +Another consequence is that quoting macros never insert literal quotes; +.Sq Ic "foo <bar>" +has been produced by +.Ql ".Ic \*[q]foo <bar>\*[q]" . +.Pp Most macros have a default width value which can be used to specify a label width .Pf ( Fl width ) @@ -898,7 +916,7 @@ Slightly different variations of this language are used to describe the three different aspects of writing a man page. First, there is the description of .Nm \-mdoc -macro request usage. +macro command usage. Second is the description of a .Ux command @@ -918,7 +936,7 @@ command is: .Pp . .Ql .Xx -is a macro command or request, and anything following it are arguments to +is a macro command, and anything following it are arguments to be processed. In the second case, the description of a .Ux @@ -1053,7 +1071,7 @@ impose an order on their argument lists. All content macros are capable of recognizing and properly handling punctuation, provided each punctuation character is separated by a leading space. -If a request is given: +If a command is given: .Pp .Dl \&.Ar sptr, ptr), .Pp @@ -1147,7 +1165,7 @@ In the .Sx AUTHORS section, the .Ql .An -request causes a line break allowing each new name to appear on its own +command causes a line break allowing each new name to appear on its own line. If this is not desirable, . @@ -1211,7 +1229,7 @@ In the .Sx SYNOPSIS section a .Ql .Cd -request causes a line break before and after its arguments are printed. +command causes a line break before and after its arguments are printed. .Pp . The default width is 12n. @@ -1359,7 +1377,7 @@ In the .Sx SYNOPSIS section a .Ql .Fd -request causes a line break if a function has already been presented and a +command causes a line break if a function has already been presented and a break has not occurred. This leaves a nice vertical space in between the previous function call and the declaration for the next function. @@ -2047,7 +2065,7 @@ For possible values of .Ao version Ac see the description of the .Ql .Os -request above in section +command above in section .Sx "TITLE MACROS" . . .Ss "FreeBSD Macro" @@ -2066,7 +2084,7 @@ For possible values of .Ao version Ac see the description of the .Ql .Os -request above in section +command above in section .Sx "TITLE MACROS" . . .Ss "OpenBSD Macro" @@ -2337,7 +2355,7 @@ Note: The macro always invokes the .Ql .No macro after eliminating the space unless another macro name follows it. -If used as a request (i.e., the second form above in the +If used as a command (i.e., the second form above in the .Sq Usage line), .Ql .Ns |