* Re: mdocml: Add a "last child" member of struct mdoc_node. [not found] <201012152339.oBFNdeuH023314@krisdoz.my.domain> @ 2010-12-21 22:59 ` Ingo Schwarze 2010-12-22 11:35 ` Kristaps Dzonsons 0 siblings, 1 reply; 2+ messages in thread From: Ingo Schwarze @ 2010-12-21 22:59 UTC (permalink / raw) To: tech Hi Kristaps, > 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. Yours, Ingo P.S. See here for the full story: http://www.openbsd.org/faq/ports/specialtopics.html#Mandoc -- To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv ^ permalink raw reply [flat|nested] 2+ messages in thread
* Re: mdocml: Add a "last child" member of struct mdoc_node. 2010-12-21 22:59 ` mdocml: Add a "last child" member of struct mdoc_node Ingo Schwarze @ 2010-12-22 11:35 ` Kristaps Dzonsons 0 siblings, 0 replies; 2+ messages in thread From: Kristaps Dzonsons @ 2010-12-22 11:35 UTC (permalink / raw) To: tech >> 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 ^ permalink raw reply [flat|nested] 2+ messages in thread
end of thread, other threads:[~2010-12-22 11:35 UTC | newest] Thread overview: 2+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- [not found] <201012152339.oBFNdeuH023314@krisdoz.my.domain> 2010-12-21 22:59 ` mdocml: Add a "last child" member of struct mdoc_node Ingo Schwarze 2010-12-22 11:35 ` Kristaps Dzonsons
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).