bugGNU roff - Bugs: bug #62042, [man] want designed, documented...

 
 

bug #62042: [man] want designed, documented CHECKSTYLE feature

Submitter:  Alejandro Colomar <alx>
Submitted:  Sat 12 Feb 2022 06:45:41 PM UTC
   
 
Category:  Macro man Severity:  1 - Wish
Item Group:  Documentation Status:  None
Privacy:  Public Assigned to:  gbranden
Open/Closed:  Open Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Jump to the original submission

Fri 20 May 2022 11:14:35 AM UTC, comment #12: 

Thanks for following up, Alex.  It was my fault.  I misspelled the name of the leading space(s) macro I offered you in comment #8.

Also, in case you don't want to throw away the output with `-z`, it is helpful to append to the existing end-of-input macro used by the man(7) package instead of replacing it.  I overlooked this in my original proposed solution.

Here's a transcript of things working, I think.


$ cat EXPERIMENTS/landmine.man
.TH landmine 1 2022-05-20 "groff test suite"
.SH Name
landmine \- blow up
.SH Description
 Here's a paragraph with a leading space.

And this is a new paragraph,
because that was a blank line.
$ cat EXPERIMENTS/deadly.tmac
$ cat EXPERIMENTS/deadly.tmac
.am an-style-warn
. ds LANDMINE\"
..
.de end-of-input-macro
. if d LANDMINE .ab found style problems; aborting
..
.am an-end
.  end-of-input-macro
..
$ cat EXPERIMENTS/checkstyle-alx.tmac
.de1 an-blank-line-trap
. sp
..
.
.de1 an-leading-space-trap
. nop \h'\\n[lss]u'\c
..
$ ./build/test-groff -T utf8 -z -man -rCHECKSTYLE=3 -M EXPERIMENTS -m checkstyle-alx -m deadly EXPERIMENTS/landmine.man
$ ./build/test-groff -T utf8 -man -rCHECKSTYLE=3 -M EXPERIMENTS -m checkstyle-alx -m deadly EXPERIMENTS/landmine.man
landmine(1)                 General Commands Manual                landmine(1)

Name
       landmine - blow up

Description
        Here’s a paragraph with a leading space.

       And this is a new paragraph, because that was a blank line.

groff test suite                  2022‐05‐20                       landmine(1)


comment #11:

> Hi Branden,
>
> comment #10:
> > I am confused.  This appears to be working exactly as I intended.  Did I misunderstand what you wanted?
>
> Yup, check <checkstyle.tmac>; it's supposed to cancel the effects of <deadly.tmac> for leading spaces and blank lines, isn't it?
>
> But I still die when I step on the landmine :(

G. Branden Robinson <gbranden>
Group administrator
Fri 20 May 2022 10:45:52 AM UTC, comment #11: 

Hi Branden,

comment #10:

> I am confused.  This appears to be working exactly as I intended.  Did I misunderstand what you wanted?


Yup, check <checkstyle.tmac>; it's supposed to cancel the effects of <deadly.tmac> for leading spaces and blank lines, isn't it?

But I still die when I step on the landmine :(

Alejandro Colomar <alx>
Fri 20 May 2022 03:26:18 AM UTC, comment #10: 

Hi Alex,

I apologize for get distracted away from this ticket.

comment #9:

> Your snippet is not working for me:

[...]

> $ make lint-groff V=1
> GROFF CHECKSTYLE tmp/share/man/man7/chessutils.7.cks.touch
> groff -z -man -rCHECKSTYLE=3 -M ./etc/groff/tmac -m checkstyle -m deadly share/man/man7/chessutils.7
> an.tmac:share/man/man7/chessutils.7:9: style: 1 leading space(s) on input line
> found style problems; aborting
> make: * [Makefile:253: tmp/share/man/man7/chessutils.7.cks.touch] Error 1


I am confused.  This appears to be working exactly as I intended.  Did I misunderstand what you wanted?

G. Branden Robinson <gbranden>
Group administrator
Wed 23 Feb 2022 04:44:27 PM UTC, comment #9: 

Your snippet is not working for me:


$ ll etc/groff/tmac/
total 0
lrwxrwxrwx 1 user user 35 Feb 23 17:30 checkstyle.tmac -> ../../../share/tmac/checkstyle.tmac
lrwxrwxrwx 1 user user 31 Feb  4 14:45 deadly.tmac -> ../../../share/tmac/deadly.tmac



$ cat etc/groff/tmac/checkstyle.tmac
.de an-blank-line-trap
. sp
..
.
.de an-leading-spaces-trap
. nop \h'\\n[lss]u'\c
..



$ cat etc/groff/tmac/deadly.tmac
.am an-style-warn
. ds LANDMINE\"
..
.de end-of-input-macro
. if d LANDMINE .ab found style problems; aborting
..
.em end-of-input-macro



$ make lint-groff V=1
GROFF CHECKSTYLE tmp/share/man/man7/chessutils.7.cks.touch
groff -z -man -rCHECKSTYLE=3 -M ./etc/groff/tmac -m checkstyle -m deadly share/man/man7/chessutils.7
an.tmac:share/man/man7/chessutils.7:9: style: 1 leading space(s) on input line
found style problems; aborting
make: * [Makefile:253: tmp/share/man/man7/chessutils.7.cks.touch] Error 1

Alejandro Colomar <alx>
Wed 23 Feb 2022 01:44:35 PM UTC, comment #8: 

Hi, Alex!

comment #7:

> But for now, I guessed it's possible to silence a specific warning, by redefining some macro.  Isn't it possible?


Yes, but my advice in comment #4 to this bug was wrong because I forgot that `TH` re-establishes the blank line and leading space traps (it has to, because in batch processing man pages we might have wandered off to mdoc(7) land and back).

Try adding this to /etc/groff/man.local.


.de an-blank-line-trap
.  sp
..
.
.de an-leading-spaces-trap
.  nop \h'\\n[lss]u'\c
..


Regards,
Branden

G. Branden Robinson <gbranden>
Group administrator
Wed 23 Feb 2022 01:08:36 PM UTC, comment #7: 

But for now, I guessed it's possible to silence a specific warning, by redefining some macro.  Isn't it possible?  It's not as easy as enabling a switch, but it's already good enough I think.

That will allow you to procrastinate even more :)

Alejandro Colomar <alx>
Wed 23 Feb 2022 12:46:39 PM UTC, comment #6: 

comment #5:

> What I'd like then, is to be able easily preclude some warnings.  I guess it's possible, but would like you to confirm (and hopefully show an example).  For example, for clang-tidy, I use:
>
> $ cat etc/clang-tidy/config.yaml
> ---
> Checks: >
>     *,
>     -altera-id-dependent-backward-branch,
>     -altera-unroll-loops,
>     -bugprone-narrowing-conversions,
>     -clang-analyzer-security.insecureAPI.DeprecatedOrUnsafeBufferHandling,
>     -concurrency-mt-unsafe,
>     -cppcoreguidelines-avoid-magic-numbers,
>     -cppcoreguidelines-init-variables,
>     -cppcoreguidelines-narrowing-conversions,
>     -google-readability-braces-around-statements,
>     -hicpp-braces-around-statements,
>     -llvmlibc-restrict-system-libc-headers,
>     -misc-no-recursion,
>     -readability-braces-around-statements,
>     -readability-function-cognitive-complexity,
>     -readability-isolate-declaration,
>     -readability-magic-numbers,
>
> WarningsAsErrors: >
>     *,
> ...
>
>
> Something similar in a <etc/groff/tmac/checkstyle_exceptions.tmac> would be nice.  Since maybe there are other things in level3  (or a hypothetical level4) that I do want.  My typical usage of warnings is:  set them all, and then remove those that cause noise.


I completely understand and sympathize with your aims, here, and in general I share them.  The only problem is that to attack the problem as you suggest requires that thing I explicitly disclaimed the (undocumented) "CHECKSTYLE" feature as missing:

design.

If I change CHECKSTYLE in the future such that there is something in else in level 3 that you want, or introduce a level 4, then I reckon that will be the time to roll up my sleeves and develop a proper design, with names for the warning types, and (ugh) string parsing inside the macro package to set up flags for the desired warnings.

But right now, that is a significant investment for no extant use case, so I want to procrastinate it.  :)

I am very glad to hear that -rCHECKSTYLE=2 meets your current needs without giving up anything that you want.  I will therefore change the summary of and postpone this ticket until the dread day arrives when I must practice the art of design. ;-)

G. Branden Robinson <gbranden>
Group administrator
Tue 15 Feb 2022 02:24:01 PM UTC, comment #5: 


comment #3:

>
> [comment #2 comment #2:
> > Don't worry about that; I very well know it's "not" a literal mode.  You taught me that a long time ago.  I haven't checked groff_man_style(7), though, and don't know if it needs to be clearer to newcomers; but to me it is.
>
> That's good.  I'd still welcome your feedback on the document as a whole.  Though it's not ultra-short, and might take a bit of time to review.


Will do :-)

 

> > Are you sure you want to write programs as pure man(7)?
>
> Well, no, I'm not sure--recall what I said about the CHECKSTYLE feature not being designed.  It's there to scratch the itches I had in my long-term grind to thoroughly revise the groff man page corpus.
>
> I do know that I want these warnings even inside .EX/.EE sections in groff man pages.


That makes sense.

What I'd like then, is to be able easily preclude some warnings.  I guess it's possible, but would like you to confirm (and hopefully show an example).  For example, for clang-tidy, I use:

$ cat etc/clang-tidy/config.yaml
---
Checks: >
    *,
    -altera-id-dependent-backward-branch,
    -altera-unroll-loops,
    -bugprone-narrowing-conversions,
    -clang-analyzer-security.insecureAPI.DeprecatedOrUnsafeBufferHandling,
    -concurrency-mt-unsafe,
    -cppcoreguidelines-avoid-magic-numbers,
    -cppcoreguidelines-init-variables,
    -cppcoreguidelines-narrowing-conversions,
    -google-readability-braces-around-statements,
    -hicpp-braces-around-statements,
    -llvmlibc-restrict-system-libc-headers,
    -misc-no-recursion,
    -readability-braces-around-statements,
    -readability-function-cognitive-complexity,
    -readability-isolate-declaration,
    -readability-magic-numbers,

WarningsAsErrors: >
    *,
...


Something similar in a <etc/groff/tmac/checkstyle_exceptions.tmac> would be nice.  Since maybe there are other things in level3  (or a hypothetical level4) that I do want.  My typical usage of warnings is:  set them all, and then remove those that cause noise.

Alejandro Colomar <alx>
Tue 15 Feb 2022 02:12:49 PM UTC, comment #4: 


comment #3:

> I don't blame you, but you don't have to do this.  You can use -rCHECKSTYLE=2 instead of 3.  Or, more deviously, you could edit your /etc/groff/man.local to redefine the blank line and leading space trap macros.  (Keep the non-diagnostic bits, which reproduce what the formatter would have done by default anyway.)


Er, easier still, adding these to /etc/groff/man.local (on Debian-derived systems)...


.blm
.lsm


...will simply clear the traps and shut up my warnings.

G. Branden Robinson <gbranden>
Group administrator
Tue 15 Feb 2022 02:04:34 PM UTC, comment #3: 


[comment #2 comment #2:

> Don't worry about that; I very well know it's "not" a literal mode.  You taught me that a long time ago.  I haven't checked groff_man_style(7), though, and don't know if it needs to be clearer to newcomers; but to me it is.


That's good.  I'd still welcome your feedback on the document as a whole.  Though it's not ultra-short, and might take a bit of time to review.

> Buuut, do we want to write code EXAMPLES non-literally?  I mean, to write those programs, I first write the program, use it, then copy it to the manual page, and fix the few escape sequences that I find.


That sounds like a good workflow.  I don't expect much else to be required apart from replacing blank lines with ".P" and adding ".RS" and ".RE" inside brace scopes or around continuation lines.

> Rewriting (or having a script to transform it into perfect man(7) input) is not something that I'm not sure if I'm entirely happy with.


I don't blame you, but you don't have to do this.  You can use -rCHECKSTYLE=2 instead of 3.  Or, more deviously, you could edit your /etc/groff/man.local to redefine the blank line and leading space trap macros.  (Keep the non-diagnostic bits, which reproduce what the formatter would have done by default anyway.)
 

> Are you sure you want to write programs as pure man(7)?


Well, no, I'm not sure--recall what I said about the CHECKSTYLE feature not being designed.  It's there to scratch the itches I had in my long-term grind to thoroughly revise the groff man page corpus.

I do know that I want these warnings even inside .EX/.EE sections in groff man pages.

Your needs as co-maintainer of the Linux man-pages project, with its hugely greater emphasis on section 2, 3, and 4 pages, are a little bit different.  I'm anxious to learn as much as I can from your experiences, because the demands of pages in those sections constitute a gap in my knowledge of deficiencies in groff's dialect man(7) language.

I think I have a pretty good idea what the writers of section 1,  5, and 7 pages require, because I've spent a lot of time with those hats on.  (I recklessly regard sections 6 and 8 as having essentially the same concerns as section 1.)

A sed script can probably handle the issues of character conversion to special character escape sequences as well as blank line conversion to .P.

Handling multiple indentation levels would require a bit more firepower, to track the amount of nesting.  So maybe Perl would be a good solution.

I'm happy to help write c-to-example.pl.

G. Branden Robinson <gbranden>
Group administrator
Tue 15 Feb 2022 01:40:47 PM UTC, comment #2: 

Hi Branden,

comment #1:
[...]

> All of this said, and because I've had to say it, I feel that the existing groff_man_style(7) page does not make it clear enough that material within .EX/.EE is not in a "literal mode".  I intend to make several of the above points (briefly) in a forthcoming revision.


Don't worry about that; I very well know it's "not" a literal mode.  You taught me that a long time ago.  I haven't checked groff_man_style(7), though, and don't know if it needs to be clearer to newcomers; but to me it is.

Buuut, do we want to write code EXAMPLES non-literally?  I mean, to write those programs, I first write the program, use it, then copy it to the manual page, and fix the few escape sequences that I find.  Rewriting (or having a script to transform it into perfect man(7) input) is not something that I'm not sure if I'm entirely happy with.

Are you sure you want to write programs as pure man(7)?

Alejandro Colomar <alx>
Tue 15 Feb 2022 01:29:25 PM UTC, comment #1: 

original submission:

> I got a few warnings about blank lines for code inside .EX/.EE.
> That is typical and expected.  CHECKSTYLE should not warn about those.


Hi Alex,

On further reflection, I disagree.

Typical, it may be.  Something the formatter should honor as best it can, it is.  Expected, yes--but we expect a lot of bad style from man pages in general, especially those produced by the notorious docbook-to-man.

Good style, I cannot concur with.

One of the things I'd really like man page authors to understand is that .EX/.EE is not a "literal region".

I will grant that it is easy to confuse it for one.  It is typically used to represent things that should be input literally, yes.  But a "literal mode" in and of itself, it is not.

Yes, filling is turned off.  That has several major consequences.  Since filling is off, automatic breaking is off.  Since automatic breaking is off, automatic hyphenation is as well.  That's going to feel a lot like a "literal mode" to many users.

However, text is still being formatted.  For example, inter-sentence spacing is still added.

Granted, this is going to be hard to see in most examples.  Here's the closest thing to a real-world example I can think of right now.


$ cat EXPERIMENTS/EX-with-inter-sentence-spacing.man
.TH foo 1 2022-02-15 "groff test suite"
.SH Name
foo \- frobnicate a bar
.SH Examples
Consider the following regex for an engine that lacks the
.B +
quantifier.
.EX
######################
foo | grep \[aq].  *stuff\[aq]
.EE
.ss 12 48 \" set supplementary inter-sentence spacing to 4n
.EX
######################
foo | grep \[aq].  *stuff\[aq]
.EE
$ ./build/test-groff -b -ww -rCHECKSTYLE=3 -Tutf8 -man EXPERIMENTS/EX-with-inter-sentence-spacing.man
foo(1)                      General Commands Manual                     foo(1)

Name
       foo - frobnicate a bar

Examples
       Consider the following regex for an engine that lacks the + quantifier.
       ######################
       foo | grep '.  *stuff'
       ######################
       foo | grep '.     *stuff'

groff test suite                  2022-02-15                            foo(1)


(Modulus blank vertical lines around the headers and footers, groff 1.22.4 output is the same.)

People can use different font styles inside .EX/.EE regions and I encourage them to do so where it aids exposition.  In subsection "Using groff as a REPL" of groff(1), I in fact use all three basic styles.

I can hear the cries from the linux-man mailing list even now.

"But, Branden, what if we want a blank line in our example?  A blank line is the only way to get it!"

No, it's not.  Use the `P` macro.  It works to separate paragraphs elsewhere, why wouldn't it here?

"But, Branden, what if we want to indent the example, or only part of it, or vary the indentation at several different levels within it?  Leading spaces are the only way to do this in the .EX/.EE literal mode!!"

No, it's not--not the only way, and .EX/.EE is not a "literal mode".  Use .RS/.RE.  You then don't even have to count the number of spaces you type.  Simply tell .RS how many ens you want.

I'm happy to help adapt existing examples in the man-pages project corpus, at least to point the way with some sample cases, and/or tackle the tricky ones that give people trouble.

All of this said, and because I've had to say it, I feel that the existing groff_man_style(7) page does not make it clear enough that material within .EX/.EE is not in a "literal mode".  I intend to make several of the above points (briefly) in a forthcoming revision.

Ticket rescoped.

What do you think?

G. Branden Robinson <gbranden>
Group administrator
Sat 12 Feb 2022 06:45:41 PM UTC, original submission:  

I got a few warnings about blank lines for code inside .EX/.EE.
That is typical and expected.  CHECKSTYLE should not warn about those.

Alejandro Colomar <alx>

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

No files currently attached

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by gbranden (Updated the item)
  • -email is unavailable- added by alx (Submitted the item)
  • -email is unavailable- added by alx
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only logged-in users can vote.

     

    Follow 10 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2023-08-10 gbranden StatusPostponed None
    2022-08-23 gbranden Summary[man]: want designed, documented CHECKSTYLE feature [man] want designed, documented CHECKSTYLE feature
    2022-02-23 gbranden Severity3 - Normal 1 - Wish
        StatusIn Progress Postponed
        Summarygroff: CHECKSTYLE: (incorrect) warning about blank lines inside .EX/.EE [man]: want designed, documented CHECKSTYLE feature
    2022-02-15 gbranden CategoryGeneral Macro man
        Item GroupLint Documentation
    2022-02-15 gbranden StatusNone In Progress
        Assigned toNone gbranden
    2022-02-12 alx Carbon-Copy- Added g. branden robinson <g.branden.robinson@gmail.com>

    Back to the top

    Powered by Savane 3.13-d3ae.
    Corresponding source code