From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from smtp-2.sys.kth.se (smtp-2.sys.kth.se [130.237.32.160]) by krisdoz.my.domain (8.14.3/8.14.3) with ESMTP id oBMBZp1l016870 for ; Wed, 22 Dec 2010 06:35:52 -0500 (EST) Received: from smtp-2.sys.kth.se (localhost [127.0.0.1]) by smtp-2.sys.kth.se (Postfix) with ESMTP id 48FA614C06E for ; Wed, 22 Dec 2010 12:35:45 +0100 (CET) X-Virus-Scanned: by amavisd-new at kth.se Received: from smtp-2.sys.kth.se ([127.0.0.1]) by smtp-2.sys.kth.se (smtp-2.sys.kth.se [127.0.0.1]) (amavisd-new, port 10024) with LMTP id pdCfTGGVabij for ; Wed, 22 Dec 2010 12:35:42 +0100 (CET) X-KTH-Auth: kristaps [46.109.54.191] X-KTH-mail-from: kristaps@bsd.lv X-KTH-rcpt-to: tech@mdocml.bsd.lv Received: from macky.local (unknown [46.109.54.191]) by smtp-2.sys.kth.se (Postfix) with ESMTP id 5AFF714DCA1 for ; Wed, 22 Dec 2010 12:35:38 +0100 (CET) Message-ID: <4D11E288.1010307@bsd.lv> Date: Wed, 22 Dec 2010 13:35:36 +0200 From: Kristaps Dzonsons User-Agent: Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10.6; en-US; rv:1.9.2.12) Gecko/20101027 Thunderbird/3.1.6 X-Mailinglist: mdocml-tech Reply-To: tech@mdocml.bsd.lv MIME-Version: 1.0 To: tech@mdocml.bsd.lv Subject: Re: mdocml: Add a "last child" member of struct mdoc_node. References: <201012152339.oBFNdeuH023314@krisdoz.my.domain> <20101221225958.GA9705@iris.usta.de> In-Reply-To: <20101221225958.GA9705@iris.usta.de> Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit >> Add a "last child" member of struct mdoc_node. >> Remove `Pp' or `Lp' if it is the FIRST or LAST child of an `Sh' or `Sh' body. > > Keeping track of the last child looks nice, ... > >> Make "skipping paragraph" be an error, not a warning, as information (an >> invoked macro) is ignored. > > ... but i disagree with this part. When we say, in mandoc(1), > > error An input file contains syntax that cannot be safely interpreted, > either because it is invalid or because mandoc does not > implement it yet. By discarding part of the input or inserting > missing tokens, the parser is able to continue, and the error > does not prevent generation of formatted output, but typically, > preparing that output involves information loss, broken document > structure or unintended formatting. > > i think the most important part is the first line: > *cannot be safely interpreted* > The wording at the end, > *information loss*, > is not a definition, but rather an example. > > In any case, we are not talking about information in the mathematical > sense here, but about information that matters to the user, information > that, when being lost, could cause the user to misunderstand the > content of the manual. So, i would consider anything that might > cause loss of a blank line, or insertion of one in excess, to be safe. > > Also, this distinction is not academical, but it has practical > consequences. I'm telling people that, as long as there are errors, > they should use groff to format the manual. I'm telling them that > errors are what gives them broken manuals, with wrong content > or unintelligible formatting, for porters to worry about; > while warnings only means unclean source code, with no serious > impact on manual content, merely for authors to worry about, > in case they care about nice mdoc(7) usage. > > Here, we clearly have the second case, a warning, not an error. Ingo, Hm, I didn't consider this in the practical context of broken manuals qua groff (I blame my academical day job ;)). In that light, your argument makes perfect sense, so I've reverted the change. I'll keep this in mind when adding warnings and errors in the future... > P.S. > See here for the full story: > http://www.openbsd.org/faq/ports/specialtopics.html#Mandoc Wow, that looks great! And don't kill Espie! :-) Thanks again, Kristaps -- To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv