bugGNU troff - Bugs: bug #58946, [ms] adapt to use the facilities...

 
 

bug #58946: [ms] adapt to use the facilities of pdfmark

Submitted by:  None
Submitted on:  Thu 13 Aug 2020 10:28:08 PM UTC
 
Category:  Macro ms Severity:  1 - Wish
Item Group:  Feature change Status:  None
Privacy:  Public Assigned to:  None
Open/Closed:  Open Planned Release:  None
* Mandatory Fields

Add a New Comment (Rich Markup)
   

Comment Type & Canned Response:
       No canned response available

 

( Jump to the original submission )

Thu 07 Oct 2021 02:47:58 PM UTC, comment #13: 

Arrrrgh!!!  Why can't savannah offer a sane UI, like OSDN?  Please ignore prematurely submitted comment #12, (which I seem to be unable to either edit, or delete)!

Here's what I wanted it to say:
comment #11:

> > I'm wondering if there may be some justification for incorporation of
> > simplified versions of [XH and XN], and maybe also a minimal default
> > implementation of "XH-UPDATE-TOC", within s.tmac?
> >
> > What do you think?
>
> I think "yes"!  Please go for it.  ...

I've attached two proposed patches; patch #52067 adds minimal implementations of XH and XN, (together with default implementations of ancillary hooks XH-INIT, XN-INIT, XH-UPDATE-TOC, XH-REPLACEMENT, and XN-REPLACEMENT), to s.tmac, while patch #52069 removes the default XH-INIT, XN-INIT, and XH-UPDATE-TOC implementations from spdf.tmac, (adopting those from s.tmac), and reimplements XH, and XN indirectly, in spdf.tmac, using XH-REPLACEMENT and XN-REPLACEMENT respectively, rather than redefining XH and XN directly.

In s.tmac, I've preserved the same calling syntax for XH, XN, and XH-UPDATE-TOC, as I originally specified in spdf.tmac, (and as outlined in comment #10), except that the -N, -S, and -X options are unsupported, for XH and XN; I have retained <outline-level> as a mandatory argument to XH-UPDATE-TOC, (even though the default implementation in s.tmac ignores it), since it is an essential component of the interface design.

I did agonize, for some time, over the default implementation of XH, (specifically, how it should be protected against use before SH); I eventually decided that, unlike the misuse of XN before NH, no such protection is actually necessary.

Keith Marshall <keithmarshall>
Project Member
Thu 07 Oct 2021 01:19:15 PM UTC, comment #12: 

comment #11:

> > I'm wondering if there may be some justification for incorporation of simplified versions of [XH and XN], and maybe also a minimal default implementation of "XH-UPDATE-TOC", within s.tmac?
> >
> > What do you think?
>
> I think "yes"!  Please go for it.  ...

I've attached two proposed patches; file # adds minimal implementations of XH and XN, (together with default implementations of ancillary hooks XH-INIT, XN-INIT, XH-UPDATE-TOC, XH-REPLACEMENT, and XN-REPLACEMENT), to s.tmac; file #

(file #52067)

Keith Marshall <keithmarshall>
Project Member
Sun 03 Oct 2021 11:12:20 AM UTC, comment #11: 

Hi, Keith!

Yes, I like your proposal for two reasons.

1. As I was porting my updates from groff_ms(7) to doc/ms.ms (whence the language about the "Groff and Friends HOWTO" originates), I found myself wincing pretty hard.  I thought to myself, "why don't we just offer the user a pre-rolled solution to this straightforward problem"?  I also learned things about the .XA macro that I never knew because no one had really documented then.  (They're in groff_ms(7) now.)

[I haven't pushed my changes to doc/ms.ms yet--I got distracted because I finally felt equal to the task of stomping bug #61266.]

2. Dean Allen Provins's "Groff and Friends HOWTO" doesn't seem like a bad document but it has not been updated in literally 20 years.  Even slow-moving groff has developed in that time, mostly thanks to Werner, Deri, and you.  Moreover, the document is broad-reaching and while I haven't perused it, I'm pretty nervous about the diverse and deep potential for outdated advice.

> I'm wondering if there may be some justification for incorporation of simplified versions of each of these, and maybe also a minimal default implementation of "XH-UPDATE-TOC", within s.tmac?


> What do you think?


I think "yes"!  Please go for it.  It drives me crazy that we're advising people to violate the DRY principle with respect to section headings and, worse, to count tabs.

Simplified is good, and if you have hooks in these simplified versions such that additional features and coolness and PDF-enhancements spring to life when -mspdf is specified, that's great!

The only thing I would ask--and it may not be relevant as I have little familiarity with pdfmark and spdf--is to not wall up external hyperlink support behind the PDF device.  As you probably saw on the groff development list, the planets are coming into alignment for a generalized, cross-device hyperlinking facility.

I don't, however, see at this point any way to enable within-document anchors and links for terminal devices.  I'm sure it's not impossible, given things like addressable scrollback buffers in terminal emulators and less(1)'s existing ability to seek its input stream, but at present I know of no way to tell a terminal how to place an anchor, so there's nothing to navigate to.  So that is a problem for another day, and for people like Egmont Koblinger who have many tentacles to spare for terminal emulation and pager development communities.

I apologize if that digresses from anything you have in mind.

Regards,
Branden

G. Branden Robinson <gbranden>
Project Administrator
Sun 03 Oct 2021 10:20:31 AM UTC, comment #10: 

I have now reworked spdf.tmac, to incorporate only those macros identified in comment #9 as "necessary"; I have included a completely reworked implementation of "XN", (which also serves as a new "XH" macro, courtesy of groff's .als mechanism).

As now implemented, the "XH" and "XN" macros conform to the following calling syntax:

.SH
.XH [-option ...] <outline-level> <heading-text> ...

.NH <outline-level>
.XN [-option ...] <heading-text> ...

In both cases, the permitted options are:

-N <name>   Place a pdfhref destination mark, with the given name,
            at the location of this heading.

-S          Sanitize <heading-text> (by removal of "\F" escapes)
            for use in the PDF document outline.

-X          Create a pdfhref cross-reference dictionary entry for
            this heading; use the destination name specified by
            -N <name>, if given, or the first word taken from
            <heading-text> if not.

Both of these new macro implementations ("XH" and "XN") reproduce their <heading-text> argument(s) as running text, in the appropriate heading font/size, and as PDF document outline entries, at the specified <outline-level>, and sanitized as required.  Neither creates a TOC entry, by default; however, each invokes a pair of callback hooks:

XH-INIT
XN-INIT
   Called on entry to XH, and XN respectively; by default, each is
   a no-op, but either, or both, may be redefined by the user, to
   perform any respective initialization, for use by:

XH-UPDATE-TOC <outline-level> [<section-number>] <heading-text>
   Called by both XH and XN, (the <section-number> argument is
   omitted, when called by XH, and always present, when called by
   XN); once again, this is a no-op by default, but may be redefined
   by the user, to generate TOC entries.

As I had previously observed in comment #4, neither this implementation of "XN", nor its new "XH" sibling, is an appropriate candidate for inclusion in s.tmac; however, given this statement in the groff online manual (not reproduced in groff_ms(7)):

The Groff and Friends HOWTO includes a sed script that automatically inserts XS and XE macro entries after each heading in a document.

Altering the NH macro to automatically build the table of contents is perhaps initially more difficult, but would save a great deal of time in the long run if you use ms regularly.

and given that "XH" and "XN" can facilitate linking of TOC entries to section headings, I'm wondering if there may be some justification for incorporation of simplified versions of each of these, and maybe also a minimal default implementation of "XH-UPDATE-TOC", within s.tmac?

What do you think?

Keith Marshall <keithmarshall>
Project Member
Fri 27 Aug 2021 08:28:52 PM UTC, comment #9: 

Ignoring those intended exclusively for internal use, (which I've elided from the following), in spdf.tmac I see:

$ hg grep -r qparent '^\. *de ' spdf.tmac
contrib/pdfmark/spdf.tmac:5357:.de OMIT OMIT
contrib/pdfmark/spdf.tmac:5357:...
contrib/pdfmark/spdf.tmac:5357:.de XM
contrib/pdfmark/spdf.tmac:5357:.de XR
contrib/pdfmark/spdf.tmac:5357:.de XN
contrib/pdfmark/spdf.tmac:5357:...
contrib/pdfmark/spdf.tmac:5357:.de LU
contrib/pdfmark/spdf.tmac:5357:.de AN
contrib/pdfmark/spdf.tmac:5357:...
contrib/pdfmark/spdf.tmac:5357:.de OP
contrib/pdfmark/spdf.tmac:5357:.de NN
contrib/pdfmark/spdf.tmac:5357:...
contrib/pdfmark/spdf.tmac:5357:.de PXREF
contrib/pdfmark/spdf.tmac:5357:.de IS
contrib/pdfmark/spdf.tmac:5357:.de IE
contrib/pdfmark/spdf.tmac:5357:.de TC
contrib/pdfmark/spdf.tmac:5357:...

Of these, OMIT, OP, and TC are required to support the partitioned document assembly mechanism of pdfroff.sh; as such, I would suggest that they should remain in spdf.tmac.

Of the remainder, perhaps only XN, (with modification), is worthy of consideration as a strictly necessary adjunct, and maybe XR as a convenient addition.  All of the rest are essentially redundant, and may even be worthless!  Here's what they do:

XN: sets its arguments as text, for use within the numbered heading following NH, additionally using the same text as the content of a PDF document outline entry, and within a TOC entry.  The modification, which I propose, is that formatting of the TOC entry should be delegated to a user-defined callback macro, (hence a document-local macro).  I also propose adding a complementary XH macro, serving a similar purpose following SH.

XR: creates a ".pdfhref L" reference to a named destination, using semantics similar to ms .B, or .I, with \$1 as the destination name, \$2 as argument to the pdfhref "-A" option, and \$3 as argument to "-P"; reference text is derived from the reference dictionary entry, created by ".pdfhref M".  If deemed worthy of retention, maybe consider modification, to allow additional arguments beyond \$3, to specify reference text.

XM: strict shorthand for ".pdfhref M -X".  Certainly not necessary.  If any user wants such shorthand, I think it really should be defined locally to their own document.

LU: surely not worthy of inclusion; it inserts an LP paragraph, stating — in English — that content is to be added at some unspecified future time!  Should be document-local, if wanted.

AN: inserts an SH heading, with default text "Note", but taking an optional argument to override that.  It originates from my workplace documents, where I used to introduce note, or warning annotations, or similar.  In hindsight, I think I should have made it document-local.

NN: a contraction of NH, followed by XN, with some added bells and whistles.  IIRC, I wrote this for one particular workplace document template; I definitely should have kept it local.

PXREF: a parenthetical variation of XR; should be document-local.

IS:
IE: utterly useless.  Do much the same as QS...QE, which should be used instead

Keith Marshall <keithmarshall>
Project Member
Fri 27 Aug 2021 04:42:28 PM UTC, comment #8: 

comment #7:

> Looks good to me--go for it!

Thanks, Branden,

It's currently sitting at 4th position, in my local patch queue; I'll push it, after I've dealt with the three which precede it.

Keith Marshall <keithmarshall>
Project Member
Sat 21 Aug 2021 01:13:14 AM UTC, comment #7: 

Hi, Keith.

Looks good to me--go for it!

G. Branden Robinson <gbranden>
Project Administrator
Tue 17 Aug 2021 10:08:59 PM UTC, comment #6: 

I'd like to add a hook, in s.tmac's @FS macro, to facilitate bidirectional pdfhref linking between the footnote mark (in running text), and the footnote itself.

Okay to apply, and commit, the attached patch?  Is FS-MARK an acceptable name for the hook macro?  (I was tempted to abuse the existing DEVTAG "namespace", but since this hook may not normally be expected to write tag information to the output device stream, that doesn't really seem appropriate).

Keith Marshall <keithmarshall>
Project Member
Wed 04 Aug 2021 02:31:30 PM UTC, comment #5: 

comment #4:

> Just one point of clarification:
>
> comment #3:
> > I merely cobbled the current incarnation of spdf.tmac
> > together, while writing pdfmark.ms; it became a conveinent
> > "dumping ground" for supplementary convenience macros, which I
> > used within pdfmark.ms, and in hindsight, would have been better
> > implemented as document-local macros.  XN is one such, (and one
> > which exhibits implementation failings, which I never managed to
> > successfully resolve); there are others, which could similarly
> > be considered for factoring out, as document-local macros.
>
> Document-level within pdfmark.ms, you mean?

Yes.

> Are the macros you speak of (XN, et al) not general-purpose
> enough to include in pdfmark.tmac?

Definitely not in pdfmark.tmac; that's substantially complete, as it stands, but it is what groff_tmac(5) dubs a "supplemental", or "auxiliary" macro set; it shouldn't be polluted by anything which is specific to any one of the "major", or "full-service" macro packages, of which "ms" is just one example.

Similarly, s.tmac shouldn't be made dependent on a stand-alone auxiliary macro set, on which it has no existing dependency; I contend that a binding package, such as spdf.tmac is the logical place to implement the interface.

Some of the stuff I shoved into spdf.tmac is nothing more than "syntactic sugar" — shorthand for features which pdfmark.tmac already supports adequately, with just a shorter "ms" style name.  Those, I would suggest, don't really deserve an existence beyond document-local scope — if we consider pdfmark.ms as an example, then that's where they belong.

That said, XN is one of the macros I dumped into spdf.tmac, which may be a candidate for remaining there — but not as it stands at present.  It exhibits flaws, which would need to be addressed; however, it does attempt to address an extant limitation of "ms" itself: NH, and SH, simply instruct roff to format the text which follows, up to the next following paragraph macro call, as a section heading.  There is no inherent provision to use any of that text, as the basis for a TOC entry, or as a PDF document outline entry, so the author is left repeating content, for the three contexts; XN, when used immediately after NH, attempts to address that limitation, by reproducing its arguments in each of those contexts, (including the section number generated by NH, in the TOC and PDF document outline contexts, a variant would be required, for use after SH).

Keith Marshall <keithmarshall>
Project Member
Wed 04 Aug 2021 02:36:53 AM UTC, comment #4: 

OK, if I'm reading you right, in the big picture, the existing ms/pdfmark macros are more prototype / proof of concept than production-level implementation.  If this is accurate, the current Summary is as good as any.

Just one point of clarification:

comment #3:

> I merely cobbled the current incarnation of spdf.tmac
> together, while writing pdfmark.ms; it became a conveinent
> "dumping ground" for supplementary convenience macros, which I
> used within pdfmark.ms, and in hindsight, would have been better
> implemented as document-local macros.  XN is one such, (and one
> which exhibits implementation failings, which I never managed to
> successfully resolve); there are others, which could similarly
> be considered for factoring out, as document-local macros.


Document-level within pdfmark.ms, you mean?  Are the macros you speak of (XN, et al) not general-purpose enough to include in pdfmark.tmac?  I'm wholly unfamiliar with pdfroff (and ms, for that matter), so this question is rooted in my fundamental ignorance.

> I've also observed some issues which may be best address
> within pdfmark.tmac, but these should likely be addressed by
> way of separate tickets).


Any issues you've come across, please do open tickets for them, so there's a full record of what remains to be done.

Dave <barx>
Project Member
Mon 26 Jul 2021 10:32:56 AM UTC, comment #3: 

comment #2:

> >> In the groff system, XN is defined in spdf.tmac
> >
> > Which, I would suggest, it should NOT be ....
> >
> > Since it is provided purely as an example, it has no place in
> > ANY of the standard macro packages; it would be more appropriate
> > to relocate it to an "examples" repository, and, in hindsight
> > I should have defined it directly within pdfmark.ms
>
> Keith, if this is the only task, I'll update this bug's Summary accordingly.  (Probably the summary needs to be updated anyway, since your post implies the bulk of the work for integrating ms and pdfmark is done, with merely some housekeeping left to take care of.)


I never really intended spdf.tmac as anything more than an example of — or potentially, a foundation for — development of bindings for use of pdfmark.tmac in conjunction with some other document formatting macro package ... s.tmac, in this particular case.  Just as POSIX extends ISO-C, with the extensions normally being implemented through supplementary header files and libraries, pdfmark.tmac extends s.tmac, (and potentially other macro packages which offer similar functionality to s.tmac); spdf.tmac provides the supplementary "glue" to bind pdfmark.tmac features to s.tmac, but nothing within spdf.tmac really belongs as an integral part of s.tmac itself.

That said, I merely cobbled the current incarnation of spdf.tmac together, while writing pdfmark.ms; it became a conveinent "dumping ground" for supplementary convenience macros, which I used within pdfmark.ms, and in hindsight, would have been better implemented as document-local macros.  XN is one such, (and one which exhibits implementation failings, which I never managed to successfully resolve); there are others, which could similarly be considered for factoring out, as document-local macros.

So yes, spdf.tmac could definitely benefit from some housekeeping, before formal adoption as a binding between s.tmac and pdfmark.tmac; s.tmac itself should require no associated modification.  (I left pdfmark.ms very much incomplete, so that will require some further attention; I've also observed some issues which may be best address within pdfmark.tmac, but these should likely be addressed by way of separate tickets).

Keith Marshall <keithmarshall>
Project Member
Mon 26 Jul 2021 08:24:53 AM UTC, comment #2: 

OK, now that I've bothered to read the entire message I just linked to, there appears to be at least one task on the ms/pdfmark to-do list:

>> In the groff system, XN is defined in spdf.tmac
>
> Which, I would suggest, it should NOT be ....
>
> Since it is provided purely as an example, it has no place in
> ANY of the standard macro packages; it would be more appropriate
> to relocate it to an "examples" repository, and, in hindsight
> I should have defined it directly within pdfmark.ms


Keith, if this is the only task, I'll update this bug's Summary accordingly.  (Probably the summary needs to be updated anyway, since your post implies the bulk of the work for integrating ms and pdfmark is done, with merely some housekeeping left to take care of.)

Dave <barx>
Project Member
Mon 26 Jul 2021 08:04:14 AM UTC, comment #1: 

Keith posted more discussion germane to this: http://lists.gnu.org/archive/html/groff/2021-07/msg00103.html

In particular, he notes that, while pdfmark functionality was never rolled into -ms itself, he doesn't believe it should be.  Thus the current -mspdf may be the preferred solution, and nothing more may need to be done for -ms.  Keith, is this an accurate synopsis?

Dave <barx>
Project Member
Thu 13 Aug 2020 10:28:08 PM UTC, original submission:  

Keith Marshall observes that "use of a macro set which has not been adapted to use the facilities of pdfmark" means that links are not clickable when rendering to PDF.

He goes on to say, "When I wrote pdfmark, I provided a small wrapper for -ms, to illustrate how the ms macros might be adapted, but I didn't modify ms itself, and I left it as an exercise for others, to adapt other macro sets.  AFAIK, that never happened."

Anonymous

 

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

Attach Files:
   
   
Comment:
   

Attached Files
file #52069:  spdf-xh-xn-update.patch added by keithmarshall (3KiB - text/x-patch - Adapt spdf.tmac XH/XN implementation to integrate with s.tmac)
file #52067:  ms-xh-xn-implementation.patch added by keithmarshall (6KiB - text/x-patch - Basic XH/XN implementation in s.tmac)
file #51795:  ms-footnote-marker-hook.patch added by keithmarshall (1KiB - text/x-patch - Patch to add a footnote marker placement hook; required to facilitate bidirectional pdfhref linking of footmark markers.)

 

Depends on the following items: None found

Digest:
   bug dependencies.

 

Carbon-Copy List
  • -email is unavailable- added by keithmarshall (Posted a comment)
  • -email is unavailable- added by barx
  • -email is unavailable- added by barx (Posted a comment)
  • -email is unavailable- added by gbranden (Updated 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 9 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2021-11-02 keithmarshall Assigned tokeithmarshall => None
    2021-10-07 keithmarshall Attached File- => Added spdf-xh-xn-update.patch, #52069
    2021-10-07 keithmarshall Attached File- => Added ms-xh-xn-implementation.patch, #52067
    2021-09-25 keithmarshall Dependencies- => bugs #60927 is dependent
    2021-08-21 gbranden Assigned toNone => keithmarshall
    2021-08-17 keithmarshall Attached File- => Added ms-footnote-marker-hook.patch, #51795
    2021-07-26 barx Carbon-Copy- => Added keithmarshall
    2021-04-30 gbranden Severity3 - Normal => 1 - Wish
        Summaryadapt -ms to use the facilities of pdfmark => [ms] adapt to use the facilities of pdfmark

    Back to the top


    Powered by Savane 3.9