bugGNU roff - Bugs: bug #63812, Discussion of conditional...

 
 

bug #63812: Discussion of conditional expressions in docs should mention `.if h`

Submitter:  John Gardner <alhadis>
Submitted:  Fri 17 Feb 2023 04:55:09 AM UTC
   
 
Category:  Core Severity:  1 - Wish
Item Group:  Documentation Status:  Fixed
Privacy:  Public Assigned to:  gbranden
Open/Closed:  Closed Planned Release:  1.23.0
* Mandatory Fields

Add a New Comment Rich Markup
   

Jump to the original submission

Wed 05 Apr 2023 10:28:03 PM UTC, comment #13: 


comment #12:

> Because I love crosslinking:

[...]

> > and new conditional operators to test for "nodes" and for glyphs
> > that are actually defined in the current font,
>
> If either of these have tickets, I can't find them.


I've filed bug #64004 to track my semi-coherent thoughts on this.

G. Branden Robinson <gbranden>
Group administrator
Wed 05 Apr 2023 01:39:21 AM UTC, comment #12: 

Because I love crosslinking:

comment #6:

> I want a `for` request that will iterate over macros/strings/diversions,


Bug #62264

> and new conditional operators to test for "nodes" and for glyphs
> that are actually defined in the current font,


If either of these have tickets, I can't find them.

Dave <barx>
Group Member
Fri 31 Mar 2023 11:48:15 AM UTC, comment #11: 

This was pushed to master last week.


commit 9df2e2ea425663167496ba340f850c0b9aa37990
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Sun Mar 5 03:10:48 2023 -0600

    [docs]: Fix Savannah #63812.

    * doc/groff.texi (Operators in Conditionals):
    * man/groff.7.in (Conditional expressions): Clarify how the output
      comparison operator is recognized.

    Fixes <https://savannah.gnu.org/bugs/?63812>.  Thanks to John Gardner
    for the report.

    ANNOUNCE: Update bug counts.


G. Branden Robinson <gbranden>
Group administrator
Sun 05 Mar 2023 01:09:21 PM UTC, comment #10: 

comment #9:

> comment #8:
> > This would be a simple iterator.  The string named "s" takes on the value of each item in string-expr from left to right.
> How is string-expr tokenised?


Sorry, I wasn't thinking properly when I typed that.  (Haven't actually tried to implement this yet.)

The second argument would need to be a "name", so a string/macro/diversion.  Attempting to iterate over an undefined one would probably throw a "mac" warning.  Attempting to iterate over a request would be rejected with an error.

> What do you mean by contrivance? AFAIK, most of the characters documented by groff_char(7) have corresponding entries in the UCD.


I'm starting to remember what I wanted the really-a-glyph predicate for.

See bug #63354.  There's a lot to it.

> No no, I only mentioned that to elucidate my remark about "too many hours coding in PostScript".


Ahhh.  No worries.  :)

G. Branden Robinson <gbranden>
Group administrator
Sun 05 Mar 2023 12:53:25 PM UTC, comment #9: 

comment #8:

> This would be a simple iterator.  The string named "s" takes on the value of each item in string-expr from left to right.

How is string-expr tokenised? Is its value treated like a whitespace-delimited list (following the same rebarbative logic as Roff's argument quoting/escaping), or is it closer to Awk and the Bourne shell in that an (internal) field separator can be specified?

> some contrivance in the *roff language?"

What do you mean by contrivance? AFAIK, most of the characters documented by groff_char(7) have corresponding entries in the UCD.

> > (This corresponds to PostScript's `where` operator, which locates the entry on the dictionary stack which defines an entry with the given key. I'll shut up now)
> By the time a request can process something in *roff, there aren't many stacks of interest to look at.  Just a node list.

No no, I only mentioned that to elucidate my remark about "too many hours coding in PostScript".

John Gardner <alhadis>
Sun 05 Mar 2023 12:26:00 PM UTC, comment #8: 


comment #7:

> comment #6:
> > Long stories short, I want a `for` request that will iterate over macros/strings/diversions
> Interesting. Does it resemble this?


Not closely.

What I had in mind was this.


.for s string-expr \{\
.  whatever
.  you
.  want
.\"  break
.\"  continue
.\}


This would be a simple iterator.  The string named "s" takes on the value of each item in string-expr from left to right.
 

> > and new conditional operators to test for "nodes"
> YES. PLEASE. The whole "nodes versus strings" semantic is what led me down the aforementioned rabbit hole. The fact I even got it working (without GNU extensions, no less) is a testament to my neurotic stubbornness.


Yes.  People keep doing complicated, wacky things to work around this.  Keith Marshall has his "sanitize.tmac".  I have two different instances of loony shit in an.tmac and doc.tmac to abbreviate overlong material for placement in headers/footers.

It's incredibly tedious and bug-prone.
 

> > and for glyphs that are actually defined in the current font
> I've probably spent too many hours coding in PostScript, but wouldn't an escape sequence that expands to the name of the font containing the requested glyph be more useful?


Maybe.  But the question I've found myself needing to answer recently was "is this REALLY a glyph the font will provide, or some contrivance in the *roff language?".  I forget now where this came up but it's in a Savannah ticket.  Dave might remember.

> At least that way you'll be able to compare the output against the name of the current font.


Not saying this isn't worth doing, but it's not one of the two big changes mentioned above, and which I would like to do soon.
 

> (This corresponds to PostScript's `where` operator, which locates the entry on the dictionary stack which defines an entry with the given key. I'll shut up now)


By the time a request can process something in *roff, there aren't many stacks of interest to look at.  Just a node list.

*roff was written for small systems. There's no Document Object Model.  The formatter has no view of the whole document at any time.  It keeps track of as little as possible; enough to spit out the next output line and a few other bits of state demanded by features required to typeset conventional works.

G. Branden Robinson <gbranden>
Group administrator
Sun 05 Mar 2023 11:56:19 AM UTC, comment #7: 

comment #6:

> Long stories short, I want a `for` request that will iterate over macros/strings/diversions

Interesting. Does it resemble this?

> and new conditional operators to test for "nodes"

YES. PLEASE. The whole "nodes versus strings" semantic is what led me down the aforementioned rabbit hole. The fact I even got it working (without GNU extensions, no less) is a testament to my neurotic stubbornness.

> and for glyphs that are actually defined in the current font

I've probably spent too many hours coding in PostScript, but wouldn't an escape sequence that expands to the name of the font containing the requested glyph be more useful? At least that way you'll be able to compare the output against the name of the current font.

(This corresponds to PostScript's `where` operator, which locates the entry on the dictionary stack which defines an entry with the given key. I'll shut up now)

John Gardner <alhadis>
Sun 05 Mar 2023 11:36:55 AM UTC, comment #6: 


comment #5:

> The projected likelihood of introducing such a backwards-incompatible feature is marginal at best, and indicative of feature creep at worst.


Muahahahaha.  You don't know of my plans for groff 1.24.

Long stories short, I want a `for` request that will iterate over macros/strings/diversions, and new conditional operators to test for "nodes" and for glyphs that are actually defined in the current font, as opposed to interposed via character definitions.

G. Branden Robinson <gbranden>
Group administrator
Sun 05 Mar 2023 11:32:17 AM UTC, comment #5: 

comment #4:

> Here's what I have at the moment.

Looks good. One nanoscopic nitpick, which borders on bikeshedding:

> and GNU @code{troff} may provide additional operators in the future.

The projected likelihood of introducing such a backwards-incompatible feature is marginal at best, and indicative of feature creep at worst. I wouldn't rule the possibility out completely, but it's still not likely enough to warrant mentioning in Groff's documentation.

(I told you it was a nitpick…)

John Gardner <alhadis>
Sun 05 Mar 2023 10:02:20 AM UTC, comment #4: 

I'm working on this on a (so far, local only) post-1.23.0 branch.

Here's what I have at the moment.


diff --git a/doc/groff.texi b/doc/groff.texi
index 15b3cd8a3..ae5645c63 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -12571,8 +12571,19 @@ certain other @code{troff} implementations.@footnote{This refers to
 @code{vtroff}, a translator that would convert the C/A/T output from
 early-vintage @acronym{AT&T} @code{troff} to a form suitable for
 Versatec and Benson-Varian plotters.}
+@end table
+
+If the first argument to an @code{if}, @code{ie}, or @code{while}
+request begins with a non-alphanumeric character apart from @code{!}
+(see below); it performs an @slanted{output comparison test}.
+@footnote{Strictly, letters not otherwise recognized @emph{are} treated
+as output comparison delimiters.  For portability, it is wise to avoid
+using letters not in the list above; for example, Plan@tie{}9
+@code{troff} uses @samp{h} to test a mode it calls @code{htmlroff}, and
+GNU @code{troff} may provide additional operators in the future.}

 @cindex output comparison operator
+@table @code
 @item @code{'}@var{xxx}@code{'}@var{yyy}@code{'}
 True if formatting the comparands @var{xxx} and @var{yyy} produces the
 same output commands.  The delimiter need not be a neutral apostrophe:
diff --git a/man/groff.7.man b/man/groff.7.man
index 0d0539a98..dec4deefd 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -2099,9 +2099,20 @@ T}
 .
 .
 .P
-The first of the above,
+If the first argument to an
+.BR .if ,
+.BR .ie ,
+or
+.B .while
+request begins with a non-alphanumeric character apart from
+.B !\&
+(see below);
+it performs an
+.I "output comparison test" .
+.
+Shown first in the table above,
 the
-.I "output comparison operator,"
+.I "output comparison operator"
 interpolates a true value if formatting its comparands
 .I s1
 and


G. Branden Robinson <gbranden>
Group administrator
Fri 17 Feb 2023 07:03:24 AM UTC, comment #3: 

comment #2:

> That's documented because we do support it.  If we didn't, the 'v' would be treated as the opening delimiter of a formatted output comparison operation, just like other letters that aren't conditional operators.

Ah right, that makes sense. Following that line of reasoning, then, it makes sense not to document `.if h` if Groff doesn't recognise it as a built-in condition (and supporting it now would obviously break compatibility with existing macros that, for whatever reason, use "h" as a string delimiter.

John Gardner <alhadis>
Fri 17 Feb 2023 06:56:58 AM UTC, comment #2: 


comment #1:

> I'm a bit dubious about this.  I have send elsewhere


s/send/said/

Also, if I find where I said this, I'll link to it.

And, finally, I didn't address `.if v`.

That's documented because we do support it.  If we didn't, the 'v' would be treated as the opening delimiter of a formatted output comparison operation, just like other letters that aren't conditional operators.


$ echo '.if z' | ./build/test-groff -ww -Tascii
troff:<standard input>:1: warning: missing closing delimiter in output comparison operator (got a newline)



G. Branden Robinson <gbranden>
Group administrator
Fri 17 Feb 2023 06:53:10 AM UTC, comment #1: 

I'm a bit dubious about this.  I have send elsewhere that I don't regard it as the groff manual's job to document other implementations in general.  It's important to cover CSTR #54 *roff for historical and portability reasons, our own differences and extensions, and recognition of the de facto portability of our extensions where convenient.

But the groff manual is there to document GNU troff (see bug #60061), not be the "Everything *roff Book".

However, of itself it's not a major change, and we have precedent in Plan 9 troff's `.S` register, so I'm not outright rejecting this.  Needs mulling over.

G. Branden Robinson <gbranden>
Group administrator
Fri 17 Feb 2023 04:55:09 AM UTC, original submission:  

Plan 9 (and by extension, plan9port and 9front) include a utility called htmlroff that adds a new single-character condition to its `.if`/`.ie` requests:

> Conditional input
> To make it easier to write input files that can be formatted by both troff and htmlroff, htmlroff adds a new condition h which evaluates true in .if and .ie requests. The t  condition continues to evaluate true, to accomodate input files trying to distinguish between troff and nroff. To write a conditional matching troff alone, use ‘*.if !h .if t*’.

Since groff(7)'s "Conditional expressions" section mentions the historical Vroff extension (`.if v`), it should probably also mention the unsupported htmlroff extension too (`.if h`), if only for completeness's sake.

John Gardner <alhadis>

 

(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 barx (Posted a comment)
  • -email is unavailable- added by gbranden (Posted a comment)
  • -email is unavailable- added by alhadis (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 10 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2023-03-31 gbranden StatusIn Progress Fixed
        Open/ClosedOpen Closed
    2023-03-22 gbranden CategoryGeneral Core
    2023-03-22 gbranden StatusReady for Merge In Progress
        Planned Release1.24.0 1.23.0
    2023-03-13 gbranden Assigned toNone gbranden
    2023-03-13 gbranden StatusIn Progress Ready for Merge
    2023-03-09 gbranden Planned ReleaseNone 1.24.0
    2023-03-05 gbranden StatusNone In Progress
    2023-02-17 gbranden Severity3 - Normal 1 - Wish

    Back to the top

    Powered by Savane 3.13-3230.
    Corresponding source code