Re: mdocml: Add a "last child" member of struct mdoc_node.

[Kristaps Dzonsons <kristaps@bsd.lv>]

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