Clarification needed in regards to "WARNING: blank line in fill mode, using .sp"

Clarification needed in regards to "WARNING: blank line in fill mode, using .sp"

[Raf Czlonka]

Hello,

While linting mdoc(7)-formatted manual pages, blank lines in them
generate the below warning message:

	mandoc: foo.1:20:1: WARNING: blank line in fill mode, using .sp

'.sp' is obviously a roff(7) request and the above, if not explicitly,
does seem to suggest using it is the "proper" way to fix the manual
page's formatting, at least implicitly.

This seem to be contrary to what the mdoc(7) manual page says:

	Many aspects of the basic syntax of the mdoc language are
	based on the roff(7) language; see the LANGUAGE SYNTAX and
	MACRO SYNTAX sections in the roff(7) manual for details,
	in particular regarding comments, escape sequences, whitespace,
	and quoting.  However, using roff(7) requests in mdoc
	documents is discouraged; mandoc(1) supports some of them
	merely for backward compatibility.

I'm obviously talking about the "discouraged" here as there's no
backward compatibility to speak of - as mentioned earlier, this is
an mdoc(7)-formatted manual page.

Given that '.sp' is nowhere to be found in mdoc(7) and is only
present in roff(7), perhaps the warning should mention '.Pp' macro
instead?

Without knowing any of the above, one might simply take the warning
at a face value and replace the blank line with roff(7)'s '.sp'.

What do others think? What should the linter say in order to aid
new authors in producing better-formatted mdoc(7) manual pages?

Regards,

Raf
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: Clarification needed in regards to "WARNING: blank line in fill mode, using .sp"

[Ingo Schwarze]

Hi Raf,

Raf Czlonka wrote on Tue, Sep 28, 2021 at 01:20:51AM +0100:

> While linting mdoc(7)-formatted manual pages, blank lines in them
> generate the below warning message:
> 
> 	mandoc: foo.1:20:1: WARNING: blank line in fill mode, using .sp
> 
> '.sp' is obviously a roff(7) request and the above, if not explicitly,
> does seem to suggest using it is the "proper" way to fix the manual
> page's formatting, at least implicitly.

It does absolutely not suggest that.  mandoc messages almost
never instruct the document author what to do.  Those very few
messages doing that anyway are explicit about it:

     consider using OS macro
     verbatim "--", maybe consider using \(em
     .so is fragile, better use ln(1)

Mandoc messages typically consist of of two parts: the first part states
a fact describing some problem, and the second part states what the
mandoc(1) program is doing to work around the problem, often using the
idiom "<comma> using <foobar>":

     missing manual title, using UNTITLED
     missing manual section, using ""
     missing date, using ""
     cannot parse date, using it verbatim
     date in the future, using it anyway
     missing description line, using ""
     empty argument, using 0n
     missing display type, using -ragged
     missing -width in -tag list, using 8n
     missing utility name, using ""
     missing function name, using ""
     missing argument, using next line
     missing font type, using \fR
     unknown font type, using \fR
     missing option string, using ""
     missing resource identifier, using ""
     missing eqn box, using ""
     undefined string, using ""
     missing list type, using -item
     argument is not numeric, using 1
     missing manual name, using ""
     uname(3) system call failed, using UNKNOWN

Note that most of these fallbacks have low chances of matching what
the document author actually intended; they merely allow parsing and
formatting to continue in spite of the problem.

Sometimes, the message does not specify a fallback if none is needed
for any of various reasons, for example:

     legacy man(7) date format
     useless macro
     referenced manual not found
     input text line longer than 80 bytes
     whitespace at end of input line
     prologue macros out of order
     content before first section header
     ...

Sometimes, the message *only* specifies the workaround because that
implicitly describes the problem as well:

     skipping paragraph macro
     moving paragraph macro out of list
     skipping no-space macro
     moving content out of list
     skipping empty request
     skipping empty macro
     skipping duplicate argument
     skipping duplicate display type
     skipping duplicate list type
     skipping -width argument
     skipping unknown tbl option
     ignoring excessive spacing in tbl layout
     ignoring data in spanned tbl cell
     ignoring extra tbl data cells
     skipping late title macro
     skipping bad character
     skipping unknown macro
     skipping request outside macro
     skipping insecure request
     skipping item outside list
     skipping column outside column list
     skipping end of block that is not open
     inserting missing end of block
     appending missing end of block
     skipping display without arguments
     skipping all arguments
     skipping excess arguments
     ignoring macro in table
     skipping tbl in -Tman mode
     skipping eqn in -Tman mode

If you wonder *why* the fact described by a message is problematic
and what you might do about it, please consult the mandoc(1) manual,
in this case:

  blank line in fill mode, using .sp
  (mdoc) The meaning of blank input lines is only well-defined in non-fill
  mode: In fill mode, line breaks of text input lines are not supposed to
  be significant.  However, for compatibility with groff, blank lines in
  fill mode are formatted like sp requests.  To request a paragraph break,
  use Pp instead of a blank line.

Do *not* try to guess what to do about a message from the message itself
unless you are sure you fully understand its meaning and rationale.

That said, note that this message says ", using .sp", *not* "consider
using" or "better use".

> This seem to be contrary to what the mdoc(7) manual page says:
> 
> 	Many aspects of the basic syntax of the mdoc language are
> 	based on the roff(7) language; see the LANGUAGE SYNTAX and
> 	MACRO SYNTAX sections in the roff(7) manual for details,
> 	in particular regarding comments, escape sequences, whitespace,
> 	and quoting.  However, using roff(7) requests in mdoc
> 	documents is discouraged; mandoc(1) supports some of them
> 	merely for backward compatibility.
> 
> I'm obviously talking about the "discouraged" here as there's no
> backward compatibility to speak of - as mentioned earlier, this is
> an mdoc(7)-formatted manual page.

Yes.  Using .sp in mdoc(7) - and even in man(7)! - is usually bad
style.

> Given that '.sp' is nowhere to be found in mdoc(7) and is only
> present in roff(7), perhaps the warning should mention '.Pp' macro
> instead?

Absolutely not, that would be a lie.  Wenn you do have a blank line
in fill mode, the parser uses .sp as the fallback, *not* .Pp.

> Without knowing any of the above, one might simply take the warning
> at a face value and replace the blank line with roff(7)'s '.sp'.
> 
> What do others think? What should the linter say in order to aid
> new authors in producing better-formatted mdoc(7) manual pages?

I think the existing message is accurate and concise, and the
existing documentation is probably intelligible for newbies, too.
Maybe some may not know what "fill mode" is.  Then again, searching
for "fill" in the mdoc(7) manual brings up the description
of ".Bd -filled" as the first match, and that describes quite
well what "fill mode" means in practice.  So i'm not sure what to
improve.

Giving a rigorous description of what "fill mode" means would seem
out of scope and excessively technical for mdoc(7) and mandoc(1)
because that is a low-level roff(7) feature, and explaining it in
even more detail in roff(7) than the .fi entry already explains it
would seem out of scope even there because the mandoc roff(7) page
is not intended as exhaustive ROFF documentation, but merely a list
of syntax elements with their fundamental meanings.

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: Clarification needed in regards to "WARNING: blank line in fill mode, using .sp"

[Raf Czlonka]

Hi Ingo,

On Tue, Sep 28, 2021 at 04:10:00PM BST, Ingo Schwarze wrote:
> 
> [...]
> 
> If you wonder *why* the fact described by a message is problematic
> and what you might do about it, please consult the mandoc(1) manual,
> in this case:
> 
>   blank line in fill mode, using .sp
>   (mdoc) The meaning of blank input lines is only well-defined in non-fill
>   mode: In fill mode, line breaks of text input lines are not supposed to
>   be significant.  However, for compatibility with groff, blank lines in
>   fill mode are formatted like sp requests.  To request a paragraph break,
>   use Pp instead of a blank line.

Sure, I did read it - it was also the reason why I've mentioned Pp.

> Do *not* try to guess what to do about a message from the message itself
> unless you are sure you fully understand its meaning and rationale.
> 
> That said, note that this message says ", using .sp", *not* "consider
> using" or "better use".

I guess one might read this as "Hey! I'm using .sp, and so should you!" ;^)

> > This seem to be contrary to what the mdoc(7) manual page says:
> > 
> > 	Many aspects of the basic syntax of the mdoc language are
> > 	based on the roff(7) language; see the LANGUAGE SYNTAX and
> > 	MACRO SYNTAX sections in the roff(7) manual for details,
> > 	in particular regarding comments, escape sequences, whitespace,
> > 	and quoting.  However, using roff(7) requests in mdoc
> > 	documents is discouraged; mandoc(1) supports some of them
> > 	merely for backward compatibility.
> > 
> > I'm obviously talking about the "discouraged" here as there's no
> > backward compatibility to speak of - as mentioned earlier, this is
> > an mdoc(7)-formatted manual page.
> 
> Yes.  Using .sp in mdoc(7) - and even in man(7)! - is usually bad
> style.
> 
> > Given that '.sp' is nowhere to be found in mdoc(7) and is only
> > present in roff(7), perhaps the warning should mention '.Pp' macro
> > instead?
> 
> Absolutely not, that would be a lie.  Wenn you do have a blank line
> in fill mode, the parser uses .sp as the fallback, *not* .Pp.

OK, a different, perhaps an easier, question then. In the most
obvious, nine times out of ten, scenario where a blank line separates
two sentences, shouldn't .Pp be used instead of .sp, given that
both the latter, as well as blank lines, are considered bad style?

Regards,

Raf
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: Clarification needed in regards to "WARNING: blank line in fill mode, using .sp"

[Ingo Schwarze]

Hi Raf,

Raf Czlonka wrote on Wed, Sep 29, 2021 at 05:23:49PM +0100:
> On Tue, Sep 28, 2021 at 04:10:00PM BST, Ingo Schwarze wrote:

>> [...]
>> If you wonder *why* the fact described by a message is problematic
>> and what you might do about it, please consult the mandoc(1) manual,
>> in this case:
>> 
>>   blank line in fill mode, using .sp
>>   (mdoc) The meaning of blank input lines is only well-defined in non-fill
>>   mode: In fill mode, line breaks of text input lines are not supposed to
>>   be significant.  However, for compatibility with groff, blank lines in
>>   fill mode are formatted like sp requests.  To request a paragraph break,
>>   use Pp instead of a blank line.

> Sure, I did read it - it was also the reason why I've mentioned Pp.
 
>> Do *not* try to guess what to do about a message from the message itself
>> unless you are sure you fully understand its meaning and rationale.
>> 
>> That said, note that this message says ", using .sp", *not* "consider
>> using" or "better use".

> I guess one might read this as "Hey! I'm using .sp, and so should you!" ;^)

The message needs a prefix ("mandoc: <stdin>:1:1: WARNING: ", at least 30
bytes) and the main description ("blank line in fill mode", 23 bytes),
so we are left with about 78-30-23 = 25 bytes for describing the fallback
action taken by mandoc.  The wording ", using .sp" is accurate and
concise.  It is not possible to provide a long explanation within 25 bytes,
and when you try hard enough, you can misunderstand anything that is
expressed concisely.

Do you have a specific suggestion how to describe the fallback action
in a way that is harder to misunderstand, within 25 bytes?

Note that ".Pp" must *not* appear in the description of the fallback
action because that action is completely unrelated to .Pp.

>>> This seem to be contrary to what the mdoc(7) manual page says:
>>> 
>>> 	Many aspects of the basic syntax of the mdoc language are
>>> 	based on the roff(7) language; see the LANGUAGE SYNTAX and
>>> 	MACRO SYNTAX sections in the roff(7) manual for details,
>>> 	in particular regarding comments, escape sequences, whitespace,
>>> 	and quoting.  However, using roff(7) requests in mdoc
>>> 	documents is discouraged; mandoc(1) supports some of them
>>> 	merely for backward compatibility.
>>> 
>>> I'm obviously talking about the "discouraged" here as there's no
>>> backward compatibility to speak of - as mentioned earlier, this is
>>> an mdoc(7)-formatted manual page.

>> Yes.  Using .sp in mdoc(7) - and even in man(7)! - is usually bad
>> style.

>>> Given that '.sp' is nowhere to be found in mdoc(7) and is only
>>> present in roff(7), perhaps the warning should mention '.Pp' macro
>>> instead?

>> Absolutely not, that would be a lie.  Wenn you do have a blank line
>> in fill mode, the parser uses .sp as the fallback, *not* .Pp.

> OK, a different, perhaps an easier, question then. In the most
> obvious, nine times out of ten, scenario where a blank line separates
> two sentences, shouldn't .Pp be used instead of .sp, given that
> both the latter, as well as blank lines, are considered bad style?

Yes.  But so what?  The mandoc(1) manual page already says just that.

Or do you mean that i should change the behaviour of the mandoc(1)
program?  No, because that is dictated by compatibility with groff:

   $ printf "one\n\ntwo\n" | troff -mdoc | grep ^V
  mdoc warning: Empty input line #2
  V12000
  V36000
  V792000
   $ printf "one\n.sp\ntwo\n" | troff -mdoc | grep ^V
  V12000
  V36000
  V792000
   $ printf "one\n.Pp\ntwo\n" | troff -mdoc | grep ^V 
  V12000
  V30000
  V792000

https://www.gnu.org/software/groff/manual/html_node/Simple-Commands.html#Simple-Commands
describes what the above output means.

Pay attention to the second line of output.  A blank input line
moves down to the same position (V36000) as .sp, not to the
position that .Pp would move to (V30000).  So a blank line is *not*
a synonym for a paragraph break.  It is a synonym for a physical
downward movement.

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv