From mboxrd@z Thu Jan 1 00:00:00 1970 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on inbox.vuxu.org X-Spam-Level: X-Spam-Status: No, score=0.0 required=5.0 tests=none autolearn=ham autolearn_force=no version=3.4.4 Received: (qmail 16957 invoked from network); 28 Sep 2021 15:10:07 -0000 Received: from bsd.lv (HELO mandoc.bsd.lv) (66.111.2.12) by inbox.vuxu.org with ESMTPUTF8; 28 Sep 2021 15:10:07 -0000 Received: from fantadrom.bsd.lv (localhost [127.0.0.1]) by mandoc.bsd.lv (OpenSMTPD) with ESMTP id 01a457db for ; Tue, 28 Sep 2021 10:10:05 -0500 (EST) Received: from scc-mailout-kit-02.scc.kit.edu (scc-mailout-kit-02.scc.kit.edu [129.13.231.82]) by mandoc.bsd.lv (OpenSMTPD) with ESMTP id 52766a31 for ; Tue, 28 Sep 2021 10:10:03 -0500 (EST) Received: from hekate.asta.kit.edu ([141.3.145.153] helo=hekate.usta.de) by scc-mailout-kit-02.scc.kit.edu with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (envelope-from ) id 1mVEk6-0001Wl-Md; Tue, 28 Sep 2021 17:10:02 +0200 Received: from donnerwolke.asta.kit.edu ([141.3.145.61] helo=donnerwolke.usta.de) by hekate.usta.de with esmtp (Exim 4.92.2) (envelope-from ) id 1mVEk5-0004aA-3N; Tue, 28 Sep 2021 17:10:01 +0200 Received: from login-1.asta.kit.edu ([141.3.145.72]) by donnerwolke.usta.de with esmtp (Exim 4.84_2) (envelope-from ) id 1mVEk4-0004z8-V0; Tue, 28 Sep 2021 17:10:01 +0200 Received: from schwarze by login-1.asta.kit.edu with local (Exim 4.92) (envelope-from ) id 1mVEk4-0001Fu-UI; Tue, 28 Sep 2021 17:10:00 +0200 Date: Tue, 28 Sep 2021 17:10:00 +0200 From: Ingo Schwarze To: Raf Czlonka Cc: discuss@mandoc.bsd.lv Subject: Re: Clarification needed in regards to "WARNING: blank line in fill mode, using .sp" Message-ID: References: X-Mailinglist: mandoc-discuss Reply-To: discuss@mandoc.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: 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 " using ": 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