[bug #62042] groff: CHECKSTYLE: (incorrect) warning about blank lines inside .EX/.EE

[G. Branden Robinson]

Update of bug #62042 (project groff):

                Category:                 General => Macro man              
              Item Group:                    Lint => Documentation          

    _______________________________________________________

Follow-up Comment #1:

[comment #0 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?

    _______________________________________________________

Reply to this item at:

  <https://savannah.gnu.org/bugs/?62042>

_______________________________________________
  Message sent via Savannah
  https://savannah.gnu.org/