Hi Brandon, G. Branden Robinson wrote on Wed, Nov 28, 2018 at 06:44:32PM -0500: > At 2018-11-28T23:09:34+0100, Bertrand Garrigues wrote: > > On Sun, Nov 04 2018 at 01:18:32 AM, "G. Branden Robinson" > > <g.branden.robin...@gmail.com> wrote:
> B. A few bits of my advice in groff_man.7 about which things get marked > up in bold vs. italics are controversial within our team, and will be at > least as much in general. We're at a bit of an impasse on that, which > is blocking some inconsistencies in our corpus of 61 page sources from > being resolved. We should somehow resolve that, though i'm not sure how if neither the argument that long-standing BSD practice and Linux man pages project recommendations agree on this nor that having command names bold in the SYNOPSIS and italic in the DESCRIPTION imply an inconsistency within any given page seem strong enough for you. >> If no I would make a rc4 for final sanity checks (only allowing >> important bug fixes) before releasing the official 1.22.4. Please do, i shall definitely test without too much delay. I consider testing again on different platforms important because a considerable number of dangerous commits to the build system were made lately that could impact portability if they happen to contain any subtle oversights. > I do wish I had statistics on which groff man pages are the most viewed. If you have good reasons why you need to know that, consider asking Michael Stapelberg nicely, mentioning that you are the de-facto groff documentation maintainer and we value his work on manpages.debian.org, if that's true from your perspective. Lastname at debian dot org it is. > I'm already thinking of release goals for 1.23. My current fantasies > are: > * Moving strip.sed into groff_tmac(5) as an example, and not actually > using it in our build anymore. We can warn of its imminent departure > in 1.22.5. I heartily support getting rid of strip.sed. I'm not even sure it should be shown around as an example: trying to parse and manipulate some language with a parser that doesn't really understand the language is asking for trouble, usually, so we should hardly give people the idea. Then again, i won't make a fuss about adding an example somewhere... :) > * My semantic macro package extending groff_man(7), if I can get it > where I'm happy with it and folks on the list don't bleed from the > eyes about it. That would be a HUGE step backwards, making the groff manual pages even less portable (they are already among the 20-30 least portable manual page sets in those about ten thousand free software projects that i looked at, and the amount of portability problems in groff manual pages is vastly larger than in most other of those 20-30 projects). You surely want to make that worse, right? The dusty man-ext macros are already a trainwreck: they have been around for more than 12 years now and still aren't universally supported, and the bad practice of copying macro implementations into each and every bloody manual page only makes matters worse, causing bloat, lingering outdated or buggily hand-edited versions, and other potential compat issues. For example, what is mandoc(1) supposed to do? Use the slow, purely presentational, and potentially buggy and outdated local macro implementations, just in case somebody edited them in a way that matters for the page at hand, or use the fast, partially structural, actively maintained built-in C implementations? Or do you want mandoc(1) to inspect the local macro implementations and try to guess whether they are better or worse than the normal behaviour of the macros? That said, i'm looking forward to the release and very much appreciating the work both of you are doing. Yours, Ingo
