At 2022-02-07T22:08:34+0000, Humm wrote: > > Thus if you wanted to talk in a section 2 or 3 page about some C > > function name that has a man page to which you'd already referred, you > > would write, for example. > > > > The > > .MR gmtime\c > > () function converts the calendar time > > .I timep > > to broken-down time representation, > > Why not accept an empty second argument and puncuation? > > .MR gmtime "" ()
That looks too much like cleverness to me, but I suppose there is a certain amount of subjectivity to these things. I've done my level best in current groff documentation to get rid of the mystique around `\c`. > I don’t get why you wouldn’t just use -mdoc and leave -man as it is. As I said years ago on this list when I embarked on improving man(7) (mostly _not_ with new features, but with bug fixes), if mdoc(7) were going to eat man(7)'s lunch, it would have happened by now. It's had 30 years. I find mdoc's lexicon too large, its tendency to accumulate unbounded lists of internally maintained identifiers dispiriting, and its design feature whereby every macro carries two independent bits indicating its "parsed-ness" and "callability" impenetrable. Further, high-quality dead tree typography is an explicit anti-goal of its development. All mandoc(1) cares about is the terminal and static HTML. groff's overall mission does not permit the abandonment of typesetting. Nevertheless I won't deny its advantages where it has them. I've fixed bugs and brought a couple of new features to groff's mdoc(7) implementation too. > On most systems, there is -mdoc, and on the other ones, there likely > won’t be a -man implementing such new macros. This will be attributable to laziness or hostility, and not due to licensing concerns. Systems still assuming (or imposing) the six-argument limit on macro calls will be misrendering many pages _today_. (Hmm, I never did write down that this is a reason to quote multi-word (sub)section headings in arguments to `SH` and `SS`.) > Making cross references links is nice, but I could totally live with > not having that at all with -man. I don't expect many epiphanies--I simply want to deliver a better experience for those who are open to it. > (That doesn’t seem like a better imagination though.) Just last month I was spending some sweat generating a table of contents for the new 380+ compiled groff-man-pages.pdf document--I'd had my face in the 1970s Unix manuals recently-- when Deri James emailed me out of the blue with a shockingly short patch enabling PDF bookmarks in man(7). All of a sudden I didn't need to bother. In any reasonable PDF viewer a table of contents is available in tree form, resizable, depth-foldable, hyperlinked, and not a page number in sight. That's improvement. Granted, we pay a price with several more annoying diagnostics "can't output node in transparent throughput! OMG!". But at least I finally understand that hopelessly inscrutable message. Enough that I am prepared to try to kill Savannah #61407 in the formatter if necessary. How's that[1] coming, Deri? :D Regards, Branden [1] https://savannah.gnu.org/bugs/?61407
signature.asc
Description: PGP signature
