From 22f7ce37467303547cdd37259f0f4f5735ae98c6 Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Thu, 4 May 2023 06:59:33 -0500 Subject: [docs]: Fix content and style nits. * Recast description of `bd`, `backtrace`, and `lf` requests. * Explicitly associate `bd` request with `.b` register. * Introduce metasyntactic variable `message` for use with `ab` and `tm`-family requests, since it is interpreted differenly from the `contents` argument of string assignment and appendment requests. Document that special character escape sequences in a `message` are not interpreted. * Clarify that groff_diff(7) details only GNU troff extensions. * Set default argument assumed by `af` request in bold. * Document behavior of `ce` and `rj` requests when used with negative agument. * Fully discuss `ce`, `cf`, and `trf`'s interfaces before presenting examples. * Use "file" instead of "filename" as metasyntactic variable name with requests. --- man/groff.7.man | 140 +++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 94 insertions(+), 46 deletions(-) (limited to 'man') diff --git a/man/groff.7.man b/man/groff.7.man index a13b546a2..19951296c 100644 --- a/man/groff.7.man +++ b/man/groff.7.man @@ -2240,6 +2240,14 @@ Escape sequences may generally be used freely in except when it is read in copy mode. . .TPx +.I message +is a character sequence to be emitted on the standard error stream. +. +Special character escape sequences are +.I not +interpreted. +. +.TPx .I n is a numeric expression. . @@ -2317,7 +2325,9 @@ Not all details of request behavior are outlined here. . See the .I groff -Texinfo manual or +Texinfo manual or, +for features new to GNU +.IR troff , \" GNU .MR groff_diff @MAN7EXT@ . . . @@ -2377,8 +2387,8 @@ indicate Roman numerals and basic Latin alphabetics, respectively, in the lettercase specified. . -The default is \[lq]0\[rq]. -. +The default is +.BR 0 . . .TPx .REQ .aln "new old" @@ -2490,28 +2500,49 @@ Unformat ASCII characters, spaces, and some escape sequences in . .TPx .REQ .backtrace -Write a backtrace of the input stack to the standard error stream. +Write the state of the input stack to the standard error stream. . -Also see the +See the .B \-b option of .MR groff @MAN1EXT@ . . .TPx +.REQ .bd font +Stop emboldening font +.I font. +. +.TPx .REQ .bd "font N" Embolden .I font -by +by overstriking its glyphs offset by .IR N \-1 units. . +See +.register .b . +. .TPx -.REQ .bd "S font N" -Embolden Special Font -.I S -when current font is -.IR font . +.REQ .bd "special-font font" +Stop emboldening +.I special-font +when +.I font +is selected. +. +.TPx +.REQ .bd "special-font font N" +Embolden +.I special-font, +overstriking its glyphs offset by +.IR N \-1 +units when +.I font +is selected. . +See +.register .b . . .TPx .REQ .blm @@ -2612,14 +2643,15 @@ productive input lines without filling, then break again. . If -.IR npl =0, +.I npl +\[<=] 0, stop centering. . .TPx -.REQ .cf "filename" -Copy contents of file -.I filename -unprocessed to stdout or to the diversion. +.REQ .cf file +Copy contents of +.I file +without formatting to the (top-level) diversion. . .TPx .REQ .cflags "n c1 c2 \fR\&.\|.\|.\&\fP" @@ -3659,23 +3691,24 @@ See Immediately jump to end of current file. . .TPx -.REQ .nx "filename" -Immediately continue processing with file -.IR file . +.REQ .nx file +Stop formatting current file and begin reading +.I file. . .TPx -.REQ .open "stream filename" +.REQ .open "stream file" Open -.I filename +.I file for writing and associate the stream named .I stream with it. . .TPx -.REQ .opena "stream filename" -Like -.request .open -but append to it. +.REQ .opena "stream file" +As +.request .open , +but append to +.I file. . .TPx .REQ .os @@ -3779,9 +3812,16 @@ also see .esc[] s \[+-]N . . .TPx -.REQ .psbb "filename" -Get the bounding box of a PostScript image -.IR filename . +.REQ .psbb file +Retrieve the bounding box of the PostScript image found in +.I file, +which must conform to Adobe's Document Structuring Conventions (DSC). +. +See registers +.BR llx , +.BR lly , +.BR urx , +.BR ury . . .TPx .REQ .pso "command" @@ -3857,7 +3897,8 @@ productive input lines without filling, then break again. . If -.IR npl =0, +.I npl +\[<=] 0, stop right-aligning. . .TPx @@ -4183,25 +4224,26 @@ Enable track kerning for Three-part title. . .TPx -.REQ .tm contents -Print -.I contents -on stderr. +.REQ .tm message +Write +.I message, +followed by a newline, +to the standard error stream. . .TPx -.REQ .tm1 contents -Print -.I anything -on stderr, +.REQ .tm1 message +As +.request .tm , but an initial neutral double quote in -.I contents -is stripped off to allow embedding of leading spaces. +.I message +is removed, +allowing it to contain leading spaces. . .TPx -.REQ .tmc contents -Similar to -.request .tm1 -without emitting a final newline. +.REQ .tmc message +As +.request .tm1 , +without emitting a newline. . .TPx .REQ .tr "abcd\fR\&.\|.\|.\&\fP" @@ -4215,9 +4257,15 @@ to etc.\& on output. . .TPx -.REQ .trf "filename" -Transparently output the contents of file -.IR filename . +.REQ .trf file +Transparently output the contents of +.I file. +. +Unlike +.request .cf , +invalid input characters in +.I file +are rejected. . .TPx .REQ .trin "abcd\fR\&.\|.\|.\&\fP" -- cgit v1.2.1