bugGNU roff - Bugs: bug #62339, [doc] add guidance about...

 
 

bug #62339: [doc] add guidance about single-level caching of formatting parameters

Submitter:  Bjarni Ingi Gislason <bjarniig>
Submitted:  Thu 21 Apr 2022 01:02:59 AM UTC
   
 
Category:  General Severity:  1 - Wish
Item Group:  Documentation Status:  None
Privacy:  Public Assigned to:  None
Open/Closed:  Open Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Tue 31 May 2022 05:06:50 AM UTC, comment #5: 

I had intended to solicit more general wording, not this highly particularized discussion of the `\s` escape sequence.

I would like to see language suitable for a node in our Texinfo manual that discusses the general (but sadly not perfectly consistent) practice of *roff programs maintaining a 1-level cache of formatting parameters.

  • Requests and escape sequences that behave this way can be listed.
  • \s0 and \fP should be called out explicitly because of their unusual semantics.
  • .hy without arguments should be called out for its deviation from the general behavior.
G. Branden Robinson <gbranden>
Group administrator
Thu 28 Apr 2022 12:39:48 AM UTC, comment #4: 

  There must be a separate paragraph about "\s0" and mentioning of 0
for \s+-N dropped.

  Adding text to document the use of "\s0":

\s0        Restores the previous type size.

        Does not restore the intended type size if there is a type size
        shift before it, like "\s<i>...\s<n>...\s0...\s0" (restores
        \s<i>+<n>, not that before \s<i>).

        The best practice is not to use it.

        The second best practice is not to use it after a variable,
        as it might contain "\s0".


Bjarni Ingi Gislason <bjarniig>
Mon 25 Apr 2022 04:23:28 PM UTC, comment #3: 

I concur with Dave; some recommended wording would be helpful here.

G. Branden Robinson <gbranden>
Group administrator
Thu 21 Apr 2022 08:01:15 PM UTC, comment #2: 

There's nothing special about \s in this regard.  Many requests and escapes take a special argument (or use lack of one) to indicate "go back to the previous value."  In isolated cases (one, and maybe the only, example being the .ev request), roff maintains an internal stack, so the "go back" syntax actually can be nested.  But this is the exception rather than the rule.  Typically "go back to the previous value" does exactly that, and while there are plenty of aspects of roff syntax lying in wait to trip up the unwary, I think the documentation makes this behavior pretty clear; a rudimentary understanding of "previous value" will clue in the reader that what coders think of as nesting won't work.

Certainly there is more risk of getting tripped up by this when a macro calls another macro, or a string another string, without understanding all state changes that macro or string might make, and this could be a point to make (if it's not there already) when discussing a high-level view of the language.  Do you have a proposed wording for this?

Dave <barx>
Group Member
Thu 21 Apr 2022 01:32:16 AM UTC, comment #1: 

  The absolute type size changes must be around the string variable (\*...).

Bjarni Ingi Gislason <bjarniig>
Thu 21 Apr 2022 01:02:59 AM UTC, original submission:  

Subject: [doc]: Add a remark about a pitfall using \s0

  Using two type size changes around a string can cause malformed
changes if the string (with the size changes) is surrounded by a size
change.

  Example from gcc(1), which uses (pod2man):

.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'

  or simplified

.ds C+ C\s-2+\s0

  and uses

\s-1ISO \*(C+\s0

  So it is actually:

\s-1...\s-2...\s0...\s0

  which results in a sum of \s-1.

  So, when defining a string that contains local type size changes
(\s), absolute size changes should be used (\s+n...\s-n; \s-n...\s+n),
not \s0.

  See also bug #40793.

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 (Posted a comment)
  • -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 4 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2022-05-31 gbranden Severity3 - Normal 1 - Wish
        StatusNeed Info None
        Summary[doc]: Add a remark about a pitfall using \s0 [doc] add guidance about single-level caching of formatting parameters
    2022-04-25 gbranden StatusNone Need Info

    Back to the top

    Powered by Savane 3.13-02a9.
    Corresponding source code