groff-pdfmark

Fork

Some typographic and grammatical man page corrections.

* pdfroff.1.man (option --no-kill-null-pages): s/where/whence/ as
argument descriptor; s/any/all/ as valid argument value.

Use RCS keywords more consistently.

* tmac/opmode.tmac tmac/pdfmark.tmac tmac/pdfroff.tmac
* tmac/spdf.tmac tmac/toc.tmac ($Id$, $RCSfile$): Add annotations.

Provide pdfroff binding macros for rendering man pages.

* tmac/anpdf.tmac: New file; it is a wrapper around andoc.tmac,
supporting use of -man only; (currently, -mdoc is not supported).

* Makefile.in (man2pdf): Use it.
(MAN2PDF_FLAGS): Enable features, controlled by addition of...
(CS, CT): ...these registers; set both to 1.

* tmac/sanitize.tmac (sanitize:esc-f): New alias; map it to...
(sanitize:esc-generic): ...this, making its handling analogous to...
(sanitize:esc-F): ...this.

* tmac/strcase.tmac: New file; it retrospectively emulates...
(.stringup, .stringdown): ...this pair of new groff-1.23 requests.

* pdfroff.sh (MANPDF_OPTIONS): New internal-use variable; it provides
a hook capability, whereby '-manpdf' triggers processing of '\" hints
in man page source, causing nominated preprocessors to be invoked.

* pdfroff.1.man: Various layout, and grammatical adjustments;
reserve vertical space, as required, to avoid widow and orphan lines.
(PDFROFF_POSTPROCESSOR_COMMAND): Disallow a page break within text
specifying the default command.

Describe method of finished document assembly.

* pdfmark.ms (Section 4.1.7): Add content.
(Section 4.1.4): Omit "$" prompt from "pdfroff" command example,
to maintain consistency with all earlier, and new examples.

Describe method of document body formatting.

* pdfmark.ms (Section 4.1.6): Add content.

Describe default method of table of contents generation.

* pdfmark.ms (Section 4.1.5): Add content.

Eliminate a macro loading order dependency.

* tmac/opmode.tmac [!rPDFOPMODE] (OPMODE): Define it, otherwise...
[rPDFOPMODE] (OPMODE): ...alias it, to make them equivalent.

Add a commit log typographic error notification.

* pdfroff.ms: File name reference is bogus, in four commits, dated
between 2023-04-11 and 2023-04-28; correct file name is...
* pdfmark.ms: ...this.

Describe provisions for formatting front-matter.

* pdfroff.ms (Section 4.1.4): Add content.

Describe in-document optional processing hints support.

* pdfroff.ms (Section 4.1.3): Add content.

Describe pdfroff's reference resolution procedure.

* pdfroff.ms (Section 4.1.2): Add content.

Add description of pdfroff operating principles.

* pdfroff.ms (Section 4.1.1): Add content, and subsequent link
target headings, as required to satisfy planned forward references.
(Section 4.2): Modify heading text, to clarify relationship to...
(Section 4.1.2): ...this planned content.

Handle hyphenation special characters in PDF outlines.

* tmac/sanitize.tmac (sanitize): Interpret "\%" specially.
(sanitize:esc-(, sanitize:esc-(hy): New macros; they add generic
support for "\(xx", and specialization for "\(hy", respectively.

Manage page break placement within the table of contents.

* pdfmark.ms (toc.end): New document-local macro; initially define
with no content, and subsequently remap as an alias for KE, after
first use, to close a not-yet-opened KS/KE block, within...
(toc.outline): ...this; use toc.end in place of KE, to close any
previously opened KS/KE block, then insert KS to open a new block,
prior to output of any TOC entry at outline-level one.
(toc end): Add after inclusion of TOC file, to close its final,
residually open KS/KE block.

Add PDF publishing process introduction.

* pdfmark.ms (Section 4): Add introductory text.
(Section 4.1): Insert new subsection, with introductory content,
referring to the pdfroff command; increment following subsection
numbers accordingly.

Implement a standardized snapshot distribution procedure.

* configure.ac (AC_INIT): Assign package name and version.
(chmod): Perform AC_PATH_PROG assignment to "CHMOD" AC_SUBST variable.

* Makefile.in: Perform some cosmetic clean-up.
(PACKAGE_TARNAME, PACKAGE_VERSION, CHMOD): Use autoconf assignments.
(pdfroff-posix, pdfroff-win32): New build targets; they build variants
of pdfroff suitable for POSIX, and MS-Windows, respectively, using...
(CHMOD): ...this autoconf-assigned program, to make them executable.
(dist): New primary build target; it delegates operations to...
(srcdist, bindist, docdist, mandist, tmacdist): ...these subsidiary
build targets; implement them; they employ programs identified by...
(TAR_CMD, ZIP_CMD, ZIP_EXT): ...these new make variables; define them,
permitting user override, subject to GNU tar, and XZ compatibility.

Implement a duplex printing layout capability.

* pdfmark.ms [duplex] (BT): Augment macro definition, to alternate
left and right margin widths, between even and odd numbered pages;
activated by "-duplex" option to pdfroff command, (i.e. define a
string called "uplex", with "-duplex=true", for example).
[duplex && pdfroff] (preserve_blank_pages): Suggest it for...
[body]: ...this document assembly component.

Support in-document hints for --no-kill-null-pages option.

* pdfroff.sh [--no-kill-null-pages]: Record option argument in...
(preserve_blank_pages): ...this shell variable; defer its evaluation
until processing of in-document hints, during reference resolution.
(safe_hints): Add "preserve_blank_pages" to authorized list.

Number pages contiguously, including front-matter page count.

* pdfmark.ms (PG-ADVANCE-TO-ODD): New macro; it advances the effective
page number to next available odd-numbered page, while suppressing the
display of the page number on that page; use it to number the starting
page number for the document text, accounting for the number of pages
which are already occupied by front-matter, and table of contents.
(HD): Define groff-ms hook, to restore normal page numbering sequence,
after use of PG-ADVANCE-TO-ODD to establish a starting page number.
(XH-APPENDIX): Simplify it, by use of PG-ADVANCE-TO-ODD; this offers
the added benefit of starting each appendix at an odd page number.

Improve selectivity of pdfroff's blank-page removal feature.

* pdfroff.sh (--no-kill-null-pages): Accept an optional argument,
with permitted values of "all", "body", or "toc"; interpret to set...
(TC_FILTER, BD_FILTER): ...these new internal-use variables, which
subsequently establish the scope of operation for...
(PDFROFF_COLLATE): ...this internal filter.

* pdfroff.1.man (--no-kill-null-pages): Document argument usage.

* tmac/spdf.tmac (TC) [PHASE>1]: Make it a no-op.

Append GNU Free Documentation Licence to document body.

* fdl: New directory.
* fdl/fdl-v1.3.txt: New file; it is an unmodified verbatim copy of
the original FDL plain-text document, imported from groff sources.

* fdl/Makefile.sub: New file; it implements an inline txt2roff filter,
suitable for creating a generic groff-marked-up copy of the FDL.

* fdl/fdl-v1.3.ms.in: New file; it provides boiler-plate mark-up to
map txt2roff generic mark-up for use with groff-ms.

* Makefile.in: Include fdl/Makefile.sub, configured by...
(txt2roff_srcdir, txt2roff_tmac_suffix): ...these unconditional...
[fdl-v1.3.ms] (TXT2ROFF_PREFIX): ...and this conditional assignment.
(pdfmark.pdf): Add dependency on fdl-v1.3.ms

* pdfmark.ms (Appendix A): Define and use...
(XH-APPENDIX, XH-APPENDIX-NUMBER-FORMAT): ...these new local macros,
to set up the appendix heading, and page numbering format; include
generated file fdl-v1.3.ms, subject to formatting specified by...
(FDL-SETUP, FDL-BACKUP-AND-REPLACE, FDL-SH-START, FDL-TI-START)
(FDL-RESTORE): ...these temporary local macros, which also use...
(fdl:replacement.tag, fdl:title.block): ...these temporary strings...
(fdl:title.lines): ...and this temporary numeric register.
(TC-MARGIN): Increase its width, to accommodate up to seven digits.
(XH-UPDATE-TOC) [%%]: Use as pageref, when defined; it represents the
true page number, when \n% has been temporarily reset to one, as it is
by XH-APPENDIX, after saving its original value in \n(%%, to suppress
page numbering at particular locations within the document body.

Add a copyright assignment page to document front-matter.

* cover.ms: Add template content, supported by...
(PUB, ASSERT-RIGHTS, FDL-REFERENCE): ...these new public macros...
(pub@initial, pub@collect, pub@revised, pub@enum, pub@rights)
(pub@post, au@assert-rights, au@asserted, au@uk-asserted): ...these
new internal-use helper macros, additionally augmented by...
(pub@preformat.content): ...this new temporary diversion...
(FDL-SECTION, FDL-SECTION-TITLE, pub@copyright, pub@series, pub@last)
(pub@revlist, au@pronoun, ASSERT-RIGHTS@his, ASSERT-RIGHTS@her)
(au@plural, au@pending, au@list): ...these new strings, and...
(au@count, pub@revcount): ...these new counter registers.
(au@next): Extend it, to assign, and manage...
(au@count, au@list, au@pending): ...these.

* pdfmark.ms (ASSERT-RIGHTS, FDL-REFERENCE, PUB): Use them.

Ignore potentially unsafe pdfroff hint assignments.

* pdfroff.sh (safe_hints): New shell variable; it enumerates the
names of hint variables which are deemed to be safe for assignment.
(safer_hint): New shell function; it ensures that assignments are made
for variables which are enumerated as "safe"; use it to evaluate all
hints which are identified during pdfhref reference resolution.

Fix a constant-width font usage inconsistency.

* pdfmark.ms (Section 2.5.5.4): Consistently use '\f(CI', not '\fI',
for named argument identification in document mark-up examples.

Correct some minor typographic errors.

* pdfroff.1.man (See also): Identify...
(groff-pdfmark): ...this as reference manual distriutor.
(Environment): In reference to GROFF_AWK_INTERPRETER, correct
spelling of 'continues'; s/continue/continues/

Support safe mode TOC record collection within pdfroff.

* pdfroff.sh [pdfroff-option:set]: Evaluate early, relocating...
[toc_relocation=enabled]: ...this option set-up to, and adding...
[toc_file=<file_name>]: ...this assignment at end of first reference
resolution loop pass, and updating toc_file content at end of this,
and every subsequent pass of this loop.

* tmac/toc.tmac (toc file) [pdfroff]: Emit 'toc_file' hint.
[!pdfroff]: Fall back to unsafe mode file output.

* Makefile.in (%.pdf: %.ms): Remove "-U" option from 'pdfroff'
command invocation; it is no longer required.

Add support for in-document pdfroff option hints.

* tmac/pdfroff.tmac: New macro file; it defines...
(pdfroff): ...a default implementation for this new macro, and...
(PDF-TOC-ONLY, PDF-BODY-TEXT): ...these (effectively constant)
processing phase indicating register values.

* tmac/spdf.tmac (TC): Use pdfroff macro, when defined, to set...
[toc_relocation=enabled]: ...this pdfroff operating mode option.

* Makefile.in (pdfmark.ms): Add a further dependency on...
(pdfroff.tmac): ...this new macro file.

* pdfroff.sh (GROFF_STYLE): Append "-mpdfroff" option.

Generalize support for phased output mode control.

* tmac/spdf.tmac (OP, OPMODE): Factor out definitions; relocate to...
* tmac/opmode.tmac: ...this additional new macro file.

* tmac/spdf.tmac (opmode.tmac): Source it.

* Makefile.in (pdfmark.ms): Add a further dependency on...
(opmode.tmac): ...this new macro file.

Eliminate warnings emanating from document source.

* pdfmark.ms (\s): Use 'z' units, not 'p', throughout.
(toc.refmark): Separate collected text for TOC entry into...
(toc.refmark.tag): ...this pdfhref destination name tag, and...
(toc.refmark.text): ...this additional text; when passed to...
(toc.pageref): ...here, quote it for expansion in pdfhref.
(pdf-publishing): Do not encode reference in terms of...
(XR): ...this; it requires the semantics of...
(XR-NO-PREFIX): this, hence use it; do not redefine...
(PDFHREF.PREFIX): ...this; it is no longer required.
(CW): Quote arguments with embedded tabs.

Eliminate warnings emanating from pdfmark macros.

* tmac/pdfmark.tmac (pdf*href.format): On entry, initialize...
(PDFHREF.TEXT): ...this string, without any content, then append...
(PDFHREF.PREFIX): ...this, only if it has been, and remains defined.
(pdf:note.newline): Ensure it is defined, on package load.