* 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
* Re: Clarification needed in regards to "WARNING: blank line in fill mode, using .sp" 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 0 siblings, 1 reply; 4+ messages in thread From: Ingo Schwarze @ 2021-09-28 15:10 UTC (permalink / raw) To: Raf Czlonka; +Cc: discuss 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 ^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: Clarification needed in regards to "WARNING: blank line in fill mode, using .sp" 2021-09-28 15:10 ` Ingo Schwarze @ 2021-09-29 16:23 ` Raf Czlonka 2021-09-30 13:11 ` Ingo Schwarze 0 siblings, 1 reply; 4+ messages in thread From: Raf Czlonka @ 2021-09-29 16:23 UTC (permalink / raw) To: Ingo Schwarze; +Cc: discuss 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 ^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: Clarification needed in regards to "WARNING: blank line in fill mode, using .sp" 2021-09-29 16:23 ` Raf Czlonka @ 2021-09-30 13:11 ` Ingo Schwarze 0 siblings, 0 replies; 4+ messages in thread From: Ingo Schwarze @ 2021-09-30 13:11 UTC (permalink / raw) To: Raf Czlonka; +Cc: discuss 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 ^ 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).