Re: [groff] Release Candidate 1.22.4.rc3

[G. Branden Robinson]

At 2018-11-28T23:09:34+0100, Bertrand Garrigues wrote:
> Hi Branden,
> 
> We have both made some commits recently and I think we are not far from
> making the final release,

I was hoping you'd say something like that.  :)

> On Sun, Nov 04 2018 at 01:18:32 AM, "G. Branden Robinson" <address@hidden> 
> wrote:
> > I'd like to propose resolving the following 4 issues before going final.
> >
> > 1. Resolve this compiler warning:
> >
> > ../src/roff/troff/input.cpp: In function ‘void macro_source()’:
> [...]
> > 2. Revert the 3 changes Ingo made to hdtbl in August;
> [...]
> > 3. Resolve Savannah #40967.
> [...]
> These 3 issues were solved recently.

Yup.  I've kept meaning to go back over the last month's worth of list
traffic and make some comments, and this was one of them.

> > 4. Apply the final pass of my groff_man.7 overhaul.  IIRC I sent this
> > privately to you and Ingo a few months ago; I have tweaked it very
> > little sense, so I reckon I'm happy with it.  All it needs now is a
> > commit message and ChangeLog entry.
> 
> That was on whether 'preconv --version' should appear on a separate
> line (below 'preconv -v') or not;

You mean in the man page synopsis?  The current version of the page
looks fine in that respect.

> if I'm not mistaken all the man pages are aligned now?

The _synopses_ are, yes, to the best of my knowledge.

With all of the advice in my groff_man.7 overhaul?  Heck no.  But that
was never a 1.22.4 release objective for me.  A unified editorial style,
let alone a single authorial voice should not be a release goal for
1.22.4.  (For things in contrib/, I'm not sure an "authorial voice"
matching the stuff outside of it is even desirable.)

There are three barriers to editorial style consistency in our pages:

A. There is still a huge volume of editing work to be done on nearly all
the pages.  The ones primarily authored by Bernd Warken need a great
deal of attention.

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.

C. As an educational exercise and proof of concept I've been working on
a semantic macro extension to man(7) for us.  It's nowhere near ready
for review and commentary, and may not be for quite a while; my work
visa in another country has just been approved and it looks like I'll be
relocating internationally in the near future.  Fortunately, my new
employers are FLOSS-friendly.

> Do you have more things you would like to commit?

Nothing that can't wait for 1.22.5.  I'll append my current task to the
end of the message.  It is _not_ worth holding up the release for, IMO.

> If no I would make a rc4 for final sanity checks (only allowing
> important bug fixes) before releasing the official 1.22.4.

Sounds good to me!  Even if we had a perfect accord on man page font
style issues, it's going to take weeks more of work to get everything
aligned.

I do wish I had statistics on which groff man pages are the most viewed.
groff(1) and troff(1), probably.  But without that data _and_ some lead
time when I shouldn't be packing up my house, it's not worth any delay.
Like Colin, I'd very much like to see a new groff in the next Debian
stable release.

doc/webpage.ms will have to wait for now, I think.  Sadly I think it
likely that too few people even look at it for it to cause significant
confusion.

The only other thing I would even think of proposing is taking the man
macro package documentation _out_ of the Texinfo manual, since
groff_man.7.man is where that material is actively maintained.  I
already have a git stash of that chance so it wouldn't be hard to do
(all I'd leave would be the man.local example of DEC Ultrix man
extensions).  There are several instances of claims that the Texinfo
manual is complete and authoritative when it is neither.  mdoc is not
documented within it, groff(7) claims that groff_diff(7) is the
authoritative document of GNU extensions to classical troff, and so
forth.

There's nothing I'm itching to shove into the 1.22.4 final release.  All
the stuff I've got pending is either still in progress or I'll be just
as happy seeing appear in 1.22.5.

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.
* 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.
* A free implementation of the mv macros.  From the documentation I have
  (Gehani's book, I think) it seems like a pretty straightforward
  exercise (famous last words).  The main problem is that I can't find
  any extant documents written in it to test it with and see if the
  rendering is faithful.

Thanks for your work!

Regards,
Branden

signature.asc
Description: PGP signature