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

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

[Ingo Schwarze]

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

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

[Kristaps Dzonsons]

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