groff-commit
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[groff] 06/11: doc/groff.texi: Revise presentation of `mc`.


From: G. Branden Robinson
Subject: [groff] 06/11: doc/groff.texi: Revise presentation of `mc`.
Date: Tue, 23 May 2023 16:25:35 -0400 (EDT)

gbranden pushed a commit to branch master
in repository groff.

commit 5481524b68aeaebb0c7b2309f0864a036dc976c1
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue May 23 10:27:53 2023 -0500

    doc/groff.texi: Revise presentation of `mc`.
    
    * doc/groff.texi: Recast.  Identify margin character as a property of
      the output line.  Revise examples.  Re-sequence examples; put the
      normal use case first, and the presentation of oddball AT&T-compatible
      behavior (the margin character being "sticky" on the first output
      line it affects).  Better motivate existence of feature; mention
      diffmk and gdiffmk.  Mark this portion of the manual as reviewed for
      correct glyph usage in examples.
    * man/groff.7.man (Request short reference) <mc>: Sync.
---
 doc/groff.texi  | 112 ++++++++++++++++++++++++++------------------------------
 man/groff.7.man |  24 ++++++------
 2 files changed, 65 insertions(+), 71 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 2ee2c8821..325eb7d83 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -16285,82 +16285,74 @@ The output lines correctly report their numbering 
status.
   This line ISN'T numbered.
 @endExample
 
-@codequotebacktick off
-@codequoteundirected off
-
-@Defreq {mc, glyph [@Var{dist}]}
+@Defreq {mc, [@Var{margin-character} [@Var{distance}]}
 @cindex margin glyph (@code{mc})
 @cindex glyph, for margins (@code{mc})
-Print a @dfn{margin character} to the right of the
-text.@footnote{@dfn{Margin character} is a misnomer since it is an
-output glyph.}  The first argument is the glyph to be printed.  The
-second argument is the distance away from the right margin.  If missing,
-the previously set value is used; the default is 10@tie{}points.  For
-text lines that are too long (that is, longer than the text length plus
-@var{dist}), the margin character is directly appended to the lines.
+Begin (or, with no arguments, cease) writing a @dfn{margin-character} to
+the right of each output line.  The @var{distance} argument separates
+@var{margin-character} from the right margin.  If absent, the most
+recent value is used; the default is 10@tie{}points.  If an output line
+exceeds the line length, the margin character is appended to it.
+@cindex @code{tl} request, and @code{mc}
+No margin character is written on lines produced by the @code{tl}
+request.
 
-With no arguments the margin character is turned off.  If this occurs
-before a break, no margin character is printed.
+The margin character is a property of the output line; the margin
+character last configured when the line is output controls.  If the
+margin character is disabled before an output line breaks, none is
+output (but see below).
 
-For compatibility with @acronym{AT&T} @code{troff}, a call to @code{mc}
-to set the margin character can't be undone immediately; at least one
-line gets a margin character.  Thus
+The margin character is associated with the environment
+(@pxref{Environments}).
 
 @Example
-.ll 1i
+.ll 5i
+.nf
 .mc \[br]
-.mc
-xxx
-.br
-xxx
+This paragraph is marked with a margin character.
+.sp
+As seen above, vertical space isn't thus marked.
+\&
+An output line that is present, but empty, is.
+@c We deliberately overset these lines to mimic `mc`'s behavior.
+    @result{} This paragraph is marked with a margin character.  |
+    @result{}
+    @result{} As seen above, vertical space isn@quoteright{}t thus marked.   |
+    @result{}                                                    |
+    @result{} An output line that is present, but empty, is.     |
 @endExample
+@endDefreq
 
-@noindent
-produces
+For compatibility with @acronym{AT&T} @code{troff}, a call to @code{mc}
+to set the margin character can't be undone immediately; at least one
+line gets a margin character.
 
 @Example
-xxx        |
-xxx
+.ll 10n
+.nf
+.mc |
+.mc *
+.mc
+foo
+bar
+    @result{} foo        *
+    @result{} bar
 @endExample
 
-@cindex @code{tl} request, and @code{mc}
-For empty lines and lines produced by the @code{tl} request no margin
-character is emitted.
-
-The margin character is associated with the environment
-(@pxref{Environments}).
-
+@pindex gdiffmk
 @pindex nrchbar
 @pindex changebar
-This is quite useful for indicating text that has changed, and, in fact,
-there are programs available for doing this (they are called
-@code{nrchbar} and @code{changebar} and can be found in any
-@samp{comp.sources.unix} archive).
-
-@Example
-.ll 3i
-.mc |
-This paragraph is highlighted with a margin
-character.
-.sp
-Vertical space isn't marked.
-.br
-\&
-.br
-But we can fake it with `\&'.
-@endExample
-
-Result:
+@pindex diffmk
+The margin character mechanism is commonly used to annotate changes in
+documents.  The @code{groff} distribution ships a program,
+@command{gdiffmk}, to assist with this task.@footnote{Historically,
+tools named @command{nrchbar} and @command{changebar} were developed for
+this task and could be found in archives of the @code{comp.sources.unix}
+USENET group.  Some proprietary Unices also offer(ed) a @command{diffmk}
+program.}
 
-@Example
-This  paragraph is highlighted |
-with a margin character.       |
-
-Vertical space isn't marked.   |
-                               |
-But we can fake it with `\&'.  |
-@endExample
-@endDefreq
+@codequotebacktick off
+@codequoteundirected off
 
 @DefreqList {psbb, file}
 @DefregItemx {llx}
diff --git a/man/groff.7.man b/man/groff.7.man
index ab5432a2e..1b2d3e58a 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -3519,22 +3519,24 @@ default scaling unit\~\c
 .
 .TPx
 .REQ .mc
-Margin glyph off.
+Cease writing margin character.
 .
 .TPx
-.REQ .mc "c"
-Print glyph\~\c
-.I c
-after each text line at actual distance from right margin.
+.REQ .mc c
+Begin writing margin
+.RI character\~ c
+to the right of each output line.
 .
 .TPx
 .REQ .mc "c d"
-Set margin glyph to\~\c
-.I c
-and distance to\~\c
-.I d
-from right margin
-(default scaling unit\~\c
+Begin writing margin
+.RI character\~ c
+on each output line at
+.RI distance\~ d
+to the right of the right margin
+(default distance
+.scalednumber 10 p ,
+default scaling unit\~\c
 .scaleindicator m ).
 .
 .TPx



reply via email to

[Prev in Thread] Current Thread [Next in Thread]