Add a New Comment (Rich Markup)
Comment Type & Canned Response: None No canned response available
( Jump to the original submission )
I'm punting MF and U to a subsequent release since there are thorny issues with PDF hotspots to work out for generalized hyperlink support.
Reconceptualizing this as bringing mdoc(7) into parity with man(7) as of groff 1.22.4, this is complete.
commit 78922cf9f39f6ebcd3a80aaab9c3a2931b8b0ad4 Author: G. Branden Robinson <g.branden.robinson@gmail.com> Date: Tue Dec 27 02:46:19 2022 -0600 [mdoc]: Support `HF` string. * tmac/doc.tmac (initialization): Add logic supporting `HF` string just as our man(7) implementation does. If the font name ends with `B` (as the default does), set `doc-remap-I-style-in-headings` register and extract font family, which can be empty (as is the default). * tmac/mdoc/doc-common (Sh, Ss): If `doc-remap-I-style-in-headings` register set, perform (and unwind) font remapping of italic to bold-italic face. * tmac/mdoc/doc-ditroff: * tmac/mdoc/doc-nroff: Define `doc-Sh-font` in terms of `HF`. * tmac/tests/doc_heading-font-remapping-works.sh: Test it. * tmac/tmac.am (tmac_TESTS): Run test. * tmac/groff_mdoc.7.man (Options): Document it. * NEWS: Update item. Fixes last part of <https://savannah.gnu.org/bugs/?63046>.
We're now down to HF, MF, and U.
commit d0ae281616da88d55134d877fdc3735df5cde8dc Author: G. Branden Robinson <g.branden.robinson@gmail.com> Date: Sun Dec 18 13:41:44 2022 -0600 [mdoc]: Support `FT` register. * tmac/doc.tmac (initialization): Add logic supporting `FT` register just as our man(7) implementation does. * tmac/mdoc/doc-common (doc-set-up-titles): Plant footer trap in validated user-requested location. * tmac/groff_mdoc.7.man (Options): Document it. * NEWS: Update item. Fixes part of <https://savannah.gnu.org/bugs/?63046>.
commit 88e89ebe9ce3931b49fb3cbd7fa20eacb03bf69f Author: G. Branden Robinson <g.branden.robinson@gmail.com> Date: Wed Dec 14 19:28:07 2022 -0600 [doc]: Support `X` register. * tmac/doc.tmac (initialization): Add logic supporting `X` register just as our man(7) implementation does. * tmac/groff_mdoc.7.man (Options): Document it. * NEWS: Update item. Fixes part of <https://savannah.gnu.org/bugs/?63046>.
commit 17477b26f5881117dd3f2c4df8db9420b2f3e9ae Author: G. Branden Robinson <g.branden.robinson@gmail.com> Date: Sun Dec 11 15:31:31 2022 -0600 [mdoc]: Support `P` register. * tmac/doc.tmac (initialization): Add logic supporting `P` register just as our man(7) implementation does. * tmac/groff_mdoc.7.man (Formatting with groff, troff, and nroff): Document it. * NEWS: Update item. Fixes part of <https://savannah.gnu.org/bugs/?63046>.
commit bb10a668e10e43f9ccb1727f9f82a1df1530e3b6 Author: G. Branden Robinson <g.branden.robinson@gmail.com> Date: Sat Oct 29 12:28:45 2022 -0500 [mdoc]: Support `SN` register. * tmac/doc.tmac: Recognize `SN` register if set on command line and use groff man(7)-compatible default if it is not. * tmac/mdoc/doc-common (Ss): Use this register instead of a literal. * tmac/groff_mdoc.7.man (Formatting with groff, troff, and nroff): Document it. * NEWS: Update item. Fixes part of <https://savannah.gnu.org/bugs/?62926>. commit 2134257877b8da28b6d225d99a1c6d81592d9043 Author: G. Branden Robinson <g.branden.robinson@gmail.com> Date: Sat Oct 29 12:09:26 2022 -0500 [mdoc]: Support `IN` register. * tmac/doc.tmac: Recognize `IN` register if set on command line and use groff man(7)-compatible defaults if it is not. * tmac/mdoc/doc-common (Sh): Use this register instead of `doc-paragraph-indentation`. * tmac/mdoc/doc-ditroff: * tmac/mdoc/doc-nroff: Stop setting pargraph indentation defaults here. * tmac/groff_mdoc.7.man (Formatting with groff, troff, and nroff): Document it. * NEWS: Update item. * tmac/tests/doc_Mt-works.sh: * tmac/tests/doc_indents-correctly.sh: Update test expectations. Fixes part of <https://savannah.gnu.org/bugs/?62926>.
There is significant overlap between this bug and bug #62926. They are distinguishable, but many of the command-line options supported by man(7) affect rendering.
Strictly, I reckon this ticket should get updated for any such options implemented in mdoc(7); those which affect the formatted appearance of man pages should also be logged in bug #62926, and those which aren't parameterized in options but affect rendering (like the typefaces used by the `Nm` and `Pa` macros, for instance), should be logged only in bug #62926.
It looks like only a handful of man(7) options remain to get mdoc(7) parity: HF, FT, P, X, and MF.
commit 952c2f75c25b70a6ebe4d457339b4fdcefd00f3a Author: G. Branden Robinson <g.branden.robinson@gmail.com> Date: Fri Sep 9 05:12:17 2022 -0500 [mdoc]: Support AD string; sets default adj mode. * tmac/mdoc/doc-common (Sh): Set adjustment mode to user-specified default, not troff's default (and not only in troff mode). * tmac/mdoc/doc-ditroff: * tmac/mdoc/doc-nroff: Process `AD` string setting from command line as man(7) does. * tmac/groff_mdoc.7.man (Formatting with groff, troff, and nroff): Document it. * NEWS: Add and update items. Fixes part of <https://savannah.gnu.org/bugs/?63046>.
commit 30115f3ba72801badda08cdbc0210cb0014ddc1e Author: G. Branden Robinson <g.branden.robinson@gmail.com> Date: Wed Sep 7 21:53:34 2022 -0500 [mdoc]: Support `C` register as man(7) does. * tmac/mdoc/doc-common (Dd): Reset page number to 1 upon new document only if not consecutively numbering. * tmac/mdoc/doc-ditroff: * tmac/mdoc/doc-nroff: Process `C` register setting from command line as man(7) does. * tmac/groff_mdoc.7.man (Formatting with groff, troff, and nroff): Document it. * NEWS: Expand existing item. Fixes part of <https://savannah.gnu.org/bugs/?63046>.
Over in bug #62926, Ingo had the following exchange.
[me:]
> I would also add that your use of "API" here is open to equivocation. > > There are two materially relevant interfaces here. > > 1. That between the man page author and the macro package. > 2. That between the man page reader and the macro package. > > Man page authors are explicitly discouraged from using `MF`, as they are all other strings and registers.
[quotation of groff_man(7) omitted; the key point is that it says "*man pages should never use them* (emphasis added)]
> There is therefore no reason to catastrophize the addition of `MF` to a set that already includes (strings) `AD` and `HF` and registers `cR`, `C`, `CS`, `CT`, `D`, `FT`, `HY`, `IN`, `LL`, `LT`, `P`, `S`, `SN`, `U`, and `X`. > > groff mdoc does not yet support all of these, but I would like it if it did. These are all rendering options, and if an implementation wants to remove these degrees of freedom, it can do so without impacting how man pages using either package are written.
comment #6:
> It seems CS, CT, D, HY, LL, LT, and S are GNU only, but cR already appeared in 4.4BSD. > So indeed, the horse is barely in sight of the barn any longer, let alone inside of it. No, i wasn't aware of that. > > In this situation, while MF does add even more noise to the manual page (noise which authors don't need and users will not usually even look at), it does not seem to make the situation that much worse than it already is, it merely continues one more step down the declining slope, as long as you don't break .Nm.
Well, I got stuck in the tar pit that was groff_mdoc(7) and have starting revising it, heavily.
I have found that I cannot stand the overuse of Courier and bold, but that these mostly stem from use of two macros: `Nm` and `Pa`. So I plan to add `NF` and `PF` strings to manage how they render their arguments. man(7) has no astrings) `AD` and `HF` and registers `cR`, `C`, `CS`, `CT`, `D`, `FT`, `HY`, `IN`, `LL`, `LT`, `P`, `S`, `SN`, `U`, and `X`.nalogues for these.
> P.S. > My concept of API is quite simple: it's the syntax and semantics described in the manual page - because that's what users of the language need to review.
I must apparently take greater pains to clarify. I distinguish two communities of users: those who render man pages and those who write them.
Those who write man pages need not know anything about, and should not meddle with, strings `AD`, `HF`, and `MF`, nor registers `cR`, `C`, `CS`, `CT`, `D`, `FT`, `HY`, `IN`, `LL`, `LT`, `P`, `S`, `SN`, `U`, and `X`.
Those who read (or at least render) man pages on the other hand, could find them useful. I do, at any rate.
My understanding is that you, as mandoc maintainer, look darkly upon user control of rendering. Until recently, I guess (I've lost track of the mail where you said this changed), even the line length was not subject to user control.
That is manifestly not the groff approach. Maybe it's a GNU thing: knobs for everything!
Anyway, this ticket is to track an ongoing project to align groff _man_ and mdoc in this respect.
(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)
Attach Files: Comment:
No files currently attached
Depends on the following items: None found
Items that depend on this one: None found
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.
Please enter the title of George Orwell's famous dystopian book (it's a date):
Follow 3 latest changes.
Copyright © 2023 Free Software Foundation, Inc. Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved. The Levitating, Meditating, Flute-playing Gnu logo is a GNU GPL'ed image provided by the Nevrax Design Team. Source Code
Powered by Savane 3.9