deri pushed a commit to branch master
in repository groff.
commit a0a7a4c458442cf96d35fa9949cd6f342f45c8e1
Author: Deri James <[email protected]>
AuthorDate: Mon May 11 16:03:20 2026 +0100
[ms]: add PDF support.
* tmac/s.tmac (initial): Depend on register PDFFEAT set to 1
to add features. Only allowed with -Tpdf. Alias new XR/XM
to LP (to prevent use before ms is initialised).
(XR/@XR): Macro for internal links.
(XM/@XM): Macro to 'mark' position in document.
(RP): Name 'title' page, used to relocate TOC in .TC.
(cov*ab-init) turn on XR/XM.
(cov*print): Extract title and author for PDF meta data.
(@SH): Extra param (2) name bookmark, XR can link to it.
Setup diversion (box) to collect bookmark text.
(@NH): Extra param (2) name bookmark, XR can link to it.
Setup diversion (box) to collect bookmark text.
(@NH-end): Diversion trap when NH/SH has collected one
line of OUTPUT.
(XA): Start hotlink text (in TOC).
(XE): Stop marking hotlink.
(.TC): If .RP seen, move TOC to page after 'title'.
* doc/ms.ms.in (Initial): Add RP so that the TOC moves
after the cover.
(abstract): Mention PDF features.
(Introduction): Get PDF features by setting PDFFEAT.
(document Structure): Change references to hotlinks.
(Tables of Contents): Explain how to move TOC.
(NH/SH): New param 'name' and document.
(Using PDF features with ms): New section.
(Throughouut)): Name various sections to support
hotlinking. Change man page references to hotlinks.
* tmac/groff_ms.7.man:
* doc/groff.texi.in: Sync changes with ms.ms.
* doc/Groff-PDF-Features.ms (new file): Document
PDF features in pdf.tmac and macro packages mom,
man, ms.
* doc/doc.am: Build the new file above and switch
ms.ms and pic.ms to generate pdfs with features on.
* NEWS: Announce changes to s.tmac and acknowledge
antecedents of spdf.tmac.
---
ChangeLog | 46 ++
NEWS | 26 +
doc/Groff-PDF-Features.ms | 1353 +++++++++++++++++++++++++++++++++++++++++++++
doc/doc.am | 26 +-
doc/groff.texi.in | 74 ++-
doc/ms.ms.in | 219 +++++++-
tmac/groff_ms.7.man | 156 +++++-
tmac/s.tmac | 164 +++++-
8 files changed, 2021 insertions(+), 43 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index 4edc81e3c..d56d5c7de 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,49 @@
+2026-05-11 Deri James <[email protected]>
+
+ [ms]: add PDF support.
+
+ * tmac/s.tmac (initial): Depend on register PDFFEAT set to 1
+ to add features. Only allowed with -Tpdf. Alias new XR/XM
+ to LP (to prevent use before ms is initialised).
+ (XR/@XR): Macro for internal links.
+ (XM/@XM): Macro to 'mark' position in document.
+ (RP): Name 'title' page, used to relocate TOC in .TC.
+ (cov*ab-init) turn on XR/XM.
+ (cov*print): Extract title and author for PDF meta data.
+ (@SH): Extra param (2) name bookmark, XR can link to it.
+ Setup diversion (box) to collect bookmark text.
+ (@NH): Extra param (2) name bookmark, XR can link to it.
+ Setup diversion (box) to collect bookmark text.
+ (@NH-end): Diversion trap when NH/SH has collected one
+ line of OUTPUT.
+ (XA): Start hotlink text (in TOC).
+ (XE): Stop marking hotlink.
+ (.TC): If .RP seen, move TOC to page after 'title'.
+
+ * doc/ms.ms.in (Initial): Add RP so that the TOC moves
+ after the cover.
+ (abstract): Mention PDF features.
+ (Introduction): Get PDF features by setting PDFFEAT.
+ (document Structure): Change references to hotlinks.
+ (Tables of Contents): Explain how to move TOC.
+ (NH/SH): New param 'name' and document.
+ (Using PDF features with ms): New section.
+ (Throughouut)): Name various sections to support
+ hotlinking. Change man page references to hotlinks.
+
+ * tmac/groff_ms.7.man:
+ * doc/groff.texi.in: Sync changes with ms.ms.
+
+ * doc/Groff-PDF-Features.ms (new file): Document
+ PDF features in pdf.tmac and macro packages mom,
+ man/mandoc, ms.
+
+ * doc/doc.am: Build the new file above and switch
+ ms.ms and pic.ms to generate pdfs with features on.
+
+ * NEWS: Announce changes to s.tmac and acknowledge
+ antecedents of spdf.tmac.
+
2026-05-11 G. Branden Robinson <[email protected]>
[groff]: Rename test scripts to accommodate case-insensitive
diff --git a/NEWS b/NEWS
index ca79f8520..c9f69291a 100644
--- a/NEWS
+++ b/NEWS
@@ -113,6 +113,32 @@ Macro packages
These macro definitions are harmlessly redundant when formatting such
a document with an older version of groff mm.
+* The s (ms) macro package now supports the parameter `-rPDFFEAT=1`
+ which will enable PDF features when used with `-Tpdf`. The PDF produced
+ will show an overview bookmark panel, the pdf `properties` information
+ will include the document title and author(s), any TOC included will
+ have clickable entries which can navigate the document (even if the
+ document does not use the newer `XN` macro), and if the document has
+ a cover page (introduced with RP) the TOC will be relocated to after
+ the cover.
+
+ Two new macros: `XR` and `XM` allow clickable internal links within
+ the document.
+
+ The documents ms.ms and pic.ms are now delivered as pdfs (rather than
+ postscript) with features turned on. An additional document
+ `Groff-PDF-Features.pdf` covers using pdf features in several macro
+ packages, including `ms`.
+
+ These changes were inspired by Keith Marshall's spdf.tmac which was
+ withdrawn from groff, but is available at:-
+
+ https://savannah.nongnu.org/projects/groff-pdfmark/
+
+ Although there are several differences. The aim with these additions
+ to `ms` was to add pdf features to any ms document without having to
+ make any changes to the document at all.
+
Miscellaneous
-------------
diff --git a/doc/Groff-PDF-Features.ms b/doc/Groff-PDF-Features.ms
new file mode 100644
index 000000000..44692b087
--- /dev/null
+++ b/doc/Groff-PDF-Features.ms
@@ -0,0 +1,1353 @@
+.\" Run: pdfmom --roff -ms -msboxes -dpapersz=a4 -tU -P-pa4
Groff-PDF-Features.ms > Groff-PDF-Features.pdf
+.\"
+.\" Copyright 2026 Free Software Foundation, Inc.
+.\"
+.\" This file is part of groff, the GNU roff typesetting system.
+.\"
+.\" groff is free software; you can redistribute it and/or modify it
+.\" under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation, either version 3 of the License, or
+.\" (at your option) any later version.
+.\"
+.\" groff is distributed in the hope that it will be useful, but WITHOUT
+.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
+.\" License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with this program. If not, see <http://www.gnu.org/licenses/>.
+.nr PS 11
+.nr VS 13
+.nr PO 2c
+.nr LL 17c
+.nr PL 29.7c
+.nr HM 1.9c
+.nr FM .3c
+.nr QI 5n
+.nr DI \n[QI]
+.nr PDFOUTLINE.FOLDLEVEL 1
+.ds FR 1
+.nr TC-MARGIN \w'00' \" expect 2-digit page numbers at most
+.ie t .nr PI 3.5n
+.el .nr PI 4n
+.ds date \*[MONTH\n[mo]] \n[year]\"
+.ND \*[date]
+.EH '%''\*[date]'
+.EF ''''
+.OH '\f[I]Groff\f[] PDF features''%'
+.OF ''''
+.de Cd
+. ft CB
+..
+.de CdX
+. ft
+..
+.de Qq
+. nop \[lq]\\$1\[rq]\\$2
+..
+.\" Define a macro for code literals; use bold and disable hyphenation.
+.de Lt
+. ft CB
+. nh
+. nop \m[grey33]\s'-1p'\\$1\s'+1p'\m[]\c
+. hy \\n[HY]
+. ft
+. nop \&\\$2
+..
+.de PN
+. ev Pn
+. evc 0
+. po .5c
+. pdfnote \\$@
+. fl
+. po
+. ev 0
+..
+.ds = \f(CB\\$1\f(CR\\$4\f[CBI]\\$2\f(CR\\$3
+.RP no
+.TL
+.BI Groff
+PDF features
+.AU
+Deri James
+.AI
[email protected]
+.\" .AB no
+.\" \X'pdf: pdfpic gnu.eps -C 0 0 15c'
+.\" .sp 5c
+.\" .AE
+.NH 1 intro
+.XN Introduction
+.LP
+This is an attempt to draw together information gleaned from
+.Lt pdf.tmac ,
+.Lt gropdf(1) ,
+and the various full service macros which manage pdf features.
+.LP
+Previously groff contained
+.Lt pdfmark.tmac
+and
+.Lt spdf.tmac
+(to integrate pdf features into the
+.Lt ms
+macros). Since these have now been dropped from groff and are now supported by
+Keith Marshall at
+.pdfhref W -D https://savannah.nongnu.org/projects/groff-pdfmark -A . this site
+.LP
+PDF features can either be controlled at a low level,
+using the macros defined in
+.Lt pdf.tmac
+or rely on these
+macros being integrated into a full-service macro
+package. Currently this is the state of play with regard
+to full-service:-
+.LP
+.TS
+allbox tab(^);
+Cb Cb Cb Cb Cb Cb
+Cf(CB) C C C C C.
+Macro^Meta Data^Bookmarks^Internal Link^External Link^Named Destination
+mom^\[OK]^\[OK]^\[OK]^\[OK]^\[OK]
+man^^\[OK]^\[OK]\m[red]\**\m[]^\[OK]^^
+ms^\[OK]^\[OK]^\[OK]^^\[OK]
+me^^^^^
+mm^^^^^
+.TE
+.LP
+.FS
+In a man page collection the MR macro can be used to link to other entries
+in the collection, otherwise it is an external link.
+.FE
+.LP
+The macros outlined below cannot be mix'n'matched between full service
+macro sets, but the information given for
+.Lt pdf.tmac
+can be used in any document, particularly if a full macro set is missing
+a particular facility.
+.LP
+.NH 1 meta
+.XN Meta Data
+.NH 2 info
+.XN Document Info
+.LP
+A PDF document can contain meta data such as
+.Qq "Created Date" ,
+.Qq Author ,
+.Qq Title ,
+etc..
+.NH 3
+.XN pdf.tmac
+.BOXSTART SHADED cornsilk OUTLINED brown INDENT 2n WEIGHT 1p
+.BOXSTART SHADED cornsilk3 INDENT 2p
+.ce 1
+.Lt pdf.tmac
+.BOXSTOP
+.LP
+To enter pdf meta data use:
+.QS
+.Lt ".pdfinfo /<label>"
+"\fItext\fP"
+.QE
+Where
+.Lt /<label>
+can be:-
+.LP
+.QS
+.Lt /Title ,
+.Lt /Author ,
+.Lt /Subject ,
+.Lt /Keywords
+.QE
+And
+.BI text
+can be multi-line if you use:-
+.QS
+.Lt \[rs]*[PDFLB]
+where you want the line-break.
+.QE
+These entries are stored in the pdf and can be seen if you run the
+command:-
+.QS
+.Lt pdfinfo
+\fIfilename\fP
+.QE
+Or are probably visible if you look at
+.Qq "Document Properties"
+in your favourite pdf viewer.
+.LP
+.BOXSTOP
+.NH 3
+.XN mom
+.BOXSTART SHADED lavenderblush OUTLINED mediumblue INDENT 2n WEIGHT 1p
+.BOXSTART SHADED lightgray INDENT 2p
+.ce 1
+.Lt mom
+.BOXSTOP
+.LP
+In
+.Lt mom
+you can use:-
+.QS
+.Lt .DOCTITLE
+.BI text
+.LP
+or more usually
+.LP
+.Lt .PDF_TITLE
+.BI text
+.QE
+The text given to:-
+.QS
+.Lt .AUTHOR
+.BI text
+.QE
+Will be added to the pdf meta data.
+.BOXSTOP
+.LP
+.NH 3
+.XN ms
+.BOXSTART SHADED honeydew OUTLINED green INDENT 2n WEIGHT 1p
+.BOXSTART SHADED lightgray INDENT 2p
+.ce 1
+.Lt ms
+.BOXSTOP
+.LP
+.Lt .TL
+and
+.Lt .AU
+Provide the Title and Author for the pdf.
+.BOXSTOP
+.LP
+.NH 2 notes
+.XN Annotation Notes
+.LP
+.PN -T "Deri James" Just an example
+These are the clickable/hoverable icons which appear in the document which
+can contain pop-up comments on the text. Only the
+.Lt pdf.tmac
+macros provide access to this facility.
+.LP
+.NH 3
+.XN pdf.tmac
+.BOXSTART SHADED cornsilk OUTLINED brown INDENT 2n WEIGHT 1p
+.BOXSTART SHADED lightgray INDENT 2p
+.ce 1
+.Lt pdf.tmac
+.BOXSTOP
+.LP
+.Lt .pdfnote
+[ -T
+.BI title
+]
+.BI "text"
+.LP
+The popup note in the left margin was created with:-
+.QS
+.Lt \&.pdfnote \"
+-T "Deri James" Just an example
+.QE
+The colour of the icon is set by setting the register
+.Lt PDFNOTE.COLOUR
+(or
+.Lt PDFNOTE.COLOR )
+to three numbers each in the range 0.0 \[rA] 1.0 representing red, green,
+blue values, so:-
+.QS
+\&.ds
+.Lt PDFNOTE.COLOUR
+1.0 1.0 0.0
+.QE
+Produces a yellow icon. The opacity of the icon is controlled by:-
+.QS
+\&.ds
+.Lt PDFNOTE.OPACITY
+0.0 \[rA] 1.0
+.QE
+Where the default value is 0.6.
+.LP
+Again you can use
+.Lt \[rs]*[PDFLB]
+in the
+.BI text .
+.BOXSTOP
+.LP
+.NH 1 bookmarks
+.XN Bookmarks
+.LP
+For PDFs, bookmarks are the entries in the outline panel. Each bookmark
+has a hierarchical level, and, optionally, can be
+.Qq named
+so that they can be linked to from elsewhere in the document
+.XR naming ). (
+.LP
+Bookmarks in the panel can be open or closed, setting:-
+.QS
+\&.ds
+.Lt PDFOUTLINE.FOLDLEVEL
+1
+.QE
+will
+.Qq close
+all bookmarks below the first level. The default is to open
+all bookmarks.
+.NH 2
+.XN pdf.tmac
+.BOXSTART SHADED cornsilk OUTLINED brown INDENT 2n WEIGHT 1p
+.BOXSTART SHADED lightgray INDENT 2p
+.ce 1
+.Lt pdf.tmac
+.BOXSTOP
+.LP
+.Lt pdf.tmac
+defines this macro for bookmarks:-
+.QS
+.Lt .pdfbookmark
+[\c
+.Lt -T
+.BI name ]
+.BI level
+.BI "descriptive text ..."
+.QE
+Where
+.Qq level
+is the mandatory nesting level for this
+.Qq bookmark .
+All the
+.Qq "descriptive text"
+form the entry in the outline panel. If the
+.Lt -T
+flag is given this becomes a
+.Qq "named destination"
+which can be linked to from elsewhere in the document
+.ds here naming
+.XR naming ). (
+.ds here after
+.BOXSTOP
+.ds here ne
+.ne 5
+.ds here
+.NH 2
+.XN mom
+.BOXSTART SHADED lavenderblush OUTLINED mediumblue INDENT 2n WEIGHT 1p
+.BOXSTART SHADED lightgray INDENT 2p
+.ce 1
+.Lt mom
+.BOXSTOP
+.LP
+mom uses the
+.Lt .HEADING
+macro to populate the outline panel:-
+.QS
+.Lt .HEADING
+.BI level
+[\c
+.Lt NAMED
+.BI name ]
+.BI "descriptive text ..."
+.QE
+.Qq level ,
+.Qq name
+and
+.Qq "descriptive text"
+have the same meanings as above.
+.BOXSTOP
+.LP
+.NH 2
+.XN ms
+.BOXSTART SHADED honeydew OUTLINED green INDENT 2n WEIGHT 1p
+.BOXSTART SHADED lightgray INDENT 2p
+.ce 1
+.Lt ms
+.BOXSTOP
+.LP
+There are two separate ways of providing outline bookmarks in
+.Lt ms .
+First there is the traditional heading:-
+.QS
+.Lt .NH
+.BI level
+[\c
+.BI name \m[red]\**\m[]]
+.QE
+.FS
+If the
+.Qq level
+is
+.Qq S
+(a Berkeley extension) you cannot have a
+.Qq named
+bookmark.
+.FE
+This is then followed by input which is used as
+.Qq "descriptive text" .
+.LP
+Although there could be several lines of input text, it is the
+accumulated output line which is used as
+.Qq "descriptive text" .
+.LP
+.pdfhref M -N hdexample ms Heading Example
+So this input:
+.ID
+.ft CB
+\&.NH 1 using
+Using
+\&.BI groff
+with the
+\&.BI ms
+Macro Package
+\&.XS
+Using
+\&.BI groff
+with the
+\&.BI ms
+Macro Package
+\&.XE
+.ft
+.DE
+Would create a named (\c
+.Qq using )
+level 1 bookmark
+.Qq "Using \fIgroff\fP with the \fIms\fP Macro Package" ,
+and also create a
+.Lt TOC
+entry.
+Note if the input text results in multiple output lines it is
+only the first output line which is used as the bookmark text.
+.LP
+.pdfhref M -N XN Using .XN
+The second method, which combined the
+.Qq heading
+with populating a
+.Lt TOC ,
+is the
+.Lt .XN
+command which
+.B must
+immediately follow the
+.Lt .NH
+command:-
+.QS
+.Lt .XN
+.BI "descriptive text"
+.QE
+Previously the
+.Lt .NH
+and following heading text had to be followed with
+.Lt .XS/.XE
+commands with the same text to separately populate the
+.Lt TOC .
+.LP
+So the equivalent code to the above using
+.Lt .XN
+is:-
+.ID
+.ft CB
+\&.NH 1 using
+\&.XN Using \[rs]fIgroff\[rs]fP with the \[rs]fIms\[rs]fP Macro Package
+.ft
+.DE
+In both cases the bookmark is named
+.Qq using ,
+and clicking on the overview panel
+or the hotspot link in the
+.Lt TOC
+will jump to the correct part of the document.
+You can also use the
+.XR XR "" "" "\&.XR command"
+to jump to the section named
+.Qq using :-
+.QS
+\&.XR using ). (
+.QE
+to enter this hotlink
+.Qq "(see: Using \fIgroff\fP with the \fIms\fP Macro Package)" .
+.BOXSTOP
+.bp
+.NH 2
+.XN man
+.LP
+.BOXSTART SHADED linen OUTLINED maroon INDENT 2n WEIGHT 1p
+.BOXSTART SHADED lightgray INDENT 2p
+.ce 1
+.Lt man
+.BOXSTOP
+.LP
+The
+.QS
+.Lt .TH
+.BI identifier
+.BI section
+.QE
+macro creates (via first call to
+.Lt .PT )
+a named heading with name id of
+.Qq identifier(section) .
+It is normally given a level 1 bookmark, which can be controlled by setting
+.Qq an*bookmark-base-level
+on the command line to increase the level,
+this can be used in man page collections where the pages
+are split into separate sections.
+.LP
+The
+.Lt .SH
+and
+.Lt .SS
+macros create unnamed bookmarks at the appropriate level.
+.BOXSTOP
+.LP
+.NH 1 naming
+.XN Named Destination
+.LP
+In order to insert hotspot links which jump to other parts of the
+document, the destination must be
+.Qq named .
+In the section on
+.XR bookmarks "" "" bookmarks
+it showed how they can be
+.Qq named .
+.LP
+If you want to jump to a place in the document which has not got a bookmark,
+you can name any particular place in the document, for example, a table or a
+figure to which you may want to refer. See information below.
+.NH 2
+.XN pdf.tmac
+.LP
+.BOXSTART SHADED cornsilk OUTLINED brown INDENT 2n WEIGHT 1p
+.BOXSTART SHADED lightgray INDENT 2p
+.ce 1
+.Lt pdf.tmac
+.BOXSTOP
+.LP
+.pdfhref M -N pdfhrefM
+This macro will plant a named destination without inserting a bookmark.
+.QS
+.Lt ".pdfhref M"
+[\c
+.Lt -N
+.BI name ]
+[\c
+.Lt -E ]
+.BI "descriptive text" ] [
+.QE
+If no
+.BI name
+is specified, the first word of
+.Qq "descriptive text"
+is used as the
+.Qq name ,
+which means that if the
+.Lt -N
+flag is not used then there must be at least one word in the text.
+.LP
+The
+.Qq "descriptive text" ,
+if any, is saved as the
+.Qq value
+of the destination, and can be used when specifying a hotspot link
+.XR hotspot ). (
+.LP
+If the
+.Lt -E
+flag is used, the text is output to the document as well.
+.BOXSTOP
+.LP
+.NH 2
+.XN mom
+.BOXSTART SHADED lavenderblush OUTLINED mediumblue INDENT 2n WEIGHT 1p
+.BOXSTART SHADED lightgray INDENT 2p
+.ce 1
+.Lt mom
+.BOXSTOP
+.LP
+The mom macro:-
+.QS
+.Lt .PDF_TARGET
+.BI name
+[\c
+.BI "descriptive text" ]
+.QE
+You can now use
+.BI name
+as the destination of any hotspot link
+.XR hotspot ). (
+.BOXSTOP
+.LP
+.NH 2
+.XN ms
+.BOXSTART SHADED honeydew OUTLINED green INDENT 2n WEIGHT 1p
+.BOXSTART SHADED lightgray INDENT 2p
+.ce 1
+.Lt ms
+.BOXSTOP
+.LP
+The
+.I ms
+macro
+.QS
+.Lt .XM
+.BI name
+[\c
+.BI "descriptive text" ]
+.QE
+Marks a position in the document to which
+.Lt .XR
+can place a hotspot link
+.XR hotspot ). (
+.BOXSTOP
+.bp
+.NH 1 hotspot
+.XN Internal Hotspot Links
+.LP
+An internal link is to a
+.Qq "named destination"
+within the document,
+.XR external "" "" external
+are links using a URI.
+.LP
+A hotspot link is a clickable piece of text which will cause the viewer
+to jump to a
+.XR naming . "" *
+The colour of the hotspot is controlled by setting the register
+.Lt PDFHREF.COLOUR
+(or
+.Lt PDFHREF.COLOR )
+to three numbers each in the range 0.0 \[rA] 1.0 representing red, green,
+blue values, so:-
+.QS
+\&.ds
+.Lt PDFHREF.COLOUR
+0.00 0.35 0.60
+.QE
+Uses a turquoise text, which can be referenced as
+.QS
+.Lt \[rs]m[\[rs]*[PDFHREF.TEXT.COLOUR]] .
+.QE
+.ne 5
+Hotspots can have a border drawn around them, which is controlled by setting
+the register
+.Lt PDFHREF.BORDER
+to an array of 3 numbers which represent \[en] horizontal corner radius,
+vertical corner radius, and border width. A zero radius gives square (not
+rounded) corners. The default is:-
+.QS
+\&.ds
+.Lt PDFHREF.BORDER
+0 0 0
+.QE
+Which produces no border around the hotspot.
+.NH 2
+.XN pdf.tmac
+.LP
+.BOXSTART SHADED cornsilk OUTLINED brown INDENT 2n WEIGHT 1p
+.BOXSTART SHADED lightgray INDENT 2p
+.ce 1
+.Lt pdf.tmac
+.BOXSTOP
+.LP
+To plant a hotspot link:-
+.QS
+.Lt ".pdfhref L " [\c
+.Lt -D
+.BI name ]
+[\c
+.Lt -P
+.BI prefix-text ]
+[\c
+.Lt -A
+.BI affixed-text ]
+[\c
+.Lt -- ]
+[\c
+.BI "hotlink text" ]
+.QE
+The target for the link is given by
+.BI name
+which should be a destination you have named
+.XR naming ). (
+.LP
+.XM prefix Prefix and Affix
+The
+.BI prefix-text
+and
+.BI affixed-text
+are placed around the
+.BI "hotlink text" .
+.LP
+If you used a
+.BI "descriptive text"
+when naming a destination, you can retrieve the value with this code:-
+.ID
+.ft CB
+\&.pdf:lookup \c
+.BI name
+\&.ie !'\[rs]*[pdf:lookup-result]'' \\
+\&. ds desc-txt \&\[rs]*[pdf:lookup-value]
+\&.el \\
+\&. ds desc-txt Unknown
+.ft
+.DE
+.LP
+.XM expandochars "expando char"
+This technique is used by some of the full service macros to provide the
+.Qq expando
+characters
+.Qq *
+and
+.Qq + \&.
+When they are the final character in
+.Qq "hotlink text"
+the expando is replaced by
+.BI desc-text ,
+surrounded by double quotes if the expando character is
+.Qq + .
+.BOXSTOP
+.LP
+.NH 2
+.XN mom
+.BOXSTART SHADED lavenderblush OUTLINED mediumblue INDENT 2n WEIGHT 1p
+.BOXSTART SHADED lightgray INDENT 2p
+.ce 1
+.Lt mom
+.BOXSTOP
+.LP
+mom uses this macro:-
+.QS
+.Lt .PDF_LINK
+.BI name
+[\c
+.Lt PREFIX
+.BI text ]
+[\c
+.Lt SUFFIX
+.BI text ]
+.BI "hotlink text"
+.QE
+If the
+.BI "hotlink text"
+is terminated with an
+.XR expandochars "" "" *
+it is replaced by the value of the
+.BI "descriptive text"
+when the target
+.BI name
+was created.
+.BOXSTOP
+.LP
+.NH 2 hotspotms
+.XN ms
+.BOXSTART SHADED honeydew OUTLINED green INDENT 2n WEIGHT 1p
+.BOXSTART SHADED lightgray INDENT 2p
+.ce 1
+.Lt ms
+.BOXSTOP
+.LP
+.XM XR
+An addition to the ms macro set is the
+.Lt .XR
+command, originally found in some versions of Keith Marshall's
+.Lt spdf.tmac ,
+our version now uses
+.XR expandochars "" "" expandos
+.QS
+.Lt .XR
+.BI name
+[\c
+.BI post
+[\c
+.BI pre
+[\c
+.BI "hotlink text" "] ] ]"
+.QE
+If
+.BI "hotlink text"
+is missing, the contents of
+.Lt \[rs]*[spdf:txt_default]
+is used instead. This defaults to
+.Qq "see:\ +" " "
+so, with the use of the terminating expando, the code
+.QS
+.Lt .XR
+intro ), (
+.QE
+would add a link
+.XR intro ), (
+if the first section of this document was:-
+.ID
+\&.NH 1 intro
+\&.XN Introduction
+.DE
+.BOXSTOP
+.LP
+.NH 2
+.XN man
+.LP
+.BOXSTART SHADED linen OUTLINED maroon INDENT 2n WEIGHT 1p
+.BOXSTART SHADED lightgray INDENT 2p
+.ce 1
+.Lt man
+.BOXSTOP
+.LP
+The
+.QS
+.Lt .MR
+.BI name
+.BI section
+.QE
+macro normally creates an external link
+.XR external ), (
+suitable for linking to
+another man page, but if the other man page it is calling is part
+of the same man page collection, it creates an internal link within
+the document.
+.BOXSTOP
+.LP
+.NH 1 external
+.XN External Hotspot Links
+.LP
+External links are often links to resources on the internet such as website
+URLs.
+.NH 2
+.XN pdf.tmac
+.LP
+.BOXSTART SHADED cornsilk OUTLINED brown INDENT 2n WEIGHT 1p
+.BOXSTART SHADED lightgray INDENT 2p
+.ce 1
+.Lt pdf.tmac
+.BOXSTOP
+.LP
+The macro to link to internet resources is:-
+.QS
+.Lt ".pdfhref W " [\c
+.Lt -D
+.BI URI ]
+[\c
+.Lt -P
+.BI prefix-text ]
+[\c
+.Lt -A
+.BI affixed-text ]
+[\c
+.Lt -- ]
+[\c
+.BI "hotlink text" ]
+.QE
+If a
+.BI URI
+is not specified the
+.BI "hotlink text"
+must be a valid
+.BI URI
+itself, and the complete
+.BI URI
+will be visible in the document.
+If a
+.BI URI
+is given by specifying
+.Lt -D
+.BI URI
+then only the
+.BI "hotlink text"
+will be visible, but clicking it will launch the
+.BI URI .
+.LP
+The
+.Lt -P
+and
+.Lt -A
+flags operate in the same way as in
+.Lt ".pdfhref L "
+.XR prefix ). (
+.BOXSTOP
+.LP
+.NH 2
+.XN mom
+.BOXSTART SHADED lavenderblush OUTLINED mediumblue INDENT 2n WEIGHT 1p
+.BOXSTART SHADED lightgray INDENT 2p
+.ce 1
+.Lt mom
+.BOXSTOP
+.LP
+External links are supported by:-
+.QS
+.Lt .PDF_WWW_LINK
+.BI URI
+[\c
+.Lt PREFIX
+.BI text ]
+[\c
+.Lt SUFFIX
+.BI text ]
+.BI "hotlink text"
+.QE
+If no
+.BI "hotlink text"
+is given, the
+.BI URI
+is used as the
+.BI "hotlink text" .
+.XR expandochars "" "" Expandos
+can be used as the last character of
+.BI "hotlink text"
+and will insert the
+.BI URI .
+.BOXSTOP
+.ne 8v
+.LP
+.NH 2
+.XN man
+.LP
+.BOXSTART SHADED linen OUTLINED maroon INDENT 2n WEIGHT 1p
+.BOXSTART SHADED lightgray INDENT 2p
+.ce 1
+.Lt man
+.BOXSTOP
+.LP
+The macro
+.QS
+.Lt .MR
+.BI name
+.BI section
+.QE
+Generates an appropriate external
+.BI URI
+such as:-
+.QS
+man:/groff(1)
+.QE
+except if the link is to another man page in the same collection.
+.BOXSTOP
+.LP
+.ne 5
+.NH 1 toc
+.XN Table of Contents
+.LP
+Some full service macro sets offer macros for building a Table of Contents,
+with PDF features these TOCs have clickable entries.
+.LP
+.NH 2
+.XN pdf.tmac
+.BOXSTART SHADED cornsilk OUTLINED brown INDENT 2n WEIGHT 1p
+.BOXSTART SHADED lightgray INDENT 2p
+.ce 1
+.Lt pdf.tmac
+.BOXSTOP
+.LP
+.Lt pdf.tmac
+has no specific macros to build Table of Contents, but it does have two macros
+which can insert a TOC into the appropriate position in the document:-
+.QS
+.Lt .pdfpagename
+.BI name
+.QE
+This assigns a name to the current page being rendered which can then be used
in
+the second macro:-
+.QS
+.Lt .pdfswitchtopage
+[\c
+.BI when ]
+.BI name
+.QE
+Where
+.BI name
+is a previously named page, and the optional
+.BI when
+can be
+.Qq before
+or
+.Qq after ,
+default is
+.Qq before .
+Alternatively the positions
+.Qq top
+and
+.Qq bottom
+can be used instead of a named page.
+This macro should be used before a new page is started.
+.BOXSTOP
+.LP
+.NH 2
+.XN mom
+.BOXSTART SHADED lavenderblush OUTLINED mediumblue INDENT 2n WEIGHT 1p
+.BOXSTART SHADED lightgray INDENT 2p
+.ce 1
+.Lt mom
+.BOXSTOP
+.LP
+The macro
+.QS
+.Lt .AUTO_RELOCATE_TOC
+.QE
+(must come before
+.Lt .START )
+will position the TOC appropriately in the document.
+.LP
+Pease see the
+.pdfhref W -D http://schaffter.ca/mom/momdoc/tables-of-contents.html#top --
mom documentation
+for details of TOC generation, by default the TOC entries are clickable.
+.BOXSTOP
+.LP
+.NH 2
+.XN ms
+.BOXSTART SHADED honeydew OUTLINED green INDENT 2n WEIGHT 1p
+.BOXSTART SHADED lightgray INDENT 2p
+.ce 1
+.Lt ms
+.BOXSTOP
+.LP
+The traditional way of populating a TOC was to use the
+.Lt .XS/.XA/.XE
+macros.
+.LP
+Groff 1.23.0 introduced the
+.Lt .XN
+macro which combined producing headings
+.XR hdexample ) (
+with adding a TOC entry.
+.LP
+In either case the entry will be clickable.
+.LP
+If the document has an
+.Lt .RP
+entry, so a title page is produced, the TOC will be repositioned after the
+Title Page.
+.BOXSTOP
+.LP
+.ne 7v
+.NH 1 slide
+.XN Slideshow Presentations
+.LP
+The groff pdf driver understands how to create pdfs to be used for slideshow
+presentations. An alternative is to use the postscript driver and gpresent
+which is downloadable
+.pdfhref W -D
https://ftp.openbsd.org/pub/OpenBSD/distfiles/gpresent-2.5.tar.gz here
+because the original
+.pdfhref W -D https://www.bob.diertens.org/corner/useful/gpresent/ website
+is having difficulty downloading files larger than 32kb.
+.LP
+groff documents written to work with
+.Lt present.tmac
+.I may
+work with -Tpdf with minor alteration (and no need to run
+.Lt presentps
+and
+.Lt ps2pdf ).
+.LP
+.NH 2
+.XN pdf.tmac
+.BOXSTART SHADED cornsilk OUTLINED brown INDENT 2n WEIGHT 1p
+.BOXSTART SHADED lightgray INDENT 2p
+.ce 1
+.Lt pdf.tmac
+.BOXSTOP
+.LP
+There are just two macros which control the slide presentation:-
+.QS
+.Lt .pdftransition
+.I feature
+.I mode
+.I duration
+.I dimension
+.I motion
+.I direction
+.I scale
+.I bool
+.QE
+These parameters are explained in the
+.pdfhref W -D man:/gropdf(1)#transition gropdf(1)
+man page, many of them are not required!
+.LP
+There are two
+.Qq events
+which trigger a transition: when a slide is first drawn
+(\c
+.I feature
+=
+.Lt SLIDE )
+and when a new element is added to the slide
+.I feature "" (
+=
+.Lt BLOCK ).
+Both can have a different transition
+.I mode ,
+such as
+.Lt "\[dq]Split | Blinds | Box | Wipe | Dissolve | Glitter | R\[dq]"
+all of which are explained (and some more!) in the man page.
+.LP
+Whenever you want the presentation to pause (because you have added a
+new element to the slide) use the macro:-
+.QS
+.Lt .pdfpause
+.QE
+and the new element will appear using the current transition set for
+.Lt BLOCK .
+.BOXSTOP
+.LP
+.NH 2
+.XN mom
+.BOXSTART SHADED lavenderblush OUTLINED mediumblue INDENT 2n WEIGHT 1p
+.BOXSTART SHADED lightgray INDENT 2p
+.ce 1
+.Lt mom
+.BOXSTOP
+.LP
+mom has full integration with pdf presentation mode, the documentation
+is
+.pdfhref W -D http://schaffter.ca/mom/momdoc/docprocessing.html#slides -A .
here
+.LP
+In addition the mom example documents include
+.Lt slide-demo.mom
+and its resultant pdf, so should be included in the examples/mom directory
+in the groff documentation.
+.BOXSTOP
+.LP
+.NH 2
+.XN ms
+.BOXSTART SHADED honeydew OUTLINED green INDENT 2n WEIGHT 1p
+.BOXSTART SHADED lightgray INDENT 2p
+.ce 1
+.Lt ms
+.BOXSTOP
+.LP
+An example of using
+.Lt ms
+to create a slideshow is
+.pdfhref W -D http://chuzzlewit.co.uk/ms-slides.tgz -A . here
+.BOXSTOP
+.bp
+.NH 1 boxes
+.XN Boxes and PDF paper colour
+.LP
+PDF viewers usually show contents on a white background, the actual
+background in the PDF is really transparent (so it appears white),
+however it is possible to specify a colour for the page background.
+.LP
+In addition it is possible to specify framed coloured boxes on the page
+to contain the running contents. These boxes will flow onto following
+pages.
+.LP
+.NH 2
+.XN pdf.tmac
+.BOXSTART SHADED cornsilk OUTLINED brown INDENT 2n WEIGHT 1p
+.BOXSTART SHADED lightgray INDENT 2p
+.ce 1
+.Lt pdf.tmac
+.BOXSTOP
+.LP
+The relevent macros are:-
+.QS
+.Lt .pdfbackground
+.I cmd
+.I left
+.I top
+.I right
+.I bottom
+.I weight
+.br
+.Lt ".pdfbackground off"
+.br
+.Lt ".pdfbackground footnote"
+.I bottom
+.QE
+which produce a background rectangle on the page. The meanings of the
+parameters are explained in the
+.pdfhref W -D man:/gropdf(1)#boxes gropdf(1)
+man page.
+.BOXSTOP
+.LP
+.NH 2
+.XN ms
+.BOXSTART SHADED honeydew OUTLINED green INDENT 2n WEIGHT 1p
+.BOXSTART SHADED lightgray INDENT 2p
+.ce 1
+.Lt ms
+.BOXSTOP
+.LP
+If you include the macro file
+.Lt -msboxes
+in the
+.I groff
+command, you will have access to these macros:-
+.QS
+.Lt .BOXSTART
+.Lt SHADED
+.I colour
+.Lt OUTLINED
+.I colour
+.Lt INDENT
+.I size
+.Lt WEIGHT
+.I size
+.QE
+begins a box, where the argument after
+.Lt SHADED
+gives the fill colour and that after
+.Lt OUTLINED
+the border colour. Omit the former to get a borderless filled box and the
+latter for a border with no fill. The specified
+.Lt WEIGHT
+(line thickness) is used if the box is
+.Lt OUTLINED .
+.LP
+.Lt INDENT
+precedes a value that leaves a gap between the border and the contents
+inside the box.
+.LP
+Each colour must be a defined groff colour name, and each size a valid
+.I groff
+numeric expression. The keyword/value pairs can be specified in any order.
+.LP
+Boxes can be stacked, so you can start a box within another box; usually
+the later boxes would be smaller than the containing box, but this is
+not enforced. When using
+.Lt BOXSTART ,
+the left position is the current indent minus the
+.Lt INDENT
+in the command, and the right position is the left position
+(calculated above) plus the current line length and twice the indent.
+.QS
+.Lt BOXSTOP
+.QE
+takes no parameters. It closes the most recently started box at the
+current vertical position after adding its
+.Lt INDENT
+spacing.
+.BOXSTOP
+.LP
+.NH 2
+.XN mom
+.BOXSTART SHADED lavenderblush OUTLINED mediumblue INDENT 2n WEIGHT 1p
+.BOXSTART SHADED lightgray INDENT 2p
+.ce 1
+.Lt mom
+.BOXSTOP
+.LP
+mom has comprehensive control of boxes see the
+.pdfhref W -D http://schaffter.ca/mom/momdoc/images.html#box-intro \
+ -A . mom documentation
+.BOXSTOP
+.bp
+.NH 1 developer
+.XN For macro developers
+.LP
+If you want to add PDF features to your own macro packages here is some
+information which may be helpful.
+.BOXSTART SHADED cornsilk OUTLINED brown INDENT 2n WEIGHT 1p
+.sp -1v
+.NH 2 restart
+.XN Stop/Start hotlink
+.QS
+.Lt .pdfmarksuspend/.pdfmarkresume
+.QE
+If there is a piece of
+.Qq "hotlink text"
+which appears right at the bottom of the page and continues across to the
+start of the next page these macros can stop/restart the hotlink.
+Typically they appear at the start of a page footer macro (to prevent the
+footer text becoming part of the hotlink), and at the end of a page
+header macro (to restart the hotlinking from the previous page).
+.LP
+.NH 2 pdfroff
+.XN Forward References
+.LP
+Since groff is a single pass interpreter when it finds an
+.XR hotspot "" "" *
+it cannot plant a link if it has not
+.Qq seen
+the
+.XR naming "" "" *
+to which it links, and the link will appear as
+\m[\*[PDFHREF.TEXT.COLOUR]]Unknown\m[]
+resisting all mouse clicks - the same happens if the
+.I destination
+of the link is mis-typed and does not exist. The forward link problem can be
+solved: instead of:-
+.QS
+.Lt "groff -Tpdf ..."
+.QE
+use:-
+.QS
+.Lt "pdfmom --roff ..."
+.QE
+The command was originally developed for satisfying forward references in
+.I mom
+files (hence the name), but with the
+.I --roff
+flag it drops its reliance on
+.I mom
+and you can place any macro package on the command line.
+.NH 2 S
+.XN Marking Hotlinks
+.LP
+The
+.QS
+.Lt .pdfhref
+.I command
+.QE
+general purpose macro, supports these commands:-
+.QS
+.IP \*[= O]
+(Outline) This is the command which
+.XR bookmarks "" "" \fB.pdfbookmark\fP
+calls.
+.IP \*[= M]
+(Mark) Setup a
+.XR naming . "" +
+.IP \*[= L]
+(Local) Mark an
+.XR hotspot . "" +
+.IP \*[= W]
+(WWW URI) Form an
+.XR external . "" +
+.QE
+.LP
+These
+.Qq low-level
+calls all expect
+.Qq "descriptive text"
+or
+.Qq "hotlink text"
+to be passed as part of the macro call. Sometimes this is not convenient,
+consider the man macro pair
+.Lt .MT/.ME
+where
+.ID
+.ft CB
+\&.MT jh@\[rs]:axis\[rs]:.se
+J\[rs][o ad]rgen H\[rs][a ad]gg
+\&.ME
+.ft
+.DE
+The mail-to
+.I URI
+is on the
+.Lt .MT
+line, but the text to use for a
+.I hotlink
+is everything up to the following
+.Lt .ME .
+.LP
+The
+.Lt .pdfhref
+macro allows an
+.Lt -S
+flag, not documented above, which just turns on
+.I hotlinking
+text. It is then up to the macro author to arrange for it to be turned off
+at the appropriate point. In this example it should be
+.Qq "turned off"
+in the
+.Lt .ME
+macro.
+.LP
+The code to turn off the
+.Qq hotlinking
+and restore the text colour to what it was before the
+.Qq hotlinking
+started is:-
+.ID
+.ft CB
+\[rs]X'pdf: markend'\[rs]m[\[rs]*[pdf:curcol]]
+.ft
+.DE
+.BOXSTOP
+.TC
diff --git a/doc/doc.am b/doc/doc.am
index c70235382..ee2b9f60f 100644
--- a/doc/doc.am
+++ b/doc/doc.am
@@ -67,7 +67,8 @@ DOC_GMP_COVER_PAGE = doc/groff-man-pages-cover.groff
# Files located in the source tree
DOCFILES_INST = \
doc/me-revisions \
- doc/pic.ms
+ doc/pic.ms \
+ doc/Groff-PDF-Features.ms
DOCFILES_NOINST = \
doc/groff-man-pages-cover.groff.in \
doc/meintro.me.in \
@@ -87,13 +88,14 @@ PROCESSEDDOCFILES_HTML = \
endif
PROCESSEDDOCFILES_PDF = \
doc/automake.pdf \
- doc/groff-man-pages.pdf
+ doc/groff-man-pages.pdf \
+ doc/ms.pdf \
+ doc/pic.pdf \
+ doc/Groff-PDF-Features.pdf
PROCESSEDDOCFILES_PS = \
doc/meref.ps \
doc/meintro.ps \
- doc/meintro_fr.ps \
- doc/ms.ps \
- doc/pic.ps
+ doc/meintro_fr.ps
PROCESSEDDOCFILES_TXT = \
doc/groff-man-pages.utf8.txt
# XXX: $(PROCESSEDDOCFILES_HTML) is omitted because pic.html gets
@@ -379,13 +381,19 @@ SUFFIXES += .ms.in .ms
$(AM_V_GEN)$(MKDIR_P) `dirname $@` \
&& $(DOC_SED) $< >$@
-doc/ms.ps: doc/ms.ms $(TMAC_PACKAGE_MS) eqn pic tbl
+doc/ms.pdf: doc/ms.ms $(TMAC_PACKAGE_MS) eqn pic tbl pdfmom
$(GROFF_V)$(MKDIR_P) `dirname $@` \
- && $(DOC_GROFF) -pet -Tps -ms doc/ms.ms >$@
+ && $(DOC_PDFMOM) -pet -Tpdf -rPDFFEAT=1 -ms doc/ms.ms >$@
-doc/pic.ps: $(doc_srcdir)/pic.ms $(TMAC_PACKAGE_MS) eqn pic tbl
+doc/pic.pdf: $(doc_srcdir)/pic.ms $(TMAC_PACKAGE_MS) eqn pic tbl
$(GROFF_V)$(MKDIR_P) `dirname $@` \
- && $(DOC_GROFF) -pet -Tps -ms $(doc_srcdir)/pic.ms >$@
+ && $(DOC_GROFF) -pet -Tpdf -ms -rPDFFEAT=1 $(doc_srcdir)/pic.ms >$@
+
+doc/Groff-PDF-Features.pdf: $(doc_srcdir)/Groff-PDF-Features.ms tbl
doc/gnu.eps \
+ $(TMAC_PACKAGE_MS) eqn pic tbl pdfmom
+ $(GROFF_V)$(MKDIR_P) `dirname $@` \
+ && $(DOC_PDFMOM) --roff -tU -P-pa4 -rPDFFEAT=1 -ms -msboxes \
+ -I $(doc_builddir) -I $(doc_srcdir) $(doc_srcdir)/Groff-PDF-Features.ms
>$@
doc/webpage.ps: $(DOC_GNU_EPS) tmac/pspic.tmac tmac/www.tmac tbl
doc/webpage.ps: $(doc_srcdir)/webpage.ms $(TMAC_PACKAGE_MS)
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index 18ef05b4e..3038ea66a 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -2969,6 +2969,7 @@ and Research Tenth Edition Unix.
* ms Document Description Macros::
* ms Body Text::
* ms Page Layout::
+* Using PDF features with ms::
* Differences from AT&T ms::
* ms Legacy Features::
* ms Naming Conventions::
@@ -3233,7 +3234,10 @@ output was designed for the production of hard copy,
the traditional procedure was to manually relocate the pages containing
the table of contents between the cover page and the body text.
Today,
-page resequencing is more often done in the digital domain.
+page resequencing is more often done in the digital domain,
+and if you use a separate cover page with @code{RP}
+(and use @option{-T pdf}) the TOC will
+be positioned immediately after this cover page.
An index works similarly,
but because it typically needs to be sorted after collection,
its preparation requires separate processing.
@@ -3940,7 +3944,7 @@ input lines following the macro call becomes the
heading's title. Call
a paragraphing macro to end the heading text and start the section's
content.
-@DefmacList {NH, [@Var{depth}], ms}
+@DefmacList {NH, [@Var{depth}] [@Var{name}], ms}
@DefmacListEnd {NH, @t{S} @Var{heading-depth-index} @dots{}, ms}
Set an automatically numbered heading.
@@ -3961,6 +3965,9 @@ the previous @code{NH} call---that is, you ``skip a
depth'', as by
@samp{.NH 1} and then @samp{.NH 3}---@code{groff} @file{ms} emits a
warning on the standard error stream.
+The @var{name} is used to assign a named destination for use with
+the @code{XR} command.
+
Alternatively, you can give @code{NH} a first argument of@tie{}@code{S},
followed by integers to number the heading depths explicitly. Further
automatic numbering, if used, resumes using the specified indices as
@@ -4027,7 +4034,7 @@ facilitates its inclusion in, for example, table
captions, equation
labels, and @code{XS}/@code{XA}/@code{XE} table of contents entries.
@endDefmpstr
-@Defmac {SH, [@Var{depth}], ms}
+@Defmac {SH, [@Var{depth}] [@Var{name}], ms}
Set an unnumbered heading.
The optional @var{depth} argument is a GNU extension indicating the
@@ -4035,6 +4042,8 @@ heading depth corresponding to the @var{depth} argument
of @code{NH}.
It matches the type size at which the heading is set to that of a
numbered heading at the same depth when the @code{GROWPS} and
@code{PSINCR} heading size adjustment mechanism is in effect.
+The @var{name} is used to assign a named destination for use with
+the @code{XR} command.
@endDefmac
If the @code{GROWPS} register is set to a value greater than the
@@ -5263,6 +5272,65 @@ spread the dots. The width of the page number field is
stored in the
@c ---------------------------------------------------------------------
+@node Using PDF features with ms
+@subsection Using @acronym{PDF} features with @file{ms}
+@cindex @file{ms} macros, Using @acronym{PDF} features
+@c @cindex @acronym{PDF} features @file{ms}, macro package differences
+
+If you run an ms document with @code{-Tpdf} and @code{-rPDFFEAT=1}
+the @acronym{PDF} features shown in this document will be incorporated.
+The @acronym{PDF} produced will show an overview bookmark panel,
+the pdf ``properties'' information will include the document title and
author(s),
+any @acronym{TOC} included will have clickable entries which can
+navigate the document, and if the document has a cover page
+(introduced with @code{RP}) the @acronym{TOC}
+will be relocated to after the cover.
+
+There are also two new macro calls available.
+
+@Defmac {XR, name [@Var{post} [@Var{pre} [@Var{hotlink-text}]]], ms}
+The @Var{name} parameter should match a @Var{name} given to a
+@code{NH} or @code{SH} section/subsection, @xref{Headings in ms},
+or a name set by a @code{XM} command.
+The @Var{hotlink-text} is the text which will be clickable.
+If the text ends with ``@code{+}'' or ``@code{*}'' (the
+expansion characters), the text associated with the section heading
+will replace the character (enclosed with double quotes if the final
+character is ``@code{+}''). If no @Var{hotlink-text} is given, the
+value of @code{\*[spdf:txt_default]} is used. Which is initially set
+to ``@code{see: +}''. (Note the expansion character). But you can change it.
+@endDefmac
+
+@Defmac {XM, name [@Var{text}], ms}
+Mark a particular position in the document with a @Var{name}.
+Any text given will be used to replace a trailing expansion character
+in an @code{XR} command which references the @Var{name}.
+It is useful if you wish to name an arbitrary location in the document,
+so you can setup a link to a picture, diagram or even a single paragraph.
+@endDefmac
+
+Using @code{XR} for a ``forward'' link (where the destination is ``later''
+in the document), will not work properly if the link uses
+expansion characters and @code{groff} only sees a single pass
+of the document. So either use the full text, without a trailing
+expansion character in the forward link, or use the multi-pass command
+
+@Example
+pdfmom --roff -ms -rPDFFEAT=1 file.ms > file.pdf
+@endExample
+
+The command can be shortened to @code{pdfms -rPDFFEAT=1 ...}
+if you have created a link to the @code{pdfmom} command called @code{pdfms}.
+
+Running an @file{ms} document with @code{nroff}, is only a single pass,
+so the above advice about not using expansion characters with
+forward links also applies.
+
+All of the @acronym{PDF} features mentioned in this document
+can be disabled if the @code{groff} command includes @code{-rPDFFEAT=0}.
+
+@c ---------------------------------------------------------------------
+
@node Differences from AT&T ms
@anchor{Additional ms Macros} @c 1.22.4
@anchor{Missing ms Macros} @c 1.22.4
diff --git a/doc/ms.ms.in b/doc/ms.ms.in
index d0601f6a0..948a270b3 100644
--- a/doc/ms.ms.in
+++ b/doc/ms.ms.in
@@ -1,7 +1,7 @@
.\" groff -ept -ms
.\" nroff -t -rLL=$(stty size | cut -f2 -d' ')n -ms
.\"
-.\" Copyright 2001 Free Software Foundation, Inc.
+.\" Copyright 2001,2026 Free Software Foundation, Inc.
.\" 2020-2025 G. Branden Robinson
.\"
.\" This file is part of groff, the GNU roff typesetting system.
@@ -59,6 +59,7 @@
. ds RH \\n[%]\"
.\}
.ds CF groff @VERSION@\"
+.RP
.TL
Using
.BI groff
@@ -89,7 +90,8 @@ automatically numbered headings,
several paragraph styles,
a variety of text styling options,
footnotes,
-and multi-column page layouts.
+multi-column page layouts,
+and support for PDF features when using -Tpdf.
.
.I ms
supports the
@@ -168,6 +170,14 @@ numerals,
and
.CW \- \[rq]. \[lq]
.
+.PP
+To turn on PDF features please use
+.CW -rPDFFEAT=1
+in the groff command.
+Changes to the operation of
+.I ms
+when PDFFEAT is on are shown in \m[red]red\m[] below.
+.
.
.KS
.NH 2
@@ -450,7 +460,7 @@ Organize longer documents as follows.
Calling the
.CW RP
macro at the beginning of your document puts the document description
-(see below)
+.XR RP "" "" "(see below)"
on a cover page.
.
Otherwise,
@@ -475,7 +485,8 @@ spacing,
headers and footers,
and footnote arrangement.
.
-See section \[lq]Document control settings\[rq] below.
+.XR doc-control "" "" "See section \*[Q]Document control settings\\*[U]"
+below.
.
.
.IP "\fBDocument description\fP"
@@ -485,7 +496,8 @@ one or more authors' names and affiliated institutions,
an abstract,
and a date or other identifier.
.
-See section \[lq]Document description macros\[rq] below.
+.XR doc-desc "" "" "See section \\*[Q]Document description macros\\*[U]"
+below.
.
.
.IP "\fBBody text\fP"
@@ -505,7 +517,8 @@ tables,
diagrams,
and similar material.
.
-See section \[lq]Body text\[rq] below.
+.XR body-text "" "" "See section \\*[Q]Body text\\*[U]"
+below.
.
.
.IP "\fBTables of contents\fP"
@@ -528,7 +541,10 @@ the traditional procedure was to manually relocate the
pages containing
the table of contents between the cover page and the body text.
.
Today,
-page resequencing is more often done in the digital domain.
+page resequencing is more often done in the digital domain,
+\m[red]and if you use a separate title page with
+.XR RP "" "" RP
+the TOC will be positioned immediately after the title.\m[black]
.
An index works similarly,
but because it typically needs to be sorted after collection,
@@ -540,7 +556,7 @@ its preparation requires separate processing.
. br
. bp
.\}
-.NH 1
+.NH 1 doc-control
Document control settings
.XS
Document control settings
@@ -557,7 +573,7 @@ string,
or special character before calling any
.I ms
macro other than
-.CW RP .
+.XR RP . "" "\f[CR]RP\f[]"
.
.\" Improve a column heading if we have the elbow room.
.ds Next \" empty
@@ -697,7 +713,7 @@ this is the case only for output to terminals.
.
.
.\" ------------------------
-.NH 1
+.NH 1 doc-desc
Document description macros
.XS
Document description macros
@@ -766,6 +782,7 @@ is called.
. br
. ne 12v
.\}
+.XM RP
.TS H
box;
lb lb
@@ -955,7 +972,7 @@ T}
. br
. bp
.\}
-.NH 1
+.NH 1 body-text
Body text
.XS
Body text
@@ -1063,7 +1080,8 @@ entered with the keyboard.
These and many others are available as special character escape
sequences\*[-]see
the
-.I groff_char (7)
+.ie \n[PDFFEAT]>0 .pdfhref W -D "man:/7/groff_char" -- \f[I]groff_char\f[](7)
+.el .I groff_char (7)
man page.
.
.TS
@@ -1164,7 +1182,9 @@ The optional
is not indented and is empty by default.
.
It has several applications;
-see subsection \[lq]Lists\[rq] below.
+see subsection
+.XR lists "" "" +
+below.
.
.I width
overrides the indentation amount in
@@ -1263,7 +1283,7 @@ T}
.
.
.KS
-.NH 2
+.NH 2 head
Headings
.XS
Headings
@@ -1290,13 +1310,14 @@ Call a paragraphing macro to end the heading text and
start the
section's content.
.
.
+.XM NH *
.TS
box;
cb cb
lf(CR) lx .
Macro Description
_
-\&.NH [\f[I]depth\f[]] T{
+\&.NH [\f[I]depth\f[]] \fI\m[red][name]\m[]\fP T{
Set an automatically numbered heading.
.
.I ms
@@ -1334,6 +1355,11 @@ and then
.CW ".NH\~3" \[rq]\c \[lq]
.I "groff ms" "" \[em]
emits a warning on the standard error stream.
+\m[red]The
+.I name
+is used to assign a named destination for use with the
+.XR XR "" "" \f[CR].XR\f[]
+command.\m[black]
T}
\&.NH S \f[I]heading-depth-index\f[]\f[R] .\|.\|.\f[] T{
Alternatively,
@@ -1458,13 +1484,14 @@ and
table of contents entries.
.
.
+.XM SH SH
.TS
box;
cb cb
lf(CR) lx .
Macro Description
_
-\&.SH [\f[I]depth\f[]] T{
+\&.SH [\f[I]depth\f[]] \fI\m[red][name]\m[]\fP T{
Set an unnumbered heading.
.
The optional
@@ -1481,6 +1508,11 @@ numbered heading at the same depth when the
and
.CW \[rs]n[PSINCR]
heading size adjustment mechanism is in effect.
+\m[red]The
+.I name
+is used to assign a named destination for use with the
+.XR XR "" "" \f[CR].XR\f[]
+command.\m[black]
T}
.TE
.
@@ -1943,7 +1975,7 @@ _
.KE
.
.
-.NH 2
+.NH 2 lists
Lists
.XS
Lists
@@ -3178,7 +3210,8 @@ Swedish.
Load the desired localization macro package after
.I ms ;
see the
-.I groff_tmac (5)
+.ie \n[PDFFEAT]>0 .pdfhref W -D "man:/5/groff_tmac" -- \fIgroff_tmac\fP(5)
+.el .I groff_tmac (5)
man page.
.
.
@@ -3239,7 +3272,8 @@ The minus sign glyph can also be accessed by the shorthand
.CW \[rs]\[mi] .
.
These and many others are documented in the
-.I groff_char (7)
+.ie \n[PDFFEAT]>0 .pdfhref W -D "man:/7/groff_char" -- \fIgroff_char\fP(7)
+.el .I groff_char (7)
man page.
.
.
@@ -3607,9 +3641,11 @@ script to reorder the pages in
.I troff 's
output,
with
-.I pdfjam (1),
+.ie \n[PDFFEAT]>0 .pdfhref W -D "man:/1/pdfjam" -- \fIpdfjam\fP(1)
+.el .I pdfjam (1)
or with
-.I gropdf (1)'s
+.ie \n[PDFFEAT]>0 .pdfhref W -D "man:/1/gropdf" -A 's -- \fIgropdf\fP(1)
+.el .I gropdf (1)'s
.CW pdfswitchtopage
macro,
for example.
@@ -4051,6 +4087,144 @@ register.
. bp
.\}
.NH 1
+Using PDF features with
+.I ms
+.XS
+Using PDF features with
+.I ms
+.XE
+.LP
+If you run an
+.I ms
+document with
+.CW -Tpdf
+and
+.CW -rPDFFEAT=1
+the PDF features shown in this document
+will be incorporated.
+The PDF produced will show an overview
+bookmark panel, the pdf \*[Q]properties\*[U]
+information will include the document title
+and author(s), any TOC included will have
+clickable entries which can navigate the document,
+and if the document has a cover page (introduced with
+.XR RP ) "" \f[CR]RP\f[]
+the TOC will be relocated to after the cover.
+.LP
+There are also two new macro calls available.
+.
+.
+.pdfhref M -D XR XR
+.TS
+box;
+cb cb
+lf(CR) lx .
+Macro Description
+_
+\m[red].XR \fIname\fP [\fIafter\fP [\fIbefore\fP [\fIhotlink-text\fP]]]\m[]
T{
+The
+.I name
+parameter should match a
+.I name
+given to a
+.XR NH "" "" NH
+or
+.XR SH "" "" SH
+section/subsection.
+(See section
+.XR head ")." "" Headings
+.I hotlink-text
+is the text which will be clickable.
+If the text ends with
+.CW \*[Q]+\*[U]
+or
+.CW \*[Q]*\*[U] ,
+(the expansion characters),
+the text associated with the section heading will replace
+the character (enclosed with double quotes if the
+final character is
+.CW \*[Q]+\*[U] ).
+If no
+.I hotlink-text
+is given, the value of
+.CW \[rs]*[spdf:txt_default]
+is used.
+Which is initially set to
+\*[Q]see: +\*[U].
+(Note the expansion character).
+But you can change it.
+T}
+_
+\m[red].XM \fIname\fP [\fItext\fP]\m[] T{
+Mark a particular position in the document with a
+.I name .
+Any
+.I text
+given will be used to replace a trailing expansion character in an
+.CW .XR
+command which references the
+.I name .
+It is useful if you wish to name an arbitrary location in the
+document, so you can setup a link to a picture, diagram or even
+a single paragraph.
+T}
+.TE
+.LP
+Using
+.CW .XR
+for a \[lq]forward\[rq] link
+(where the destination is \[lq]later\[rq] in the document),
+will not work properly if the link uses expansion characters
+and
+.I groff
+only sees a single pass of the document.
+So either use the full text, without a trailing expansion
+character in the
+.CW .XR
+forward link, or use the multi-pass command
+.
+.
+.LP
+.TS
+box center;
+L.
+T{
+.nf
+.CW
+pdfmom\** --roff -ms -rPDFFEAT=1 file.ms > file.pdf
+T}
+.TE
+.
+.FS
+The command can be shortened to
+.CW "pdfms -rPDFFEAT=1 ..."
+if you have created a link to the
+.CW pdfmom
+command called
+.CW pdfms .
+.FE
+.
+.
+.LP
+Running an
+.I ms
+document with \fInroff\fP,
+is only a single pass, so the above advice about not using
+expansion characters with forward links also applies.
+.LP
+All of the PDF features mentioned in this document can be
+disabled if the
+.I groff
+command includes
+.CW -rPDFFEAT=0 .
+.
+.
+.\" ------------------------
+.if t \{\
+. br
+. bp
+.\}
+.NH 1
Differences from historical
.BI ms
.XS
@@ -4458,7 +4632,8 @@ documents;
contemporary ones should not use them because they can render poorly.
.
See
-.I groff_char (7)
+.ie \n[PDFFEAT]>0 .pdfhref W -D "man:/7/groff_char" -- \fIgroff_char\fP(7)
+.el .I groff_char (7)
instead.
.
.
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index 2969ebd90..a02c8c402 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -10,7 +10,7 @@ manuscript macro package for formatting documents
.\" Legal Terms
.\" ====================================================================
.\"
-.\" Copyright 1989-2021 Free Software Foundation, Inc.
+.\" Copyright 1989-2021,2026 Free Software Foundation, Inc.
.\" 2018-2023 G. Branden Robinson
.\"
.\" Permission is granted to make and distribute verbatim copies of this
@@ -104,7 +104,14 @@ preprocessors for inclusion of tables,
mathematical equations,
diagrams,
and consistently formatted bibliographic citations.
-.
+If the document is intended to be a pdf (by
+using
+.BR -Tpdf ),
+extra pdf features can be enabled by using
+.B -rPDFFEAT=1
+on the command line.
+This will turn on a bookmark panel, clickable
+TOC entries, and other pdf features described below.
.
.P
.I "groff ms"
@@ -157,6 +164,10 @@ Some document types found in other
implementations are specific to AT&T or Berkeley,
and are not supported in
.IR "groff ms" .
+If
+.B PDFFEAT
+is turned on any TOC pages will be placed immediately after
+the cover page.
.
.
.TP
@@ -224,7 +235,10 @@ the traditional procedure was to manually relocate the
pages containing
the table of contents between the cover page and the body text.
.
Today,
-page resequencing is more often done in the digital domain.
+page resequencing is more often done in the digital domain,
+such as when
+.B PDFFEAT
+is turned on.
.
An index works similarly,
but because it typically needs to be sorted after collection,
@@ -847,7 +861,7 @@ section's content.
.
.TP
.BR .NH \~[\c
-.IR depth ]
+.IR depth "] [" name ]
Set an automatically numbered heading.
.
.I ms
@@ -881,6 +895,15 @@ and then
.RB \[lq] ".NH\~3" \[rq],
.I groff ms
emits a warning on the standard error stream.
+If
+.B \%PDFFEAT
+is on and a
+.I name
+is assigned, it can be used as a destination
+.I name
+in an
+.B XR
+internal link.
.
.
.TP
@@ -956,7 +979,7 @@ table of contents entries.
.
.TP
.BR .SH \~[\c
-.IR depth ]
+.IR depth "] [" name
Set an unnumbered heading.
.
The optional
@@ -974,6 +997,16 @@ and
.B \[rs]n[PSINCR]
heading size adjustment mechanism is in effect.
.
+If
+.B \%PDFFEAT
+is on and a
+.I name
+is assigned, it can be used as a destination
+.I name
+in an
+.B XR
+internal link.
+.
.
.P
The
@@ -2341,6 +2374,119 @@ register.
.
.
.\" ====================================================================
+.SH "Using PDF features with \fIms\fP"
+.\" ====================================================================
+.
+If you run an
+.I ms
+document with
+.B -Tpdf
+and
+.B -rPDFFEAT=1
+the PDF features shown in this document
+will be incorporated.
+The PDF produced will show an overview
+bookmark panel, the pdf \[lq]properties\[rq]
+information will include the document title
+and author(s), any TOC included will have
+clickable entries which can navigate the document,
+and if the document has a cover page (introduced with
+.BR RP )
+the TOC will be relocated to after the cover.
+.P
+There are also two new macro calls available.
+.TP
+.BI .XR " name \c"
+.RI " [" after " [" before " [" hotlink\-text "]]]"
+The
+.I name
+parameter should match a
+.I name
+given to a
+.B NH
+or
+.B SH
+section/subsection,
+(See section Headings), or a name set by a
+.B XM
+command.
+The
+.I hotlink-text
+is the text which will be clickable.
+If the text ends with
+.B \[lq]+\[rq]
+or
+.B \[lq]*\[rq]
+(the expansion characters),
+the text associated with the section heading will replace
+the character (enclosed with double quotes if the
+final character is
+.BR \[lq]+\[rq] ).
+If no
+.I hotlink-text
+is given, the value of
+.B \[rs]*[spdf:txt_default]
+is used.
+Which is initially set to
+\[lq]see: +\[rq].
+(Note the expansion character).
+But you can change it.
+.TP
+.BI .XM " name \c"
+.RI [ text ]
+Mark a particular position in the document with a
+.I name .
+Any
+.I text
+given will be used to replace a trailing expansion character in an
+.B XR
+command which references the
+.I name .
+It is useful if you wish to name an arbitrary location in the
+document, so you can setup a link to a picture, diagram or even
+a single paragraph.
+.
+.LP
+Using
+.B .XR
+for a \[lq]forward\[rq] link
+(where the destination is \[lq]later\[rq] in the document),
+will not work properly if the link uses expansion characters
+and
+.I groff
+only sees a single pass of the document.
+So either use the full text, without a trailing expansion
+character in the
+.B .XR
+forward link, or use the multi-pass command
+.
+.
+.LP
+\f[CB]pdfmom --roff -ms -rPDFFEAT=1 file.ms > file.pdf\f[]
+.LP
+The command can be shortened to
+.B "pdfms -rPDFFEAT=1 ..."
+if you have created a link to the
+.I pdfmom
+command called
+.I pdfms .
+.
+.
+.LP
+Running an
+.I ms
+document with \fInroff\fP,
+is only a single pass, so the above advice about not using
+expansion characters with forward links also applies.
+.LP
+All of the PDF features mentioned in this document can be
+disabled if the
+.I groff
+command includes
+.B \%-rPDFFEAT=0 .
+.
+.
+.\" ====================================================================
.SH "Differences from AT&T \f[I]ms\f[]"
.\" ====================================================================
.
diff --git a/tmac/s.tmac b/tmac/s.tmac
index 73a1960c9..aa67a4d0a 100644
--- a/tmac/s.tmac
+++ b/tmac/s.tmac
@@ -1,6 +1,6 @@
.ig
-Copyright 1989-2021 Free Software Foundation, Inc.
+Copyright 1989-2021,2026 Free Software Foundation, Inc.
2022-2023 G. Branden Robinson
Written by James Clark ([email protected])
@@ -100,6 +100,83 @@ along with this program. If not, see
<http://www.gnu.org/licenses/>.
. @divert \\$*
..
.
+.if !r PDFFEAT .nr PDFFEAT 0
+.if !'\?\*[.T]\?'\?pdf\?' .nr PDFFEAT 0
+.nr nhct 0 1
+.nr NHbox 0
+.ds spdf:txt_default see: +
+.if \n[PDFFEAT]=1 \{\
+.nr PDFHREF.VIEW.LEADING 10.0p
+.nr gottitle*pdf 0
+.ds pdf:curcol default
+.\}
+.
+.de @XR
+. if !'\\*[.T]'pdf' \{\
+. nop \\$3\\$4\\$2
+. return
+. \}
+. ds spdf!txt \\*[spdf:txt_default]
+. ds spdf!opts -D "\\$1"
+. if \\n(.$>1 .as spdf!opts " -A "\\$2"
+. if \\n(.$>2 .as spdf!opts " -P "\\$3"
+. if \\n(.$>3 .ds spdf!txt \\$4
+. ds spdf!ast \\*[spdf!txt]
+. ds spdf!ast_ql
+. ds spdf!ast_qr
+. substring spdf!ast -1 -1
+. if '\\*[spdf!ast]'+' \{\
+. ds spdf!ast *
+. ds spdf!ast_ql \[lq]
+. ds spdf!ast_qr \[rq]
+. \}
+. if '\\*[spdf!ast]'*' \{\
+. pdf:lookup \\$1
+. ie !'\\*[pdf:lookup-result]'' \{\
+. if '\\*[spdf!ast]'*' \{\
+. chop spdf!txt
+. as spdf!txt \&\\*[spdf!ast_ql]\\*[pdf:lookup-value]\\*[spdf!ast_qr]
+. \}
+. \}
+. el \{\
+. ds spdf!txt Unknown(\\$1)
+. if !rspdf!unk \{\
+. if '\\*[.T]'pdf' .tm \
+[ms]: \\n[.F]:\\n[.c]: forward reference to '\\$1' detected (please run using
'pdfmom --roff -ms')
+. nr spdf!unk 1
+. \}
+. \}
+. \}
+. ie \\n[PDFFEAT]>0 .pdfhref L \\*[spdf!opts] -- \\*[spdf!txt]\c
+. el .nop \\$3\\*[spdf!txt]\\$2
+. rm spdf!opts
+. rm spdf!txt
+. rm spdf!ast
+. rm spdf!ast_ql
+. rm spdf!ast_qr
+..
+.
+.
+.de @XM
+. ie \\n[PDFFEAT]>0 \{\
+. ds pdf:id \\$1
+. shift
+. pdfhref M -D \\*[pdf:id] -- \\$@
+. rm pdf:id
+. \}
+. el \{\
+. nr pdf:bm.nk +1
+. if !d pdf:bm\\n[pdf:bm.nk].tag \{\
+. ds pdf:bm\\n[pdf:bm.nk].tag \\$1
+. ds pdf:bm\\n[pdf:bm.nk].val \\$2
+. \}
+. if d PDF.EXPORT \{\
+. tm .ds pdf:bm\\n[pdf:bm.nk].tag \\$1
+. tm .ds pdf:bm\\n[pdf:bm.nk].val \\$2
+. \}
+. \}
+..
+.
.\" Wrap the `bp` request so that we disregard the enablement of
.\" no-space mode, which we enter after displays and equations to
.\" prevent multiple sources of vertical space (like the DD and PD
@@ -250,6 +327,12 @@ along with this program. If not, see
<http://www.gnu.org/licenses/>.
. shift
.\}
.if rPO .po \\n(POu
+.if \\n[PDFFEAT]=1 \{\
+. if \\n[cov*rp-no-repeat-info]=1 .nr cov*pdf 1
+. pdfpagename title
+. nr gottitle*pdf 1
+.
+.\}
..
.de TL
.br
@@ -320,6 +403,8 @@ along with this program. If not, see
<http://www.gnu.org/licenses/>.
.als MC LP
.als RT LP
.als XS LP
+.als XR LP
+.als XM LP
.
.de cov*ab-init
.als cov*ab-init @nop
@@ -345,6 +430,8 @@ along with this program. If not, see
<http://www.gnu.org/licenses/>.
.als AU par@AU
.als AI par@AI
.als TL par@TL
+.als XR @XR
+.als XM @XM
..
.
.de @AB
@@ -421,6 +508,31 @@ along with this program. If not, see
<http://www.gnu.org/licenses/>.
. \}
. br
.\}
+.if \\n[PDFFEAT]=1 \{\
+. if d cov*tl-div \{\
+. asciify cov*tl-div
+. chop cov*tl-div
+. pdfinfo /Title \\*[cov*tl-div]
+. \}
+. ds pdfauthor \"
+. nr cov*i 1
+. while \\n[cov*i]<=\\n[cov*n-au] \{\
+. asciify cov*au-div!\\n[cov*i]
+. chop cov*au-div!\\n[cov*i]
+. if \\n[cov*i]>1 .as pdfauthor ", "
+. as pdfauthor \\*[cov*au-div!\\n[cov*i]]
+. nr cov*i +1
+. \}
+. pdfinfo /Author "\\*[pdfauthor]"
+. pdfpagenumbering D . 1
+. fl
+. sp -1v
+. di toc*div
+. pdfpagenumbering r . 1
+. fl
+. sp -1v
+. di
+.\}
..
.de cov*rp-print
.nr cov*page-length \\n[.p]
@@ -1572,11 +1684,19 @@ along with this program. If not, see
<http://www.gnu.org/licenses/>.
.\" AT&T ms implementation does not expect an argument, but groff ms
.\" allows ".SH n" to make a heading's type size match ".NH n", for same
.\" "n", when \n[GROWPS] and \n[PSINCR] are set.
+. if \\n[NHbox] .br \" needed to fire off @NH-end if 2 NH's adjacent
. nr sh*psincr 0
. if 0\\$1>0 .nr sh*psincr (\\n[GROWPS]-0\\$1)*\\n[PSINCR]
. SH-NO-TAG
. DEVTAG-SH 1
. if '\*(.T'html' .nr s@devtag-needs-end-of-heading 1
+. ds nh*bm sh:bm\\n+[nhct]
+. if \\n[.$]>1 .ds nh*bm \\$2
+.\" . if \\n[PDFFEAT]>0 \{\
+. nr NHbox +1
+. box @NHpdf
+. dt 1v @NH-end
+.\" . \}
..
.\" TL, AU, and AI are aliased to these in cov*ab-init.
.de par@TL
@@ -1621,9 +1741,9 @@ along with this program. If not, see
<http://www.gnu.org/licenses/>.
.de \\$1
.ds par*lic \" empty
.ds par*ic \" empty
-.if \\n[.$]>2 \{\
-. as par*lic \,\"
-. as par*ic \/\"
+.if (\\n[.$]>2) \{\
+. as par*lic \,\"
+. as par*ic \/\"
.\}
.if \En[.$]>3 .@warning excess arguments to .\\$1 ignored
.ie \En[.$] \{\
@@ -1732,6 +1852,7 @@ along with this program. If not, see
<http://www.gnu.org/licenses/>.
.als SN SN-DOT
.\" numbered heading
.de @NH
+.if \\n[NHbox] .br \" needed to fire off @NH-end if 2 NH's adjacent
.ie '\\$1'S' \{\
. shift
. nr nh*hl 0
@@ -1782,6 +1903,34 @@ along with this program. If not, see
<http://www.gnu.org/licenses/>.
.DEVTAG-NH "\\$1"
.if '\*(.T'html' .nr s@devtag-needs-end-of-heading 1
\\*[SN-STYLE]
+. ds nh*bm nh:bm\\n+[nhct]
+. if \\n[.$]>1 .ds nh*bm \\$2
+.\" . if \\n[PDFFEAT]>0 \{\
+. nr NHbox +1
+. box @NHpdf
+. dt 1v @NH-end
+.\" . \}
+..
+.de @NH-end
+. nr NHbox -1
+. fl
+. box
+. chop @NHpdf
+\&\\*[@NHpdf]
+. asciify @NHpdf
+. ie \\n[PDFFEAT]>0 .pdfbookmark -T \\*[nh*bm] \\n[nh*hl] "\\*[@NHpdf]"
+. el \{\
+. nr pdf:bm.nk +1
+. if !d pdf:bm\\n[pdf:bm.nk].tag \{\
+. ds pdf:bm\\n[pdf:bm.nk].tag \\*[nh*bm]
+. ds pdf:bm\\n[pdf:bm.nk].val \\*[@NHpdf]
+. \}
+. if d PDF.EXPORT \{\
+. tm .ds pdf:bm\\n[pdf:bm.nk].tag \\*[nh*bm]
+. tm .ds pdf:bm\\n[pdf:bm.nk].val \\*[@NHpdf]
+. \}
+. \}
+. rm @NHpdf
..
.\" ****************************
.\" ******** module toc ********
@@ -1809,11 +1958,16 @@ along with this program. If not, see
<http://www.gnu.org/licenses/>.
. na
. ll -8n \" XXX: take TC-MARGIN into account?
. in (n;0\\$2)
+. if \\n[PDFFEAT]>0 \{\
+. pdfhref L -S -D \\*[nh*bm]
+. sp -1v
+. \}
.\}
.el .@error .XA without .XS
..
.de XE
.ie '\\n(.z'toc*div' \{\
+. if \\n[PDFFEAT]>0 .nop \X'pdf: markend'\m[default]\c
. if d toc*num .toc*end-entry
. ev
. di
@@ -1869,6 +2023,7 @@ along with this program. If not, see
<http://www.gnu.org/licenses/>.
.XN-INIT
.XH-UPDATE-TOC \\n[nh*hl] \\$@
\&\\$*
+.sp
..
.de toc*end-entry
.if !'\\*[toc*num]'' \\a\\t\\*[toc*num]
@@ -1899,6 +2054,7 @@ along with this program. If not, see
<http://www.gnu.org/licenses/>.
..
.\" print the table of contents on page i
.de TC
+. if \\n[PDFFEAT]=1 .if \\n[gottitle*pdf] .pdfswitchtopage after title
.P1
.pg@begin 1 i
.PX \\$1
_______________________________________________
groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
