[bug #64526] Retool example of using newlines as escape delimiters

[Dave]

URL:
  <https://savannah.gnu.org/bugs/?64526>

                 Summary: Retool example of using newlines as escape
delimiters
                   Group: GNU roff
               Submitter: barx
               Submitted: Mon 07 Aug 2023 01:34:40 PM CDT
                Category: Core
                Severity: 1 - Wish
              Item Group: Documentation
                  Status: None
                 Privacy: Public
             Assigned to: None
             Open/Closed: Open
         Discussion Lock: Any
         Planned Release: None


    _______________________________________________________

Follow-up Comments:


-------------------------------------------------------
Date: Mon 07 Aug 2023 01:34:40 PM CDT By: Dave <barx>
==== History ====

Bug #63028 seeks to document some \o limitations in certain devices.  As is my
wont, I wandered afield from this topic in its comment 3, writing about the
documentation for using newlines as escape-sequence delimiters.  (The example
in question does use the \o escape.  But the \o in that example isn't the
point of the example, merely an arbitrarily chosen escape of the ones that
accept newlines as delimiters.)

That wandering is the focus of this bug report.

==== Context ====

Bug #63142 seeks to deprecate allowing newlines as escape delimiters.  But
even if this goes through, there'll presumably be some number of groff
releases that allow but warn about the practice, so in that meantime, the
documentation about it ought to be improved.

==== The bug ====

Nowadays, most of groff's Texinfo examples try to exhibit groff best
practices, but the manual does have an example that uses \o to produce an
accented character.

@Example
A caf\o
e\(aa
in Paris
    @result{} A café in Paris
@endExample

Despite this not being a good way in general to place diacritics on characters
(it's particularly ill suited to the letter i, which must shed its dot when it
acquires a diacritic), the advantage to using it in an example that many
readers will view on a terminal is that a terminal can give meaningful output
for it (albeit not through the \o mechanism but by using the appropriate
precomposed character).  This would not be the case with an example that
actually requires the overstrike to do its job, such as this style-nerdy one:

\[lq]I'm torn between US and UK punctuation styles\o
,\[rq]
she lamented.

However, taking context into account: this example isn't even trying to
illustrate the \o escape, but groff's ability to use newlines as
escape-sequence delimiters.  So maybe a different escape altogether would do
this job without the side effect of choosing between best-practice groff code
and terminal-displayable output (notwithstanding the fact that using newlines
as delimiters is certainly not a best practice itself.  But at least that is
discouraged in the very next sentence.  There's no comment on the
overstriking-to-apply-diacritics aspect of the example--and such a warning
would be out of place here, since the use of \o is not the point of this
section).

I don't have a suggestion offhand of a better escape for this; I'd need to
peruse the list of escapes that accept newlines as delimiters and choose one
that can produce output that would render well on a terminal.







    _______________________________________________________

Reply to this item at:

  <https://savannah.gnu.org/bugs/?64526>

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/