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

[G. Branden Robinson]

Follow-up Comment #3, bug #62042 (project groff):


[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.

    _______________________________________________________

Reply to this item at:

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

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