bugGNU roff - Bugs: bug #64278, [ms] want info on pdfswitchtopage...

 
 

bug #64278: [ms] want info on pdfswitchtopage for potential TOC relocation

Submitter:  Michał Kruszewski <mkru>
Submitted:  Sat 03 Jun 2023 04:59:50 PM UTC
   
 
Category:  Macro package ms Severity:  3 - Normal
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

Thu 22 Jun 2023 01:13:21 AM UTC, comment #7: 


commit 1b2b6c8c0fbde674eb898180cb5d4905be7a352e
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Wed Jun 21 20:04:23 2023 -0500

    [ms]: Advise users of PDF and tables of contents.

    [ms]: Offer advice to users of PDF who want a table of contents at the
    front of the document.

    * doc/groff.texi (ms Document Structure): Move mention of pdfjam(1) from
      here...

      (ms TOC): ...to here, and identify alternatives, including gropdf(1)'s
      `pdfswitchtopage` macro.

    * doc/ms.ms (General structure of an ms document):
      (Creating a table of contents): Similar.

    Fixes <https://savannah.gnu.org/bugs/?64278>.  Thanks to Michał
    Kruszewski for the report.


G. Branden Robinson <gbranden>
Group administrator
Thu 22 Jun 2023 12:54:08 AM UTC, comment #6: 


comment #5:

> 'switchtopage' seems to be clear. Can't we add in the "Table of contents" in groff_ms(7) something like "In the case of pdf target 'swtichtopage' can be used to relocate TOC, see gropdf(1) for more details."?


In principle we could add anything to any page, but there has to be a limiting principle, or everything will be documented everywhere and the documentation will grow without bound.

I'm reluctant to add something to the groff_ms(7) man page, as that is meant to be a reference for those already familiar with the package.  However, your suggestion is well-taken for more tutorial materials, like the "ms.ms" document Larry Kollar and I have developed, and which (for this release), is duplicated in our Texinfo manual.

I'm attaching a PostScript version of the ms.ms document so you can see if it fulfills your needs.  See page 21 specifically.

In the longer term, I am hopeful that these suggestions for page resequencing will become unnecessary, as "pdfmark" features become better integrated into each macro package instead of relying upon explicit loads of an auxiliary package, and a wrapper script, to exercise them.

(file #54859)

G. Branden Robinson <gbranden>
Group administrator
Sat 03 Jun 2023 05:37:11 PM UTC, comment #5: 

'switchtopage' seems to be clear. Can't we add in the "Table of contents" in groff_ms(7) something like "In the case of pdf target 'swtichtopage' can be used to relocate TOC, see gropdf(1) for more details."?

Michał Kruszewski <mkru>
Sat 03 Jun 2023 05:21:55 PM UTC, comment #4: 

comment #3:

> I think the problem is that groff_ms(7) does not mention that switchtopage exists and does not direct a user to the gropdf(1).
> Relocating TOC to the beginning is de facto the standard nowadays.
> If I were a newbie trying groff, no way I would get an idea that a macro with such functionality can be documented in the gropdf(1). groff_ms(7) does not even mention gropdf.


That is regrettably true.  Adding full support for PDF features is an existing issue; see bug #58946.  We've got some but not all of the pieces in place for it.  This is true of our full-service macro packages in general (and tickets are open for them), except for mom(7).

Are you satisfied with the current documentation of the 'switchtopage' feature in gropdf(1) itself?  If so, I will resolve this ticket.

G. Branden Robinson <gbranden>
Group administrator
Sat 03 Jun 2023 05:17:36 PM UTC, comment #3: 

I think the problem is that groff_ms(7) does not mention that switchtopage exists and does not direct a user to the gropdf(1).
Relocating TOC to the beginning is de facto the standard nowadays.
If I were a newbie trying groff, no way I would get an idea that a macro with such functionality can be documented in the gropdf(1). groff_ms(7) does not even mention gropdf.

Michał Kruszewski <mkru>
Sat 03 Jun 2023 05:11:05 PM UTC, comment #2: 

Actually a lot of this language came in a few years ago, so it's in all the 1.23.0 release candidates, too.


commit 14c4fd87810427f1240a18c69ef63414087de028
Author: Deri James <deri@chuzzlewit.myzen.co.uk>
Date:   Sun Dec 29 22:16:17 2019 +0000

    Update man page of gropdf to document \X calls.

    * src/devices/gropdf/gropdf.1.man: The calls 'pagname' and
      'switchtopage' (used by mom to relocate TOC) are documented,
      together with their convenience commands '.pdfpagename' and
      '.pdfswitchtopage'.


G. Branden Robinson <gbranden>
Group administrator
Sat 03 Jun 2023 05:09:03 PM UTC, comment #1: 

This may be already fixed in the master branch.


    \X'pdf: switchtopage when name'
        Normally each new page is appended to the end of the document,
        this command allows following pages to be inserted at a `named'
        position within the document (see pagename command above).
        `when' can be either `after' or `before'.  If it is omitted it
        defaults to `before'.  It should be used at the end of the page
        before you want the switch to happen.  This allows pages such as
        a TOC to be moved to elsewhere in the document, but more
        esoteric uses are possible.  The convenience macro for this
        command is .pdfswitchtopage.


Does the foregoing suit your needs?

G. Branden Robinson <gbranden>
Group administrator
Sat 03 Jun 2023 04:59:50 PM UTC, original submission:  

pdf.tmac provides pdfswitchtopage macro that can potentially be used to relocate TOC. groff_ms(7) mentions only pdfjam. In my humble opinion the manual page should also mention pdfswitchtopage. Unfortunately there is no man for groff_pdf.

It is weird that external program such as pdfjam with heavy dependency on tex is mentioned, but the native way `pdfswitchtopage` is almost impossible to find as it appears only in the pdf.tmac file.

Michał Kruszewski <mkru>

 

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

Attach Files:
   
   
Comment:
   

Attached Files
file #54859:  ms.ps added by gbranden (157KiB - application/postscript)

 

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 mkru (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 11 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2023-06-22 gbranden StatusIn Progress Fixed
        Open/ClosedOpen Closed
        Planned ReleaseNone 1.23.0
    2023-06-22 gbranden Assigned toNone gbranden
    2023-06-22 gbranden CategoryDriver gropdf Macro package ms
        SummaryAdd info on pdfswitchtopage in groff_ms for potential TOC relocation [ms] want info on pdfswitchtopage for potential TOC relocation
    2023-06-22 gbranden Attached File- Added ms.ps, #54859
        StatusNeed Info In Progress
    2023-06-03 gbranden CategoryGeneral Driver gropdf
        Item GroupNone Documentation
        StatusNone Need Info

    Back to the top

    Powered by Savane 3.13-4b48.
    Corresponding source code