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

[G. Branden Robinson]

Update of bug #61022 (project groff):

 Planned Release:  1.23.0 => None   

___

Follow-up Comment #8:

In the meantime, FP needs a new name--AT 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
macro, but I do plan to alias it (along with other AT 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 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...

___

Reply to this item at:

  

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

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

[Keith Marshall]

Update of bug #61022 (project groff):

 Planned Release:None => 1.23.0 

___

Follow-up Comment #7:

Hi Branden,

As discussed on [bug #61157 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.

___

Reply to this item at:

  

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

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

[Keith Marshall]

Follow-up Comment #6, bug #61022 (project groff):

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)
___

Additional Item Attachment:

File name: ms-fp-manpage.patchSize:2 KB




___

Reply to this item at:

  

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

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

[Keith Marshall]

Follow-up Comment #5, bug #61022 (project groff):

Hi Branden,

On [bug #61157 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)
___

Additional Item Attachment:

File name: ms-fs-mark-manpage.patch   Size:0 KB
   




___

Reply to this item at:

  

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

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

[G. Branden Robinson]

Follow-up Comment #4, bug #61022 (project groff):

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?

___

Reply to this item at:

  

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

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

[Keith Marshall]

Follow-up Comment #3, bug #61022 (project groff):

[comment #2 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.

___

Reply to this item at:

  

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

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

[Keith Marshall]

Follow-up Comment #2, bug #61022 (project groff):

[comment #1 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).

___

Reply to this item at:

  

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

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

[G. Branden Robinson]

Update of bug #61022 (project groff):

  Status:None => Need Info  
 Assigned to:None => gbranden   
 Summary: [ms]: Documention neglects to mention FP macro =>
[ms] documention neglects to mention FP macro

___

Follow-up Comment #1:

Hi, Keith!

[comment #0 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?

___

Reply to this item at:

  

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

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

[Keith Marshall]

URL:
  

 Summary: [ms]: Documention neglects to mention FP macro
 Project: GNU troff
Submitted by: keithmarshall
Submitted on: Sat 07 Aug 2021 09:31:22 PM UTC
Category: Macro - ms
Severity: 3 - Normal
  Item Group: Documentation
  Status: None
 Privacy: Public
 Assigned to: None
 Open/Closed: Open
 Discussion Lock: Any
 Planned Release: None

___

Details:

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.




___

Reply to this item at:

  

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