discuss@mandoc.bsd.lv
 help / color / mirror / Atom feed
* Clarification needed in regards to "WARNING: blank line in fill mode, using .sp"
@ 2021-09-28  0:20 Raf Czlonka
  2021-09-28 15:10 ` Ingo Schwarze
  0 siblings, 1 reply; 4+ messages in thread
From: Raf Czlonka @ 2021-09-28  0:20 UTC (permalink / raw)
  To: discuss

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


^ permalink raw reply	[flat|nested] 4+ messages in thread

end of thread, other threads:[~2021-09-30 13:11 UTC | newest]

Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-09-28  0:20 Clarification needed in regards to "WARNING: blank line in fill mode, using .sp" Raf Czlonka
2021-09-28 15:10 ` Ingo Schwarze
2021-09-29 16:23   ` Raf Czlonka
2021-09-30 13:11     ` Ingo Schwarze

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