search

PCRE2Project / pcre2

PCRE2 development is now based here.
Other
921 stars 194 forks source link

Add a TH (title) macro to pcre2demo.3 #292

Closed MatthewVernon closed 1 year ago

MatthewVernon commented 1 year ago

per groff_man(7):

A man page should contain exactly one .TH call at or near the beginning of the file, prior to any other macro calls.

This manual page didn't (and as a result man --warnings emits a warning about the first .SH macro).

Make PrepareRelease add such a header to pcre2demo.3 along with a comment noting that pcre2demo.3 is automatically generated (to avoid any further confusion on that front).

This necessitates teaching 132html to know about that warning (which we don't want to have appearing in the HTML output).

Also, update the EX and EE macros to reflect the current content of /usr/share/groff/1.22.4/tmac/an-ext.tmac.

PhilipHazel commented 1 year ago

Thanks for looking at this. However, pcre2demo.3 is not manually maintained; it is created by the script called PrepareRelease, to ensure that it always contains the current pcre2demo.c code. If you don't want to make another pull request, I can copy your patch to PrepareRelease. It's so long ago that that script was created that I cannot remember details about the EX and EE macros. I'm happy to update them if it seems reasonable.

MatthewVernon commented 1 year ago

Oh, since it was committed in the tree I hadn't considered it might be essentially a build artifact. I'll make a patch to PrepareRelease (and presumably also pcre2demo.3 to reflect the new output?), and maybe also stick a comment at the top to say where it comes from :)

PhilipHazel commented 1 year ago

Just patch PrepareRelease; running "./PrepareRelease doc" should make a new pcre2demo.3. I guess it's more of a packaging artifact than a build one. It's in the repo so that those who clone it get the full documentation - same goes for the HTML docs, which are also made by PrepareRelease. And yes, you are right, there should be a comment!

MatthewVernon commented 1 year ago

I've now done this (see revised commit & comment).

PhilipHazel commented 1 year ago

I've merged, but there is a problem. The new man page shows everything with an indent, whereas the old one does not. This means that many lines overflow in an 80-character window, making it all hard to read. I will investigate, but I think it might be a consequence of adding the TH macro.

MatthewVernon commented 1 year ago

You can put that back by adding

.RS -7

before the .EX; this effectively undoes the default 7 or 7.2n indentation that man pages have. I could add that as a new PR if you like?

PhilipHazel commented 1 year ago

No need. I will do it.

PhilipHazel commented 1 year ago

Now done and committed.