bugGNU roff - Bugs: bug #61022, [ms] documention neglects to...

 
 

bug #61022: [ms] documention neglects to mention FP macro

Submitter:  Keith Marshall <keithmarshall>
Submitted:  Sat 07 Aug 2021 09:31:22 PM UTC
   
 
Category:  Macro ms Severity:  3 - Normal
Item Group:  Documentation Status:  Need Info
Privacy:  Public Assigned to:  gbranden
Open/Closed:  Open Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Jump to the original submission

Tue 01 Feb 2022 09:23:00 PM UTC, comment #8: 

In the meantime, FP needs a new name--AT&T already seized it in the early 1980s.

8th edition ms(7) says:

> FP
> Set font positions for a family, e.g., "FP palatino"


This doesn't elucidate much, and I certainly don't plan to implement the AT&T macro, but I do plan to alias it (along with other AT&T macros we don't support) to `@not-implemented`.

The next most mnemonic choice would probably be `PF`, but that's already (relatively) well known as a pic(1) boundary macro.  Also see bug #60558.

If no one has a better idea, I propose `FF`.  This is not taken as a macro name (it is as a register), and AT&T doesn't squat on it either.

Although I do see that 4.2BSD added an `FP` macro for the exact purpose you're using it.

Well, great.  :-/  I really don't want to have to support "ATT" vs. "BSD" modes but suddenly this looks more likely...

G. Branden Robinson <gbranden>
Group administrator
Fri 01 Oct 2021 11:02:37 AM UTC, comment #7: 

Hi Branden,

As discussed on ticket #61157, I've pushed the two attached patches, (folded into one).  I'll leave it to you, to review the manpage updates, handle info integration — I'm clueless, when it comes to writing texinfo — and close at your discretion.

Keith Marshall <keithmarshall>
Group Member
Mon 20 Sep 2021 09:19:26 AM UTC, comment #6: 

As an adjunct to my tentative proposal for FS-MARK documentation, previously attached, I've further produced a tentative update to the groff_ms(7) manpage, to document FP; this is now also attached.

(file #51947)

Keith Marshall <keithmarshall>
Group Member
Mon 20 Sep 2021 08:26:56 AM UTC, comment #5: 

Hi Branden,

On ticket #61157, you added an incidental comment:

> ... I intended to document FS-MARK but found myself confused with respect to use cases.  I'll follow up with you about that elsewhere since it's off-topic for this ticket.

to which I replied that it would be appropriate to discuss it here.

The use-case, which I had identified at the time when I proposed the FS-MARK callback hook, arose out of difficulties I was experiencing when trying to create pdfhref links between footnote markers in body text, and the footnote itself; it is basically an adaptation of the sample technique I illustrated in comment #3, with a document-local redefinition of FS-MARK replacing my original pdf:fn.mark macro, and obviating the need to redefine @FS:

.ds * \c
.de FS-MARK
.\" Macro to replace original duty performed by "\**"; invoked by
.\" callback from FS, BEFORE recording of the associated text within
.\" the footnote diversion is commenced.
.\"
.ie \\n[.$] \{\
.   pdfhref L -D pdf:fn\\$1 -- \*{\\$1\*}
.   pdfhref M -N pdf:fn\\$1r
.   \}
.\"
.\" Reference to this undocumented s.tmac counter is unfortunate, but
.\" I don't see an alternative, when "\**" no longer updates it; maybe
.\" s.tmac could expose a more suitable (documented) alias.
.\"
.el .\\$0 \\n+[fn*text-num]
..
.de FP
.\" Override s.tmac's (undocumented) footnote output hook; this emulates
.\" the default output style for \n[FF] == 3 footnotes, with the footnote
.\" number formatted as a pdfhref link back to the position at which the
.\" footnote marker appears, within the document text.
.\"
.@LP
.ds pdf:fn.tag \s'-1.5p'\\$1.\s'+1.5p'
.nr pdf:fn.tag.width (u;\\n[\\n[.ev]:PI]*2)
.pdfhref M -N pdf:fn\\$1
.in +\\n[pdf:fn.tag.width]u
.ti -\\n[pdf:fn.tag.width]u
.nr pdf:fn.tag.width -\\w'\\*[pdf:fn.tag]'u
.pdfhref L -D pdf:fn\\$1r -A \\h'\\n[pdf:fn.tag.width]u'\c -- \\*[pdf:fn.tag]
..

I've since discovered that I can achieve the same effect, by redefining the "*" string, without requiring the FS-MARK callback hook, but the redefinition is messy, and far from intuitive, so I believe the callback is still justified.  If it helps, I've attached a tentative manpage patch, to document it.

You may note that a reference to the (undocumented) ms internal register, fn*-ext-num is still present in the above sample code; I'm still exploring possibilities for avoiding that.

(file #51946)

Keith Marshall <keithmarshall>
Group Member
Fri 13 Aug 2021 03:01:44 PM UTC, comment #4: 

Thanks, Keith.  You've presented a solid use case for .FP, I think.

The other thing that bugs me about footnote paragraphing is how elaborate the semantics of FF 0 are.  The paragraph is indented unless there's nothing to indent it with.  This is compatible with Heirloom Doctools troff and I suppose it makes sense for that sort of specialized, first-page-only footnote that doesn't have a marker but instead serves as some sort of acknowledgement in some academic/journal styles.  But if it's that specialized, I don't see the harm in telling people to set FF to 2 for that unique, marker-less footnote and change to another format for all other footnotes if desired.

I'm sort of tempted to simplify it and make the correspondence between footnote formats and paragraph styles explicit.

0,1 PP
2   LP
3   IP

What do you think?

G. Branden Robinson <gbranden>
Group administrator
Thu 12 Aug 2021 04:27:45 PM UTC, comment #3: 

comment #2:

> To achieve a viable mechanism for implementing the forward footnote links, I think we need to a) redefine "\**" as "\c", and b) provide a hook within "FS", (which then cannot be separated from the mark location), to manage the counter, and plant the mark as a pdfhref link.  For the reverse link, we would need a complementary hook within what is currently "FP", (whether that name is retained, or some alternative is substituted).

To illustrate my point, here's a document-local change, which I have added to my working copy of pdfmark.ms:

.\" Redefine the FS macro (from s.tmac) to facilitate the placement of
.\" footnote reference marks, with each serving as a pdfhref link to the
.\" associated footnote itself.
.\"
.\" FIXME: This may be a candidate for inclusion in spdf.tmac; (note that,
.\" when defining it before the first page has begun, we must refer to the
.\" s.tmac internal name, "@FS", rather than to FS itself; better still,
.\" rather than any redefinition of @FS, would be a hook in the s.tmac
.\" implementation itself, to which pdf:fn.mark could be attached).
.\"
.rn * pdf:*
.rn @FS pdf:fn.record
.ds * \c
.de pdf:fn.mark
.\" Macro to replace original duty performed by "\**"; must be invoked
.\" at point of footnote mark placement, e.g. by FS, BEFORE recording of
.\" the associated text within the footnote diversion is commenced.
.\"
.ie \\n[.$] \{\
.   pdfhref L -D pdf:fn\\$1 -- \*{\\$1\*}
.   pdfhref M -N pdf:fn\\$1r
.   \}
.\"
.\" Reference to this undocumented s.tmac counter is unfortunate, but
.\" I don't see an alternative, when "\**" no longer updates it; maybe
.\" s.tmac could expose a more suitable (documented) alias.
.\"
.el .\\$0 \\n+[fn*text-num]
..
.de @FS
.\" Replacement for default FS payload implementation; handles footnote
.\" mark placement, as specified above, before recording the content of
.\" the footnote itself.
.\"
.pdf:fn.mark
.pdf:fn.record
..
.de FP
.\" Override s.tmac's (undocumented) footnote output hook; this emulates
.\" the default output style for \n[FF] == 3 footnotes, with the footnote
.\" number formatted as a pdfhref link back to the position at which the
.\" footnote marker appears, within the document text.
.\"
.@LP
.ds pdf:fn.tag \s'-1.5p'\\$1.\s'+1.5p'
.nr pdf:fn.tag.width (u;\\n[\\n[.ev]:PI]*2)
.pdfhref M -N pdf:fn\\$1
.in +\\n[pdf:fn.tag.width]u
.ti -\\n[pdf:fn.tag.width]u
.nr pdf:fn.tag.width -\\w'\\*[pdf:fn.tag]'u
.pdfhref L -D pdf:fn\\$1r -A \\h'\\n[pdf:fn.tag.width]u'\c -- \\*[pdf:fn.tag]
..

Note that, to successfully inject the necessary pdfhref requests, at appropriate locations, I need to redefine "@FS" and "FP", neither of which is formally documented, in addition to "\**", which is.

Keith Marshall <keithmarshall>
Group Member
Wed 11 Aug 2021 10:39:38 PM UTC, comment #2: 

comment #1:

> It certainly does seem like it was intended for a hook.  The implementation dates back to the dawn of repo time.
>


> ^351da0dc macros/tmac.s (James Clark          1991-06-02 04:20:34 -0500 1582) .de FP
> ^351da0dc macros/tmac.s (James Clark          1991-06-02 04:20:34 -0500 1583) .br
> ^351da0dc macros/tmac.s (James Clark          1991-06-02 04:20:34 -0500 1584) .if !d par*fp!\\n[FF] \{\
> 1294c8d22 tmac/s.tmac   (G. Branden Robinson  2017-11-18 17:55:26 -0500 1585) . @error unknown footnote format '\\n[FF]'
> ^351da0dc macros/tmac.s (James Clark          1991-06-02 04:20:34 -0500 1586) . nr FF 0
> ^351da0dc macros/tmac.s (James Clark          1991-06-02 04:20:34 -0500 1587) .\}
> ^351da0dc macros/tmac.s (James Clark          1991-06-02 04:20:34 -0500 1588) .ie '\\$2'no' .par*fp!\\n[FF]-no "\\$1"
> ^351da0dc macros/tmac.s (James Clark          1991-06-02 04:20:34 -0500 1589) .el .par*fp!\\n[FF] "\\$1"
> ^351da0dc macros/tmac.s (James Clark          1991-06-02 04:20:34 -0500 1590) ..


>
> ...but we've gotten along for 30 years without exposing it in documentation...do we really need it?  Is it worth the clash with Plan 9?  (Although I have to say, using any amount of API on the ultra-legacy font mounting position feature seems like a waste to me.)
>
> You certainly don't need .FP to do paragraphing within a footnote; the normal ones work fine.

They do, until you need some sort of hook, to implement pdfhref links from the footnote mark, to the footnote text, and back again!

> Do you agree?  Should the comment be rewritten, maybe?

Well, the current support for footnotes, in s.tmac, is already inconsistent with Mike Lesk's original implementation; he didn't have the "\**" string, and there was no requirement for any similar construct, planted before ".FS", to manage the footnote counter.

Some background may be helpful.  I'm looking at pdfmark.ms, (which I've left in a rather unsatisfactory state of incompletion for way too long).  At the bottom of page 2, (the introduction), are five footnotes; two of them are linked, (from the mark to the footnote, but not back).  Implementing even those two forward links was a pain; "\**" itself is an impediment, because it defies any attempt to wrap it as a pdfhref link, unless I abandon use of its string invocation, in the manner it is documented.

To achieve a viable mechanism for implementing the forward footnote links, I think we need to a) redefine "\**" as "\c", and b) provide a hook within "FS", (which then cannot be separated from the mark location), to manage the counter, and plant the mark as a pdfhref link.  For the reverse link, we would need a complementary hook within what is currently "FP", (whether that name is retained, or some alternative is substituted).

Keith Marshall <keithmarshall>
Group Member
Wed 11 Aug 2021 03:16:31 PM UTC, comment #1: 

Hi, Keith!

original submission:

> Internally, groff's s.tmac defines a macro called "FP", and uses it to control the printing of footnotes.  At the point of definition, I see:
>


> .\" This can be redefined. It gets a second argument of 'no' if the
> .\" first argument was supplied by the user, rather than automatically.
> .de FP
> ...


>
> To me, this suggests that the intention is to provide a hook, (albeit inconsistent with other ms implementations — e.g. Plan-9's ms manpage documents an FP macro associated with font positions), whereby the user may choose to modify the appearance of footnotes, yet the documentation (neither manpage, nor info) has absolutely no mention of it.


It certainly does seem like it was intended for a hook.  The implementation dates back to the dawn of repo time.


^351da0dc macros/tmac.s (James Clark          1991-06-02 04:20:34 -0500 1582) .de FP
^351da0dc macros/tmac.s (James Clark          1991-06-02 04:20:34 -0500 1583) .br
^351da0dc macros/tmac.s (James Clark          1991-06-02 04:20:34 -0500 1584) .if !d par*fp!\\n[FF] \{\
1294c8d22 tmac/s.tmac   (G. Branden Robinson  2017-11-18 17:55:26 -0500 1585) . @error unknown footnote format '\\n[FF]'
^351da0dc macros/tmac.s (James Clark          1991-06-02 04:20:34 -0500 1586) . nr FF 0
^351da0dc macros/tmac.s (James Clark          1991-06-02 04:20:34 -0500 1587) .\}
^351da0dc macros/tmac.s (James Clark          1991-06-02 04:20:34 -0500 1588) .ie '\\$2'no' .par*fp!\\n[FF]-no "\\$1"
^351da0dc macros/tmac.s (James Clark          1991-06-02 04:20:34 -0500 1589) .el .par*fp!\\n[FF] "\\$1"
^351da0dc macros/tmac.s (James Clark          1991-06-02 04:20:34 -0500 1590) ..


...but we've gotten along for 30 years without exposing it in documentation...do we really need it?  Is it worth the clash with Plan 9?  (Although I have to say, using any amount of API on the ultra-legacy font mounting position feature seems like a waste to me.)

You certainly don't need .FP to do paragraphing within a footnote; the normal ones work fine.

Input:


.LP
We will illustrate why we don't need an
.CW FP
macro.\**
.FS
Two software releases were considered for this report.
.PP
The first is commercial software;
the second is free.
.IP \[bu]
Microsoft Word for Windows,
starting with version 1.0 through the current version
(Word 2000).
.IP \[bu]
GNU Emacs,
from its first appearance as a standalone editor through the
current version (v20).
See [Bloggs 2002] for details.
.QP
Franklin's Law applied to software:
software expands to outgrow both RAM and disk space over time.
.XP
Bloggs, Joseph R.,
.I "Everyone's a Critic" ,
Underground Press, March 2002.
A definitive work that answers all questions and criticisms
about the quality and usability of free software.
.LP
And here's a left-aligned paragraph for fun.
.FE


Output:

$ ./build/test-groff -Tutf8 -ms EXPERIMENTS/FP.ms | cat -s

We will illustrate why we don’t need an FP macro.[1]

───────────
  [1] Two  software  releases  were considered for this
report.
  The first is commercial software; the second is free.
• Microsoft Word for Windows, starting with version 1.0
  through the current version (Word 2000).
• GNU  Emacs, from its first appearance as a standalone
  editor  through  the  current  version  (v20).    See
  [Bloggs 2002] for details.
     Franklin’s  Law applied to software: software
     expands to outgrow both RAM  and  disk  space
     over time.
Bloggs,  Joseph  R.,  Everyone’s  a Critic, Underground
  Press, March 2002.  A definitive  work  that  answers
  all  questions  and  criticisms about the quality and
  usability of free software.
And here’s a left‐aligned paragraph for fun.


Do you agree?  Should the comment be rewritten, maybe?

G. Branden Robinson <gbranden>
Group administrator
Sat 07 Aug 2021 09:31:22 PM UTC, original submission:  

Internally, groff's s.tmac defines a macro called "FP", and uses it to control the printing of footnotes.  At the point of definition, I see:


.\" This can be redefined. It gets a second argument of 'no' if the
.\" first argument was supplied by the user, rather than automatically.
.de FP
...


To me, this suggests that the intention is to provide a hook, (albeit inconsistent with other ms implementations — e.g. Plan-9's ms manpage documents an FP macro associated with font positions), whereby the user may choose to modify the appearance of footnotes, yet the documentation (neither manpage, nor info) has absolutely no mention of it.

Keith Marshall <keithmarshall>
Group Member

 

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

Attach Files:
   
   
Comment:
   

Attached Files
file #51947:  ms-fp-manpage.patch added by keithmarshall (2KiB - text/x-patch - Tentative groff_ms(7) update to document FP)
file #51946:  ms-fs-mark-manpage.patch added by keithmarshall (911B - text/x-patch - Tentative groff_ms(7) update to document FS-MARK)

 

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 keithmarshall (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
    2022-02-01 gbranden Planned Release1.23.0 None
    2021-10-01 keithmarshall Planned ReleaseNone 1.23.0
    2021-09-20 keithmarshall Attached File- Added ms-fp-manpage.patch, #51947
    2021-09-20 keithmarshall Attached File- Added ms-fs-mark-manpage.patch, #51946
    2021-08-11 gbranden StatusNone Need Info
        Assigned toNone gbranden
        Summary[ms]: Documention neglects to mention FP macro [ms] documention neglects to mention FP macro

    Back to the top

    Powered by Savane 3.13-758e.
    Corresponding source code