linux-man.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
* Re: proctological linter warnings on groff's man pages (was: mdoc(7): CHECKSTYLE)
       [not found]         ` <20230426090658.oboomd2tmmoyba6x@illithid>
@ 2023-04-26  9:44           ` Alejandro Colomar
  2023-04-26 21:58             ` Alejandro Colomar
  0 siblings, 1 reply; 2+ messages in thread
From: Alejandro Colomar @ 2023-04-26  9:44 UTC (permalink / raw)
  To: G. Branden Robinson; +Cc: groff, linux-man, Jakub Wilk, Marcos Fouces


[-- Attachment #1.1: Type: text/plain, Size: 9583 bytes --]

Hi Branden,

On 4/26/23 11:06, G. Branden Robinson wrote:
> Hi Alex,
> 
> At 2023-04-24T19:11:58+0200, Alex Colomar wrote:
>>> At 2023-04-23T16:17:06+0200, Alejandro Colomar wrote:
>>>> I got some errors from mdoc(7), which were probably due to the
>>>> LANDMINE
>>>> <https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/etc/groff/tmac/checkstyle.tmac>.
>>>> Why is that file problematic with mdoc(7)?
> [...]
>> <https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/etc/groff/tmac/checkstyle.tmac?id=55bdf08d6d7f56280fe472902331c735bb7492f9>
> 
> It's not obvious to me why that macro file would cause any problems.

You could try if you're curious; since I already removed groff's
pages from my build system, I'd have to repeat the setup.  If you
want me to do it, I can.  Otherwise, I already removed that file
from the Linux man-pages, so we can just ignore this, if you're not
curious enough.

> 
>> $ make check -k
>> troff: man1/gpinyin.1:316: warning: macro 'AD' not defined
>> troff: man5/groff_font.5:813: warning: macro 'AD' not defined
> 
> These are expected if you format groff 1.23.0 man pages with groff
> 1.22.4 (or older).  I had to resort to some unpleasantness in those 2
> pages.

But I didn't.  I have groff 1.23.0-some-commit-around-rc3 in all of
my machines.  Maybe I installed it incorrectly?


I don't remember if I run this from my desktop or laptop.  Here's
what my desktop reports:

$ groff --version
GNU groff version 1.23.0.rc3.44-a241d
Copyright (C) 2022 Free Software Foundation, Inc.
GNU groff comes with ABSOLUTELY NO WARRANTY.
You may redistribute copies of groff and its subprograms
under the terms of the GNU General Public License.
For more information about these matters, see the file
named COPYING.

called subprograms:

GNU grops (groff) version 1.23.0.rc3.44-a241d
GNU troff (groff) version 1.23.0.rc3.44-a241d


Maybe I did something wrong and run 1.22.4 somehow.  Do you want me
to try again with 1.23.0?

> 
>> troff: man7/groff_char.7:1582: warning: can't find special character 'bs'
>> troff: man7/groff_char.7:1808: warning: can't find special character 'radicalex'
>> troff: man7/groff_char.7:1810: warning: can't find special character 'sqrtex'
> 
> These are documented in the groff PROBLEMS file.  They are harmless.
> 
> https://git.savannah.gnu.org/cgit/groff.git/tree/PROBLEMS?id=dbd2b2007280f5125227307ff6962c0948366aef#n985
> 
> The solution is to design and ship a small font to solve some glyph
> coverage problems.  I think we talked about that on this list last
> summer.

But that seems to be about PS, isn't it?  My I run was with -Tutf8.

> 
>> mdoc warning: .St: Unknown standard abbreviation '-susv1' (#2540)
>>               Please refer to the groff_mdoc(7) manpage for a
>>               list of available standard abbreviations.
>> mdoc warning: .St: Unknown standard abbreviation '-susv4' (#2546)
>>               Please refer to the groff_mdoc(7) manpage for a
>>               list of available standard abbreviations.
> 
> https://savannah.gnu.org/bugs/?55789

Hmm, this is fixed, so it seems I was using 1.22.4 accidentally.

> 
>> $ make lint-man-tbl -k
>> LINT (tbl comment)	.tmp/man/man1/chem.1.lint-man.tbl.touch
>> man1/chem.1:1: missing '\" t' comment:
>> .TH \%chem 1 "24 April 2023" "groff 1.23.0.rc4.19-96b92"
>> make: *** [share/mk/lint/man/man.mk:42:
>> .tmp/man/man1/chem.1.lint-man.tbl.touch] Error 1
>> LINT (tbl comment)	.tmp/man/man1/groff.1.lint-man.tbl.touch
>> man1/groff.1:1: missing '\" t' comment:
>> .TH groff 1 "24 April 2023" "groff 1.23.0.rc4.19-96b92"
>> make: *** [share/mk/lint/man/man.mk:42:
>> .tmp/man/man1/groff.1.lint-man.tbl.touch] Error 1
>> LINT (tbl comment)	.tmp/man/man7/groff_www.7.lint-man.tbl.touch
>> man7/groff_www.7:1: missing '\" t' comment:
>> .TH groff_www 7 "24 April 2023" "groff 1.23.0.rc4.19-96b92"
>> make: *** [share/mk/lint/man/man.mk:42:
>> .tmp/man/man7/groff_www.7.lint-man.tbl.touch] Error 1
>> make: Target 'lint-man-tbl' not remade because of errors.
> 
> I thought Colin Watson withdrew interpretation of this type of comment
> from man-db man, and mandoc(1) doesn't support it either.
> 
> If I'm right, that would leave it without any consumers in Free Software
> man pagers (troffs themselves, AFAIK, have never done anything with it).

I received a report that lintian still uses it.  Maybe Jakub or Marcos
can confirm.

> 
>> And here go the ones from mandoc(1), which is more picky:
>>
>> $ make lint-man-mandoc -k |& grep -v -e 'WARNINGS: invalid escape sequence'
>> -e 'UNSUPP: unsupported roff request' -e 'WARNING: invalid escape sequence'
>> LINT (mandoc)	.tmp/man/man1/addftinfo.1.lint-man.mandoc.touch
>> mandoc: man1/addftinfo.1:1:17: WARNING: cannot parse date, using it
>> verbatim: TH 24 April 2023
> 
> I reject mandoc's attempt at date format enforcement.  While,
> personally, I prefer ISO 8601 format, our man pages' dates come from our
> mdate.pl script.  That's the place to change it, if anyone means to.

I also prefer ISO 8601.  I can prepare a patch for that.

[...]


>> mandoc: man5/groff_out.5:1921:2: WARNING: line scope broken: UR breaks TP
> 
> We have trouble with putting URLs in paragraph tags.
> 
> https://savannah.gnu.org/bugs/?61434

Yeah, that makes sense.  When I saw UR and TP in the same line, I guessed
it wouldn't be an easy thing.  :)

> 
> But even if we fix it, mandoc(1) could well still complain.

[...]

> 
>> mandoc: man5/groff_tmac.5:289:2: WARNING: skipping paragraph macro: PP after
>> SS
> 
> Another Berndism, or something I introduced while reorganizing sections.
> I _did_ revise this part of this page, and I managed to miss this bit of
> untidiness.  Fixed in my working copy, will push to master.

Nice.

> 
>> make: *** [share/mk/lint/man/man.mk:28:
>> .tmp/man/man5/groff_tmac.5.lint-man.mandoc.touch] Error 1
>> LINT (mandoc)	.tmp/man/man7/groff.7.lint-man.mandoc.touch
>> mandoc: man7/groff.7:5221:30: STYLE: whitespace at end of input line
> 
> Can't reproduce.  I find no trailing white space in this file.

I'll try again with 1.23.0, and will confirm if I still see it.

> 
>> mandoc: man7/groff.7:2:13: WARNING: cannot parse date, using it verbatim: TH
>> 24 April 2023
>> mandoc: man7/groff.7:778:2: WARNING: skipping paragraph macro: PP empty
>> mandoc: man7/groff.7:828:2: WARNING: skipping paragraph macro: PP empty
>> mandoc: man7/groff.7:2320:2: WARNING: skipping paragraph macro: PP empty
>> mandoc: man7/groff.7:4397:2: WARNING: skipping paragraph macro: PP empty
>> mandoc: man7/groff.7:5496:2: WARNING: skipping paragraph macro: PP empty
>> mandoc: man7/groff.7:5993:2: WARNING: skipping paragraph macro: PP empty
> 
> Arguable, maybe.  The page uses some private macros, LS and LE, to
> temporary reduce the paragraph distance to zero.  Those were my
> invention, and I think they arose in discussion with you.  Have I left
> them off of my list of proposed man(7) extensions?  Maybe I have.

Yeah, I remember them (I named them babies :).  Let's keep them sleeping
until the final release.

> 
> I don't feel guilty about piloting these page-private macros because the
> document is already thick with them.  (It was written by a *roff expert
> long before the Robinson/Schwarze man(7) portability summit of 2017/8.)
> It will take a lot of effort to dig them all out.  Someday...
> 
>> mandoc: man7/groff_diff.7:3280:2: WARNING: skipping paragraph macro: IP
>> empty
> 
> Looks like a false positive.  A lot of man(7) macros are being thrown
> around to get a certain desired amount of indentation, but I don't see
> any superfluous macro calls.

Might be a glitch of using 1.22.4.  I'll investigate more with 1.23.0.
Maybe it's just that a lot of macros are confusing each other, as you say.

[...]

> 
> Good grief, I'm only 34% through this mess.  I'm stopping here for now.
> 
> I'm not sure mandoc(1)'s linter is useful as a land mine trigger.
> 

It found some bugs in my pages.  I count 10 commits where I logged that
they were triggered by mandoc(1).  Of course, I had to disable many
warnings in which I wasn't interested, but it's useful if you configure
it to your preferences (Ingo didn't want to allow such configuration,
but grep(1) is a nice way to workaround it).  Here's how I have it:

$(_LINT_man_mandoc): $(_MANDIR)/%.lint-man.mandoc.touch: $(MANDIR)/% | $$(@D)/
	$(info LINT (mandoc)	$@)
	! ($(MANDOC) -man $(MANDOCFLAGS) $< 2>&1 \
	   | $(GREP) -v 'STYLE: lower case character in document title:' \
	   | $(GREP) -v 'UNSUPP: ignoring macro in table:' \
	   | $(GREP) -v 'WARNING: cannot parse date, using it verbatim: TH (date)' \
	   | $(GREP) -v 'WARNING: empty block: UR' \
	   | $(GREP) -v 'WARNING: missing date, using "": TH' \
	   | $(GREP) -v 'WARNING: undefined escape, printing literally: \\\\' \
	   ||:; \
	) \
	| $(GREP) '.' >&2
	touch $@

$(_LINT_mdoc_mandoc): $(_MANDIR)/%.lint-mdoc.mandoc.touch: $(MANDIR)/% | $$(@D)/
	$(info LINT (mandoc)	$@)
	! ($(MANDOC) -mdoc $(MANDOCFLAGS) $< 2>&1 \
	   | $(GREP) -v 'STYLE: operating system explicitly specified: Os ' \
	   | $(GREP) -v 'WARNING: cross reference to self: Xr ' \
	   ||:; \
	) \
	| $(GREP) '.' >&2
	touch $@

(For the mdoc(7) one, I'll still probably add many more exceptions.)


Cheers,
Alex

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

^ permalink raw reply	[flat|nested] 2+ messages in thread

* Re: proctological linter warnings on groff's man pages (was: mdoc(7): CHECKSTYLE)
  2023-04-26  9:44           ` proctological linter warnings on groff's man pages (was: mdoc(7): CHECKSTYLE) Alejandro Colomar
@ 2023-04-26 21:58             ` Alejandro Colomar
  0 siblings, 0 replies; 2+ messages in thread
From: Alejandro Colomar @ 2023-04-26 21:58 UTC (permalink / raw)
  To: G. Branden Robinson; +Cc: groff, linux-man, Jakub Wilk, Marcos Fouces


[-- Attachment #1.1: Type: text/plain, Size: 1273 bytes --]



On 4/26/23 11:44, Alejandro Colomar wrote:
> Hi Branden,
> 
> On 4/26/23 11:06, G. Branden Robinson wrote:
>> Hi Alex,
>>
>> At 2023-04-24T19:11:58+0200, Alex Colomar wrote:
>>>> At 2023-04-23T16:17:06+0200, Alejandro Colomar wrote:
>>>>> I got some errors from mdoc(7), which were probably due to the
>>>>> LANDMINE
>>>>> <https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/etc/groff/tmac/checkstyle.tmac>.
>>>>> Why is that file problematic with mdoc(7)?
>> [...]
>>> <https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/etc/groff/tmac/checkstyle.tmac?id=55bdf08d6d7f56280fe472902331c735bb7492f9>
>>
>> It's not obvious to me why that macro file would cause any problems.
> 
> You could try if you're curious; since I already removed groff's
> pages from my build system, I'd have to repeat the setup.  If you
> want me to do it, I can.  Otherwise, I already removed that file
> from the Linux man-pages, so we can just ignore this, if you're not
> curious enough.
> 

I can't reproduce it.  It might be due to running 1.22.4 (but that
being from the 23rd or April, something doesn't really fit in my head).

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

^ permalink raw reply	[flat|nested] 2+ messages in thread

end of thread, other threads:[~2023-04-26 21:58 UTC | newest]

Thread overview: 2+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
     [not found] <d9b111c2-1ebe-e697-34c5-a7f01445568b@gmail.com>
     [not found] ` <20230422200547.jlc2cfvbyatzlpjv@illithid>
     [not found]   ` <49b9b4b1-5500-e2b8-b20c-dfafa46a1e3f@gmail.com>
     [not found]     ` <20230424053116.asfy4hz3da7hs23k@illithid>
     [not found]       ` <cb3f3ddb-2ed5-192f-b373-7b1378cc66fa@gmail.com>
     [not found]         ` <20230426090658.oboomd2tmmoyba6x@illithid>
2023-04-26  9:44           ` proctological linter warnings on groff's man pages (was: mdoc(7): CHECKSTYLE) Alejandro Colomar
2023-04-26 21:58             ` Alejandro Colomar

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).