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

[Ingo Schwarze <schwarze@usta.de>]

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