discuss@mandoc.bsd.lv
 help / color / mirror / Atom feed
From: Ingo Schwarze <schwarze@usta.de>
To: Raf Czlonka <rczlonka@gmail.com>
Cc: discuss@mandoc.bsd.lv
Subject: Re: Clarification needed in regards to "WARNING: blank line in fill mode, using .sp"
Date: Thu, 30 Sep 2021 15:11:20 +0200	[thread overview]
Message-ID: <YVW3eFpFqzqn0oMW@asta-kit.de> (raw)
In-Reply-To: <YVSTFV6Wzh1I1xMX@gmail.com>

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


      reply	other threads:[~2021-09-30 13:11 UTC|newest]

Thread overview: 4+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-09-28  0:20 Raf Czlonka
2021-09-28 15:10 ` Ingo Schwarze
2021-09-29 16:23   ` Raf Czlonka
2021-09-30 13:11     ` Ingo Schwarze [this message]

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=YVW3eFpFqzqn0oMW@asta-kit.de \
    --to=schwarze@usta.de \
    --cc=discuss@mandoc.bsd.lv \
    --cc=rczlonka@gmail.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
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).