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
prev parent 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).