Hi Branden, G. Branden Robinson wrote on Fri, Jun 18, 2021 at 01:48:15AM +1000:
> Back in October, a release looked imminent, but it doesn't seem so now. > Over 700 commits have been pushed since rc1, so an rc2 seems called for > on quantitative grounds alone. You do have a point here, i think. In general, it's good to do disruptive changes shortly after a release rather than shortly before. Then again, these changes are not *that* disruptive, and delaying agreed changes for very long times hinders development and frustrates developers. The latter is particulary bad when short on developers. > I'm therefore seeking feedback on three > _structural_ changes to the groff repo and/or the source distribution. > > 1. "Skip the stripper". Mooted several times on this list in the past, > this proposal to stop shipping some macro packages (hdtbl, mdoc, and > "me") in a condensed, hard-to-read form akin to JavaScript > minification already enjoys a consensus, but was shelved on perceived > scheduling grounds. > <https://savannah.gnu.org/bugs/?55091> Yes! Do it, pretty please. > 2. Move grog from src/roff to src/utils. I mooted this on 5 June. I > already drastically altered grog's internal structure, making it a > stand-alone script.[1] > <https://lists.gnu.org/archive/html/groff/2021-06/msg00003.html> > https://savannah.gnu.org/bugs/?60788 No strong opinion on that one. I guess it makes sense that you did that. > 3. Rename "an-old.tmac" to simply "an.tmac". I'm not happy with the > whiff of deprecation that the current nomenclature carries. That whiff of deprecation makes a lot of sense to me, though ;-). Then again, naming of macro sets is not a good place to deprecate things our documentation does not deprecate. Deprecation needs consisistency and should not be done in a half-hearted way. > I've > done a fair amount of work on the macro package source, fixing bugs, > rearranging it, adding comments, and making it more accessible (or > trying to). I first mooted a rename in broad terms last October, and > reiterated it in April. No one screamed, so I propose now to be even > bolder, permitting the "an" package to reclaim its proper name among > the macro package file names. For what it's worth, that's already what mandoc(1) does: 1. With -man, process man(7) only. 2. Woth -mdoc, process mdoc(7) only. 3. With -mandoc, auto-detect, or fall back to -man if neither .Dd nor .TH are found. Admittedly, a slight difference remains: with mandoc(1), -mandoc is the default, while with groff(1), it isn't and should not and cannot be. > This would be a NEWS-worthy item because the "-man" argument to groff > (or nroff, or troff) would no longer load the andoc wrapper. Yes. > Is this a problem? I don't think so. People running groff themselves or from their own scripts can trivially adapt, in a way that is even backward-compatible with old groff versions. Users merely running man(1) likely won't even notice if package maintainers of man(1) implementations on their operating system do their job and take care of using -mandoc rather than -man, which is a good idea anyway, and easy to do before updating groff in their package repository. > You might think so. But I think I have discovered that > it is not. Most people don't use groff(1) for batch-rendering of > multiple man pages from one invocation at the command line. If they > want to render multiple man pages, they use man(1), which in turn > appears to execute a separate groff process for every page. (And > most of the time, people don't ask man(1) for multiple pages anyway.) [...] These arguments all sound very reasonable. > The asymmetry of doc.tmac(-u) not also causing a redirection through > andoc.tmac is bothersome, though defensible on terms that may chagrin > mdoc(7) advocates--there are many more man(7) pages in the world, so > anyone who asks for "-mdoc" is likely to know what they are doing. I fully agree with that. I don't think that -mdoc should try to handle man(7) input; that's what -mandoc is for. It is always good to have a way to explicitely state which parsing you want and avoid autodetection altogether. I think that's true for man(7), too, by the way. [...] > So I propose to advise users (and authors of man(1) librarians) in > the NEWS file to invoke groff with the "-mandoc" argument. Absolutely. > This was already a good idea, but not truly necessary. Indeed. > Now it will be. That's totally fine with me. > The arrangement of having most of the real logic > stuffed into a "subs.pl" file would be admirable if one were to > actually make a working library out of them, but that hasn't been > done and in the meantime, the arrangement makes the programs hard to > test, with a distressing impact on implementation quality. Yes. Besides, file names should be descriptive, and files should be organized according the to function purpose or function groups. Having a *single* file for subroutines is no better than having them in the main file, and the name "subs.pl" is atrocious. It's half-hearted, pointless abstraction for abstraction's sake without even trying to think about design. Do not abstract, nor aim for re-usability, unless there is a reason to. You will just make the code more complicated and hinder maintenance. Not everything needs to be a library. There are few ideas in code development as thoroughly overvalued as reusability. Yours, Ingo
