bugGNU roff - Bugs: bug #51072, groff.texi: "Diversions"...

 
 

bug #51072: groff.texi: "Diversions" material from groff_tmac(5) missing

Submitter:  Bjarni Ingi Gislason <bjarniig>
Submitted:  Sat 20 May 2017 01:13:07 AM UTC
   
 
Category:  Core Severity:  1 - Wish
Item Group:  Documentation Status:  Confirmed
Privacy:  Public Assigned to:  gbranden
Open/Closed:  Open Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Jump to the original submission

Wed 27 Dec 2023 09:57:26 PM UTC, comment #9: 

comment #6:

> yes, this seems to make the groff_tmac(5) diversion material
> wholly unnecessary.


This has also yet to be done, but as comment #2 notes, this task more accurately falls under bug #61820.

So it seems the only thing remaining to resolve this bug is the one item marked "remains to be done" in the previous comment.

Dave <barx>
Group Member
Wed 27 Dec 2023 09:31:40 PM UTC, comment #8: 

comment #5:

> > [http://git.savannah.gnu.org/cgit/groff.git/commit/?id=7252c3db
> > Commit 7252c3db], which resolved that bug, did include an
> > example of how to interleave macro definitions.  I'm not sure
> > whether a similar example, of a diversion definition spanning
> > macros, would be a valuable addition to the Texinfo manual's
> > diversion section, or would just bloat it.
>
> There is room in our Texinfo manual to be discursive.


This, then, remains to be done.

Everything else comment #5 covered seems to have been handled back in February 2022.

> the above might be more appropriately placed
> in roff(7) since that page is supposed to discuss "concepts",


This was done in commit 9e35aac37.

> I think with a little bridging material, the above could be
> spliced into our Texinfo manual.  I envision a brief section
> between the "Drawing Requests" and "Traps" sections, titled
> something like "Planning Ahead" for "Formatting for Later".


Done (the section being named "Deferring Output") in commit 85c597a12.

> the "Colors" section/node seems to
> come much later than it could.  It should be relocated earlier,
> no later than "Sizes".


Done in commit 1b93f610e.

Dave <barx>
Group Member
Wed 27 Dec 2023 09:04:42 PM UTC, comment #7: 

comment #1:

> If I don't hear back, I will probably proceed as above.


The submitter having not responded in nearly two years, I think this can come out of Need Info status.  From subsequent comments, there seems a pretty clear plan for how to resolve this.

Dave <barx>
Group Member
Fri 28 Jan 2022 02:51:20 PM UTC, comment #6: 

comment #5:

> I have the following already in groff(7), under section "_groff_
> elements".


Oh, good.  I didn't look there, since the ticket focused on info content, but yes, this seems to make the groff_tmac(5) diversion material wholly unnecessary.

> Making an analogy like that, I suppose I'm a little more
> sympathetic to Bernd's presentation of diversions.  But not a
> lot, because his analogy is to an unforgiving compiled
> programming language, not to everyday concepts.


Yeah, and even to me, someone familiar with C, the analogy seems an uneasy fit.  But that aside, the groff documentation shouldn't assume readers know C programming.

> > Maybe this is also something that can be shunted into a
> > specific examples file,
>
> I think that's too pessimistic.


"Shunted" may have been a poor word choice; my intent wasn't to treat the material as a second-class citizen, but to locate it where it's most useful to users.  But you make a solid case for its inclusion in the info manual.

Dave <barx>
Group Member
Fri 28 Jan 2022 12:58:09 PM UTC, comment #5: 

Hi, Dave!

comment #4:

> comment #1:
> > Here is that material.
> [snip]


> >        The most powerful feature using diversions is to
> >        start a diversion within a macro definition and end
> >        it within another macro.  Then everything between
> >        each call of this macro pair is stored within the
> >        diversion and can be manipulated from within the
> >        macros.


> >
> > Does it communicate any concrete information about groff
> > that our Texinfo manual (now) does not?
>
> That final paragraph quoted above is perhaps inferable from
> the rest, but--much like the second plank of bug #57944--for
> people who didn't grow up groffing, it's a nonintuitive way to
> think of defining a diversion.
>
> [http://git.savannah.gnu.org/cgit/groff.git/commit/?id=7252c3db
> Commit 7252c3db], which resolved that bug, did include an
> example of how to interleave macro definitions.  I'm not sure
> whether a similar example, of a diversion definition spanning
> macros, would be a valuable addition to the Texinfo manual's
> diversion section, or would just bloat it.


There is room in our Texinfo manual to be discursive.  My
post-1.22.4 tour of the groff language at the beginning of
chapter 5 (up to but not including the node/section
"Measurements") is manifestly conversational, at least compared
to most of the older content.

I have the following already in groff(7), under section "_groff_
elements".


       A further few language elements arise as page layouts
       become more sophisticated and demanding.  Environments
       collect formatting parameters like line length and
       typeface.  A diversion stores formatted output for later
       use.  A trap is a condition on the input or output,
       tested automatically by the formatter, that is associated
       with a macro, causing it to be called when that condition
       is fulfilled.

       Footnote support often exercises all three of the
       foregoing features.  A simple implementation might work
       as follows.  A pair of macros is defined: one starts a
       footnote and the other ends it.  The author calls the
       first macro where a footnote marker is desired.  The
       macro establishes a diversion so that the footnote text
       is collected at the place in the body text where its
       corresponding marker appears.  An environment is created
       for the footnote so that it is set at a smaller typeface.
       The footnote text is formatted in the diversion using
       that environment, but it does not yet appear in the
       output.  The document author calls the footnote end
       macro, which returns to the previous environment and ends
       the diversion.  Later, after much more body text in the
       document, a trap, set a small distance above the page
       bottom, is sprung.  The macro called by the trap draws a
       line across the page and emits the stored diversion.
       Thus, the footnote is rendered.


I have noted elsewhere (I can't remember if it's in a stashed
commit, one I've pushed, or in a comment to a Savannah ticket or
mailing list) that the above might be more appropriately placed
in roff(7) since that page is supposed to discuss "concepts",
it does not yet fulfill this promise nearly as well as it
should, and the foregoing is applicable to all *roffs since 1974
or so.

I think with a little bridging material, the above could be
spliced into our Texinfo manual.  I envision a brief section
between the "Drawing Requests" and "Traps" sections, titled
something like "Planning Ahead" for "Formatting for Later".

Structurally, chapter 5 of the manual ("gtroff Reference") gets
a little chaotic toward the end.  But as a rough rule of thumb,
all the requests and escape sequences before that point "do
something now", i.e., move or change the way ink is put on the
page in linear sequence with similar operations before and
after.  If you squint, even the "Conditionals and Loops" fits
this characterization, because it breaches linearity only in its
own context.  But diversions push things out for later and traps
can make events spring up in the midst of others.

Making an analogy like that, I suppose I'm a little more
sympathetic to Bernd's presentation of diversions.  But not a
lot, because his analogy is to an unforgiving compiled
programming language, not to everyday concepts.

I'll note while I'm here that the "Colors" section/node seems to
come much later than it could.  It should be relocated earlier,
no later than "Sizes".  (In fact, nearly everything that an
environment saves/preserves should be discussed by the point
that environments are introduced, with exceptions only for
arcane necessities like the enablement status of compatibility
mode or similar.)  The color-related escapes sequences and
requests do obvious things; apart from the mild complication of
color channels and spaces, they are straightforward to present
and use.

> Maybe this is also something that can be shunted into a
> specific examples file, putting it on the plate of bug #57855.


I think that's too pessimistic.  ms(7) and me(7) are both heavy
users of diversion opening/closing macro pairs.  It's an
idiomatic usage (for footnotes, it's the archetypal one), and
only this fog of mystique has kept diversions from receiving the
emphasis they are due.

Not everybody needs them, but there's a reason they became a
language feature even before Murray Hill acquired the C/A/T.

Regards,
Branden

G. Branden Robinson <gbranden>
Group administrator
Fri 28 Jan 2022 05:18:30 AM UTC, comment #4: 

comment #1:

> Here is that material.

[snip]

>        The most powerful feature using diversions is to start a
>        diversion within a macro definition and end it within another
>        macro.  Then everything between each call of this macro pair is
>        stored within the diversion and can be manipulated from within
>        the macros.


>
> Does it communicate any concrete information about groff
> that our Texinfo manual (now) does not?


That final paragraph quoted above is perhaps inferable from the rest, but--much like the second plank of bug #57944--for people who didn't grow up groffing, it's a nonintuitive way to think of defining a diversion.

Commit 7252c3db, which resolved that bug, did include an example of how to interleave macro definitions.  I'm not sure whether a similar example, of a diversion definition spanning macros, would be a valuable addition to the Texinfo manual's diversion section, or would just bloat it.  Maybe this is also something that can be shunted into a specific examples file, putting it on the plate of bug #57855.

Dave <barx>
Group Member
Tue 25 Jan 2022 06:11:38 AM UTC, comment #3: 

comment #2:

> comment #1:
> > I am inclined to drop this subsection of groff_tmac(5) entirely,
> > as proposed in bug #61280.
>
> This is presumably meant to say bug #61820.


Indeed so.

oSrry ofr ym rtnapssoai.

(Sorry for my transposia.)

G. Branden Robinson <gbranden>
Group administrator
Tue 25 Jan 2022 12:25:47 AM UTC, comment #2: 

comment #1:

> I am inclined to drop this subsection of groff_tmac(5) entirely,
> as proposed in bug #61280.


This is presumably meant to say bug #61820.

Dave <barx>
Group Member
Mon 24 Jan 2022 06:24:48 AM UTC, comment #1: 

original submission:

>   As the "info" file is claimed to be the best documentation about "groff",


I don't think any of our documentation makes that claim anymore.

If it does, please point it out to me.

> a text about writing a diversion that works is missing from it.


The node/section on diversions has been moderately revised since groff 1.22.4.


$ git diff -U100 1.22.4 doc/groff.texi | sed -n '/^.@node Diversions/,/^.@node/p'
 @node Diversions, Environments, Traps, gtroff Reference
 @section Diversions
 @cindex diversions

-In @code{gtroff} it is possible to @dfn{divert} text into a named
-storage area.  Due to the similarity to defining macros it is sometimes
-said to be stored in a macro.  This is used for saving text for output
-at a later time, which is useful for keeping blocks of text on the same
-page, footnotes, tables of contents, and indices.
-
+In @code{roff} systems it is possible to format text as if for output,
+but instead of writing it immediately, one can @dfn{divert} the
+formatted text into a named storage area.  The same name space is used
+for such @emph{diversions} as for strings and macros;
+@xref{Identifiers}.  Such text is sometimes said to be ``stored in a
+macro'', but this coinage obscures the important distinction between
+macros and strings on one hand and diversions on the other; the former
+store @emph{unformatted} input text, and the latter capture
+@emph{formatted} output.  Applications of diversions include ``keeps''
+(preventing a page break from occurring at an inconvenient place by
+forcing a set of output lines to be set as a group), footnotes, tables
+of contents, and indices.
 @cindex top-level diversion
 @cindex diversion, top-level
-For orthogonality it is said that @code{gtroff} is in the @dfn{top-level
-diversion} if no diversion is active (i.e., the data is diverted to the
-output device).
-
-Although the following requests can be used to create diversions,
-simply using an undefined diversion will cause it to be defined as empty.
-@xref{Identifiers}.
-
-@DefreqList {di, macro}
-@DefreqListEndx {da, macro}
+For orthogonality it is said that GNU @code{troff} is in the
+@dfn{top-level diversion} if no diversion is active (that is, formatted
+output is being ``diverted'' immediately to the output device).
+
+Dereferencing an undefined diversion will create an empty one of that
+name and cause a warning of type @samp{mac} to be emitted
+(@pxref{Debugging}).  A diversion does not exist for the purpose of
+testing with the @code{d} conditional operator until its initial
+definition ends (@pxref{Operators in Conditionals}).  The following
+requests are used to create and alter diversions.
+
+@DefreqList {di, [@Var{name}]}
+@DefreqListEndx {da, [@Var{name}]}
 @cindex beginning diversion (@code{di})
 @cindex diversion, beginning (@code{di})
 @cindex ending diversion (@code{di})
 @cindex diversion, ending (@code{di})
 @cindex appending to a diversion (@code{da})
 @cindex diversion, appending (@code{da})
-Begin a diversion.  Like the @code{de} request, it takes an argument of
-a macro name to divert subsequent text into.  The @code{da} macro
-appends to an existing diversion.
+Start collecting formatted output in a diversion called @var{name}.  The
+@code{da} request appends to the existing diversion called @var{name},
+creating it if necessary.  The pending output line is diverted as well.
+Switching to another (empty) environment (with the @code{ev} request)
+avoids the inclusion of the current partially collected line;
+@ref{Environments}.

-@code{di} or @code{da} without an argument ends the diversion.
+Invoking @code{di} or @code{da} without an argument stops diverting
+output to the diversion named by the most recent corresponding request.
+If @code{di} or @code{da} is called without an argument when there is no
+current diversion, a warning of type @samp{di} is produced.
+@xref{Debugging}, for information about the enablement and suppression
+of warnings.

-The current partially filled line is included into the diversion.  See
-the @code{box} request below for an example.  Note that switching to
-another (empty) environment (with the @code{ev} request) avoids the
-inclusion of the current partially filled line.
+@Example
+Before the diversion.
+.di yyy
+In the diversion.
+.br
+.di
+After the diversion.
+.br
+    @result{} After the diversion.
+.yyy
+    @result{} Before the diversion.  In the diversion.
+@endExample
 @endDefreq

-@DefreqList {box, macro}
-@DefreqListEndx {boxa, macro}
-Begin (or append to) a diversion like the @code{di} and @code{da}
-requests.  The difference is that @code{box} and @code{boxa} do not
-include a partially filled line in the diversion.
+@cindex box (diversion type)
+Because it is often desirable to exclude the partially collected line
+from a diversion, @code{groff} supports an alternative form of diversion
+known as a @dfn{box}.

-Compare this:
+@DefreqList {box, [@Var{name}]}
+@DefreqListEndx {boxa, [@Var{name}]}
+Divert (or append) output to @var{name}, similarly to the @code{di} and
+@code{da} requests, respectively.  Any output line pending when these
+requests are invoked is @emph{not} included in the box.  Calling
+@code{box} or @code{boxa} without an argument stops diverting output to
+the box named by the most recent corresponding request; a pending output
+line inside a diversion is discarded.

 @Example
 Before the box.
 .box xxx
 In the box.
 .br
+Hidden treasure.
 .box
 After the box.
 .br
     @result{} Before the box.  After the box.
 .xxx
     @result{} In the box.
 @endExample
-
-@noindent
-with this:
-
-@Example
-Before the diversion.
-.di yyy
-In the diversion.
-.br
-.di
-After the diversion.
-.br
-    @result{} After the diversion.
-.yyy
-    @result{} Before the diversion.  In the diversion.
-@endExample
-
-@code{box} or @code{boxa} without an argument ends the diversion.
 @endDefreq

+Apart from pending output line inclusion and the request names that
+populate them, boxes are handled exactly as diversions are.  All of the
+following @code{groff} language elements can be used with them
+interchangeably.
+
 @DefregList {.z}
 @DefregListEndx {.d}
 @cindex @code{nl} register, and @code{.d}
 @cindex nested diversions
 @cindex diversion, nested
 @cindex diversion name register (@code{.z})
 @cindex vertical position in diversion register (@code{.d})
 @cindex position, vertical, in diversion, register (@code{.d})
 @cindex diversion, vertical position in, register (@code{.d})
-Diversions may be nested.  The read-only number register @code{.z}
-contains the name of the current diversion (this is a string-valued
-register).  The read-only number register @code{.d} contains the current
-vertical place in the diversion.  If not in a diversion it is the same
-as register @code{nl}.
+Diversions may be nested.  The read-only string-valued register
+@code{.z} contains the name of the current diversion.  The read-only
+register @code{.d} contains the current vertical place in the diversion.
+If the input text is not being diverted, @code{.d} reports the same
+location as the register @code{nl}.
 @endDefreg

 @Defreg {.h}
 @cindex high-water mark register (@code{.h})
 @cindex mark, high-water, register (@code{.h})
 @cindex position of lowest text line (@code{.h})
 @cindex text line, position of lowest (@code{.h})
-The @dfn{high-water mark} on the current page or in the current
-diversion.  It corresponds to the text baseline of the lowest line
-on the page.  This is a read-only register.
+The read-only register @code{.h} stores the @dfn{high-water mark} on the
+current page or in the current diversion.  It corresponds to the text
+baseline of the lowest line on the page.@footnote{Thus, the ``water''
+gets ``higher'' proceeding @emph{down} the page.}

 @Example
 .tm .h==\n[.h], nl==\n[nl]
     @result{} .h==0, nl==-1
 This is a test.
 .br
 .sp 2
 .tm .h==\n[.h], nl==\n[nl]
     @result{} .h==40, nl==120
 @endExample

 @cindex @code{.h} register, difference to @code{nl}
 @cindex @code{nl} register, difference to @code{.h}
 @noindent
-As can be seen in the previous example, empty lines are not considered
-in the return value of the @code{.h} register.
+As implied by the example, vertical spacing does not produce text
+baselines and thus does not increase the value interpolated by
+@samp{\n[.h]}.
 @endDefreg

 @DefregList {dn}
 @DefregListEndx {dl}
 @cindex @code{dn} register, and @code{da} (@code{boxa})
 @cindex @code{dl} register, and @code{da} (@code{boxa})
 @cindex @code{da} request, and @code{dn} (@code{dl})
 @cindex @code{boxa} request, and @code{dn} (@code{dl})
-After completing a diversion, the read-write number registers @code{dn}
-and @code{dl} contain the vertical and horizontal size of the diversion.
-Note that only the just processed lines are counted: For the computation
-of @code{dn} and @code{dl}, the requests @code{da} and @code{boxa} are
-handled as if @code{di} and @code{box} had been used -- lines that have
-been already stored in a macro are not taken into account.
+After completing a diversion, the writable registers @code{dn} and
+@code{dl} contain the vertical and horizontal size of the diversion.
+Only the lines just processed are counted: for the computation of
+@code{dn} and @code{dl}, the requests @code{da} and @code{boxa} are
+handled as if @code{di} and @code{box} had been used,
+respectively---lines that have been already stored in the diversion
+(box) are not taken into account.

 @Example
-.\" Center text both horizontally & vertically
+.\" Center text both horizontally and vertically.
 .
-.\" Enclose macro definitions in .eo and .ec
-.\" to avoid the doubling of the backslash
+.\" Disable the escape character with .eo so that we
+.\" don't have to double backslashes on the "\n"s.
 .eo
-.\" macro .(c starts centering mode
+.\" Macro .(c starts centering mode.
 .de (c
 .  br
 .  ev (c
 .  evc 0
 .  in 0
 .  nf
 .  di @@c
 ..
 @endExample
 @Example
-.\" macro .)c terminates centering mode
+.\" Macro .)c terminates centering mode.
 .de )c
 .  br
 .  ev
 .  di
 .  nr @@s (((\n[.t]u - \n[dn]u) / 2u) - 1v)
 .  sp \n[@@s]u
 .  ce 1000
 .  @@c
 .  ce 0
 .  sp \n[@@s]u
 .  br
 .  fi
 .  rr @@s
 .  rm @@c
 ..
-.\" End of macro definitions, restore escape mechanism
+.\" End of macro definitions; restore escape character.
 .ec
 @endExample
 @endDefreg

-@DefescList {\\!, , , }
+@DefescList {\\!, , anything, }
 @DefescListEndx {\\?, , anything, \\?}
 @cindex transparent output (@code{\!}, @code{\?})
 @cindex output, transparent (@code{\!}, @code{\?})
-Prevent requests, macros, and escapes from being interpreted when read
-into a diversion.  Both escapes take the given text and
-@dfn{transparently} embed it into the diversion.  This is useful for
-macros that shouldn't be invoked until the diverted text is actually
-output.
-
-The @code{\!} escape transparently embeds text up to and including the
-end of the line.  The @code{\?} escape transparently embeds text until
-the next occurrence of the @code{\?} escape.  Example:
-
-@Example
-\?@var{anything}\?
-@endExample
-
-@cindex @code{\?}, and copy-in mode
-@cindex copy-in mode, and @code{\?}
-@cindex mode, copy-in, and @code{\?}
-@cindex @code{\!}, and copy-in mode
-@cindex copy-in mode, and @code{\!}
-@cindex mode, copy-in, and @code{\!}
+@dfn{Transparently} embed @var{anything} into the current diversion,
+preventing requests, macro calls, and escape sequences from being
+interpreted when read into a diversion.  This is useful for preventing
+them from taking effect until the diverted text is actually output.  The
+@code{\!} escape sequence transparently embeds input up to and including
+the end of the line.  The @code{\?} escape sequence transparently embeds
+input until its own next occurrence.
+
+@cindex @code{\?}, and copy mode
+@cindex copy mode, and @code{\?}
+@cindex mode, copy, and @code{\?}
+@cindex @code{\!}, and copy mode
+@cindex copy mode, and @code{\!}
+@cindex mode, copy, and @code{\!}
 @noindent
-@var{anything} may not contain newlines; use @code{\!}  to embed
-newlines in a diversion.  The escape sequence @code{\?} is also
+@var{anything} may not contain newlines; use @code{\!} by itself to
+embed newlines in a diversion.  The escape sequence @code{\?} is also
 recognized in copy mode and turned into a single internal code; it is
 this code that terminates @var{anything}.  Thus the following example
 prints@tie{}4.

 @Example
 .nr x 1
 .nf
 .di d
 \?\\?\\\\?\\\\\\\\nx\\\\?\\?\?
 .di
 .nr x 2
 .di e
 .d
 .di
 .nr x 3
 .di f
 .e
 .di
 .nr x 4
 .f
 @endExample

-Both escapes read the data in copy mode.
+Both escape sequences read the data in copy mode.

 @cindex @code{\!}, in top-level diversion
 @cindex top-level diversion, and @code{\!}
 @cindex diversion, top-level, and @code{\!}
 If @code{\!} is used in the top-level diversion, its argument is
-directly embedded into the @code{gtroff} intermediate output.  This can
-be used for example to control a postprocessor that processes the data
-before it is sent to the device driver.
+directly embedded into GNU @code{troff}'s intermediate output.  This can
+be used, for example, to control a postprocessor that processes the data
+before it is sent to an output driver.

 @cindex @code{\?}, in top-level diversion
 @cindex top-level diversion, and @code{\?}
 @cindex diversion, top-level, and @code{\?}
 The @code{\?} escape used in the top-level diversion produces no output
 at all; its argument is simply ignored.
 @endDefesc

 @cindex @code{\!}, and @code{output} request
 @cindex @code{output} request, and @code{\!}
-@cindex @code{output} request, and copy-in mode
-@cindex copy-in mode, and @code{output} request
-@cindex mode, copy-in, and @code{output} request
+@cindex @code{output} request, and copy mode
+@cindex copy mode, and @code{output} request
+@cindex mode, copy, and @code{output} request
 @Defreq {output, string}
-Emit @var{string} directly to the @code{gtroff} intermediate output
+Emit @var{string} directly to GNU @code{troff}'s intermediate output
 (subject to copy mode interpretation); this is similar to @code{\!} used
 at the top level.  An initial double quote in @var{string} is stripped
 off to allow initial blanks.

-This request can't be used before the first page has started -- if you
+This request can't be used before the first page has started---if you
 get an error, simply insert @code{.br} before the @code{output} request.

 Without argument, @code{output} is ignored.

 Use with caution!  It is normally only needed for mark-up used by a
 postprocessor that does something with the output before sending it to
 the output device, filtering out @var{string} again.
 @endDefreq

 @Defreq {asciify, div}
 @cindex unformatting diversions (@code{asciify})
 @cindex diversion, unformatting (@code{asciify})
 @cindex @code{trin} request, and @code{asciify}
-@dfn{Unformat} the diversion specified by @var{div} in such a way that
-@acronym{ASCII} characters, characters translated with the @code{trin}
-request, space characters, and some escape sequences that were formatted
-and diverted are treated like ordinary input characters when the
-diversion is reread.  It can be also used for gross hacks; for example,
-the following sets register@tie{}@code{n} to@tie{}1.
+@dfn{Unformat} the diversion @var{div} in a way such that Unicode basic
+Latin (@acronym{ASCII}) characters, characters translated with the
+@code{trin} request, space characters, and some escape sequences, that
+were formatted and diverted into @var{div} are treated like ordinary
+input characters when @var{div} is reread.  Doing so can be useful in
+conjunction with the @code{writem} request.  @code{asciify} can be also
+used for gross hacks; for example, the following sets
+register@tie{}@code{n} to@tie{}1.

 @Example
 .tr @@.
 .di x
 @@nr n 1
 .br
 .di
 .tr @@@@
 .asciify x
 .x
 @endExample

-Note that @code{asciify} cannot return all items in a diversion back
-to their source equivalent, nodes such as @code{\N[...]} will still
-remain as nodes, so the result cannot be guaranteed to be a pure string.
-
-@xref{Copy-in Mode}.
+@code{asciify} cannot return all items in a diversion to their source
+equivalent: nodes such as those produced by the @code{\N} escape
+sequence will remain nodes, so the result cannot be guaranteed to be a
+pure string.  @xref{Copy Mode}.  Glyph parameters such as the type face
+and size are not preserved; use @code{unformat} to achieve that.
 @endDefreq

 @Defreq {unformat, div}
-Like @code{asciify}, unformat the specified diversion.  However,
-@code{unformat} only unformats spaces and tabs between words.
-Unformatted tabs are treated as input tokens, and spaces are stretchable
-again.
-
-The vertical size of lines is not preserved; glyph information (font,
-font size, space width, etc.)@: is retained.
+Like @code{asciify}, unformat the diversion @var{div}.  However,
+@code{unformat} handles only tabs and spaces between words, the latter
+usually arising from spaces or newlines in the input.  Tabs are treated
+as input tokens, and spaces become adjustable again.  The vertical sizes
+of lines are not preserved, but glyph information (font, type size,
+space width, and so on) is retained.
 @endDefreq

+@codequotebacktick off
+@codequoteundirected off
+

 @c =====================================================================

 @node Environments, Suppressing output, Diversions, gtroff Reference


>   The Chapter "Diversions" in groff_tmac(5) contains a missing piece for the
> "info" file.


Here is that material.


   Diversions
       Diversions can be used to implement quite advanced programming
       constructs.  They are comparable to pointers to large data
       structures in the C programming language, but their usage is
       quite different.

       In their simplest form, diversions are multi-line strings, but
       diversions get their power when used dynamically within macros.
       The (formatted) information stored in a diversion can be
       retrieved by calling the diversion just like a macro.

       Most of the problems arising with diversions can be avoided if
       you remember that diversions always store complete lines.  Using
       diversions when the line buffer has not been flushed produces
       strange results; not knowing this, many people get desperate
       about diversions.  To ensure that a diversion works, add line
       breaks at the right places.  To be safe, enclose everything that
       has to do with diversions within a pair of line breaks; for
       example, by explicitly using .br requests.  This rule should be
       applied to diversion definition, both inside and outside, and to
       all calls of diversions.  This is a bit of overkill, but it works
       nicely.

       (If you really need diversions which should ignore the current
       partial line, use environments to save the current partial line
       and/or use the .box request.)

       The most powerful feature using diversions is to start a
       diversion within a macro definition and end it within another
       macro.  Then everything between each call of this macro pair is
       stored within the diversion and can be manipulated from within
       the macros.


I don't care for much of this.  It opens with editorializing about advanced usage and an analogy to pointers in C, both of which I think suggest to the reader that a facility with diversion use will be difficult to acquire and possibly unrewarding.

It is not tightly or concisely written.  Does it communicate any concrete information about groff that our Texinfo manual (now) does not?  I can't see anything, and I am inclined to drop this subsection of groff_tmac(5) entirely, as proposed in bug #61280.

Let me know what you think.  If I don't hear back, I will probably proceed as above.

G. Branden Robinson <gbranden>
Group administrator
Sat 20 May 2017 01:13:07 AM UTC, original submission:  

  As the "info" file is claimed to be the best documentation about "groff",
a text about writing a diversion that works is missing from it.

  The Chapter "Diversions" in groff_tmac(5) contains a missing piece for the
"info" file.


Bjarni Ingi Gislason <bjarniig>

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

No files currently attached

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by gbranden (Posted a comment)
  • -email is unavailable- added by barx (Updated the item)
  • -email is unavailable- added by schwarze (Updated the item)
  • -email is unavailable- added by bgarrigues (Updated the item)
  • -email is unavailable- added by bjarniig (Submitted the item)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only logged-in users can vote.

     

    Follow 7 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2023-12-27 barx StatusNeed Info Confirmed
    2022-01-24 gbranden StatusNone Need Info
        Assigned toNone gbranden
        Summarygroff.info: Tips on writing a working diversion is missing groff.texi: "Diversions" material from groff_tmac(5) missing
    2021-05-14 barx CategoryNone Core
    2018-02-16 schwarze Severity3 - Normal 1 - Wish
    2017-09-01 bgarrigues Item GroupFeature change Documentation

    Back to the top

    Powered by Savane 3.13-3230.
    Corresponding source code