groff-pdfmark

Fork

Remove inappropriate discretionary hyphenation points.

* man/pdfroff.1.man man/pdfroff.7.man man/groff_toc.man (.UR):
Delete '\%' prefix from URI argument; it was intended to prevent
hyphenation, but it actually allows insertion of a discretionary
hyphen, and line break, within the bracketted URI output string,
between the opening angle bracket and the URI itself.

Drop synopsis section from groff_toc.7 manual page.

* man/groff_toc.7.man: Add paragraph marks.
(Synopsis): Delete section; fold its relevant content into...
(Usage): ...this alternative section, as appropriate; correct...
(.toc error): ...this malformed syntax specification.
(Authors): Some minor wording improvement.

Use boiler-plate to standardize manpdf fallback macros.

* Makefile.in (AWK, GREP, USORT): New macros, defined by...
* configure.ac (AC_PROG_AWK, AC_PROG_GREP): ...these, and...
(SORT, UNIQ): ...these AC_PATH_PROG substitutions.

* Makefile.in (manpdf_fallbacks): New macro; it represents...
* man/manpdf-fallbacks.in: ...this new file; it implements in-line
fallbacks for each non-standard -manpdf extension macro; it also
implements a fallback for groff-1.23's .MR macro, for use on any
platform which lacks it, and defines host URI mappings for PDF
renditions of project-local manual pages.

* Makefile.in (manpage_update_script): Add substitutions for...
(@ENUMERATE_MR_REFERENCES@, @IMPORT_LOCAL_FALLBACK_MACROS@): ...each
of these place-holders; appropriate content is generated by...
(usort_awk, refgen_script, refmap_script, mxmap_script, mxgen_script):
...these new in-line scripts, extracting content as appropriate, from
the boiler-plate defined within the file which is represented by...
(manpdf_fallbacks): ...this new macro; it is used by...
(%.mr, %.mx): ...these new build rules; make them prerequisites...
(all-manpages, all-pdf-manpages): ...for both of these.

* man/pdfroff.1.man man/pdfroff.7.man man/groff_toc.man
(@ENUMERATE_MR_REFERENCES@, @IMPORT_LOCAL_FALLBACK_MACROS@): Use them
in place of, and to avoid duplication of, content abstracted from...
* man/manpdf-fallbacks.in: ...here.

* tmac/anpdf.tmac (MX-HOST): Make it consistent with usage as...
* man/manpdf-fallbacks.in: ...specified here.

Add a convenience makefile rule to build everything.

* Makefile.in (all-inclusive): New build goal; it incorporates...
(all, all-manpages, all-pdf-manpages): ...all of these.

Correct a malformed manpage reference.

* man/pdfroff.1.man (.MR gs 1): Should use...
(.MR gs @MAN1EXT@): ...this preferred form; correct it.

Configure project-hosted manpage URI references.

* tmac/anpdf.tmac (MX-HOST): Rename original macro, as...
(MR-HOST): ...this; update references accordingly, and then...
(MX-HOST): ...redefine as new; this replacement version now maps
individual manpage references to specific MR-HOST URI indicies.

* configure.ac (MANPAGE_URI_ROOT, MANPAGE_URI_PATH): New AC_SUBST
variables; together, they specify the groff-pdfmark project URI.

* Makefile.in (MANPAGE_URI_ROOT, MANPAGE_URI_PATH): Use them to...
(MR_HOST_3_URI_ROOT, MR_HOST_3_URI_PATH): ...define these new macros,
respectively; substitute their values into generated manpages, via...
(manpage_update_script): ...this internal sed script, mapping to...
(MR_HOST_3_URI, MR_HOST_3_DIR): ...these tags, respectively.

* man/pdfroff.7.man
* man/groff_toc.7.man [groff && MR-HOST defined]: Expand...
(MR_HOST_3_URI, MR_HOST_3_DIR): ...these substitution tags, through...
(MR-HOST-3-URI): ...this troff string, assigning to MR-HOST index 3.
(pdfroff.@MAN1EXT@): Map it to MR-HOST index 3, using...
(MX-HOST): ...this.

* man/pdfroff.7.man (groff_pdfmark.@MAN7EXT@): Also map this, and...
(groff_toc.@MAN7EXT@): ...this, to MR-HOST index 3, again using...
(MX-HOST): ...this.

Differentiate groff-pdfmark and groff package versions.

* configure.ac (AC_INIT): Specify YY.MM style groff-pdfmark version.
(GROFF_PACKAGE_VERSION): New AC_SUBST variable; define it to represent
the groff version, with which groff-pdfmark is nominally associated.
(MANPAGE_DATE_FORMAT): New AC_SUBST variable; define it to specify
the default date format for use in groff-pdfmark manual pages.

* Makefile.in (PACKAGE_BASE_VERSION): Use GROFF_PACKAGE_VERSION.
(MANPAGE_DATE): Use MANPAGE_DATE_FORMAT.

Support internal references to manpage headings.

* tmac/anpdf.tmac (SR, RK): New macros; define them in terms of...
(anpdf-ref-heading, anpdf-ref-kern): ...these new macros, and...
(anpdf-ref-kern-list): ...this new string.

* man/pdfroff.1.man man/pdfroff.7.man
* man/groff_toc.7.man [!manpdf] (SR, RK): Define fallbacks.
(SR, RK): Use them.

Remap some special escape tokens in sanitized text.

* tmac/sanitize.tmac (sanitize:scan-space-token.remap): New macro;
define it, intending it exclusively for conditional internal use by...
(sanitize) ["\ ", "\~", "\0"]: ...this, to substitute ASCII SP.
(sanitize) ["\-"]: Explicitly substitute ASCII hyphen-minus.

Use explicit naming for manpage outline reference marks.

* tmac/anpdf.tmac (anpdf-reload-man): Increase...
(PDFHREF.VIEW.LEADING): ...this, for manpage title reference marks.
(anpdf-ref, anpdf-ref-outline): New macros; together, they generate
explicit reference mark names, to associate with manpage headings.
(anpdf-sh-wrapper): Use them.

Correct manpage page trap and end macro handling.

* tmac/anpdf.tmac (anpdf-atend): New macro; assign it...
(anpdf-reload-man): ...here, as end macro replacement for...
(an-end): ...this default groff_man(7) internal end macro.
(anpdf-reload-man): Append groff_pdfhref(7) page trap handler to...
(PT): ...this groff_man(7) page trap hook.

Eliminate some compatibility mode redundancy.

* tmac/anpdf.tmac (anpdf-reload-man): Use "de1" as defining request;
thus, within it, "do" requests are redundant; remove them.

Do not override user preferences in manpage sources.

* man/pdfroff.1.man man/pdfroff.7.man
* man/groff_toc.7.man (CS, CT, MF): Do not assign overriding values;
groff_man(7) defaults may be adjusted by alternative assignments in
man.local, but ultimate reassignment is the prerogative of the user.

* man/groff_pdfroff.1.man (*groff_pdfroff_1_CS, *groff_pdfroff_1_CT)
(*groff_pdfroff_1_MF): Backup stores not required; delete references.

* man/groff_pdfroff.7.man (*groff_pdfroff_7_CS, *groff_pdfroff_7_CT)
(*groff_pdfroff_7_MF): Backup stores not required; delete references.

* man/groff_toc.7.man (*groff_toc_7_CS, *groff_toc_7_CT)
(*groff_toc_7_MF): Backup stores not required; delete references.

Some manual page formatting adjustments.

* man/pdfroff.1.man man/pdfroff.7.man man/groff_toc.7.man: Some
miscellaneous input file format adjustments, output font ajustments,
and discretionary hyphenation control changes.

Include control character in macro usage annotations.

* tmac/anpdf.tmac (Usage): Consistently include "." as control
character, in every comment which specifies the usage synopsis for
every internal, and public API macro.

Support alternative manpage URI host specifications.

* tmac/anpdf.tmac (MX-HOST): New macro; define it, and use it to...
(anpdf-manpage-provider-0, anpdf-manpage-provider-1): ...define these
two built-in default manpage URI templates.
(anpdf-manpage-reference): Use...
(anpdf-manpage-provider-1): ...this as nominal default, but let...
(MX:\\$1.\\$2): ...this manpage-specific numeric index override it.
(anpdf-manpage-reference): Interpret and apply...
(MF): ...this, inline; apply italic corrections as required; hence...
(anpdf-ic): ...this internal template is not required; delete it.

Validate link destination name assignments.

* tmac/pdfmark.tmac (pdfhref): In internal-use macros...
(pdf*href-D, pdf*href.set): ...accept only destination name arguments
which are valid as groff identifiers.

Add groff_toc.7 manual page.

* man/groff_toc.7.man: New file.
* Makefile.in (manpages): Add reference to...
(groff_toc.7): ...this.

Create example macros for groff_toc integration.

* pdfroff.ms (XH-UPDATE-TOC, toc.outline, toc.refmark)
(toc.pageref, toc.end): Factor out; relocate to, and include...
* tmac/spdf-toc.tmac: ...this new file.

* Makefile.in (pdfmark.pdf): Add dependency on...
(spdf-toc.tmac): ...this.

Reorganize manpage sources; add pdfroff.7

* man: New directory; relocate...
* pdfroff.1.man: ...this file, without change, to...
* man/pdfroff.1.man: ...here.

* man/pdfroff.7.man: New file.

* Makefile.in [vpath] (%.man): Note change of directory.
(all-manpages, all-pdf-manpages): New make goals; alias to...
(manpages, pdf-manpages): ...these respectively; use them...
(%:%.man, %.pdf:%.man): ...here, converting each of these normal
pattern rules to static pattern rules, respectively.
(manpage_update_script): Add translation for...
(SITE_TMACDIR): ...this.

Adopt standard man-pages(7) styling conventions.

* tmac/anpdf.tmac [-dMF=R] (anpdf-ic): Kludge it, so that it
is interpreted as if it were -dMF=B, when processed within...
(MR): ...this macro's context.

* pdfroff.1.man (pdfroff): Set all references in bold type.
(awk, gawk, groff, gs, mawk, mktemp, nawk, sed, groff_tmac): add
manual section references, as appropriate, and set all using...
(MR): ...this; replicate all, as an enumerated list, under...
(See also): ...this section heading.
(-rCS, -rCT, -dMF) [\n(.g]: Preserve initial settings, on entry,
and subsequently restore them, on exit; internally...
(CS, CT): ...set both to one, for standards conformance.
(MF): Keep initial setting, until TH has been evaluated, then
set it to "B", for standard conformant evaluation of...
(MR): ...this, on every occasion of its use.

A minor pdfroff.1 manpage correction.

* pdfroff.1.man (TH): s/groff/groff-pdfmark/
(AUTHORS): Refer to author's "OSDN web-site", in preference
to "OSDN site".

* Makefile.in (MANPAGE_DATE): New user overridable variable,
specifying the publication date for all generated manual pages;
define it, by shell substitution, to reflect current date.
(manpage_update_script): Use it, in substitution for...
(MDATE): ...this field value.

Revisit dynamic identifier names with invalid content.

* tmac/pdfmark.tmac (pdf*href.format): Simplify change from
2024-03-25; test identifier for validity, as "while" condition,
then break loop if no matching macro identifier defined.
(pdfbookmark, pdf*href, pdf*href-D, pdf*href-M, pdfnote): Use
corresponding while loop control logic.

Describe duplex printing layout adjustment techniques.

* pdfmark.ms (Section 3.1.3, Section 4.2): Add content.
(PO): Compute initial value, to balance left and right margins.
[duplex] (PO): Tweak assignment syntax; add sanity checks.
[duplex] (BT): Assign alternating PO, only as required.
(PG-ADVANCE-TO-ODD): Simplify, and rename it as...
(NEW-RECTO-PAGE): ...this; update references.

Eliminate trailing white-space from document source.

* pdfmark.ms pdfroff.sh tmac/pdfmark.tmac tmac/s.tmac
* fdl/fdl-v1.3.txt fdl/Makefile.sub: Delete all extraneous
white-space, where present, from the end of every input line.

Avoid dynamic identifier names with invalid content.

* tmac/pdfmark.tmac (pdf*href.format): Verify each potential
formatting keyword, read from the input data stream, as a valid
groff identifier, before attempting to match it.

Designate the GNU Free Documentation License as invariant.

* cover.ms (pub@licensing): Update grant of permissions to copy,
distribute, and/or modify, to declare Appendix A, the content of
which is the GNU Free Documentation License, as "invariant", thus
forbidding its modification in any redistributed publication of
the associated document.

Propagate FDL section headings to outline and TOC.

* pdfmark.ms (FDL-XH-UPDATE-TOC): New helper macro, used by...
(FDL-XH): ...this new document-local macro variant; define them.
* fdl/fdl-v1.3.ms.in (FDL-SH): Some heading format adjustments.
[d FDL-XH]: Invoke it.

Avoid necessity to repeat document meta-data.

* pdfmark.ms (mso): Include...
* cover-info.ms: New file; complementary to cover.ms, when included by
document source, it defines alternative implementations of CS, AU, and
CE macros, which extract title and author meta-data from within inline
CS ... CE blocks, propagating their content to PDF meta-data...
(.pdfinfo /Title, .pdfinfo /Author): ...specs, respectively.

* pdfmark.ms (.pdfinfo): Delete previously redundant...
(/Title, /Author): ...meta-data assignments.

* Makefile.in (tmacdir): Add direct ${srcdir} reference.
(pdfmark.pdf): Assert additional build-time dependencies on...
* cover.ms cover-info.ms: ...each of these.

Correct some misplaced line continuation marks.

* pdfmark.ms (Sections 2.5.5.4, 3.1.2.3): In constructs...
(.CWI ... \c, .CWB ... \c): ...adjust placement of "\c" mark, to
ensure that macro expansion results in its ultimate location at
the bitter end of the resultant output line fragment.