tech@mandoc.bsd.lv
 help / color / mirror / Atom feed
From: Ingo Schwarze <schwarze@usta.de>
To: tech@mdocml.bsd.lv
Subject: Re: remove .Xr spacing tweak
Date: Sun, 4 Dec 2011 02:05:40 +0100	[thread overview]
Message-ID: <20111204010540.GO17667@iris.usta.de> (raw)
In-Reply-To: <4EDA9839.9050001@bsd.lv>

Hi Kristaps,

Kristaps Dzonsons wrote on Sat, Dec 03, 2011 at 10:44:25PM +0100:
> On 03/12/2011 19:16, Ingo Schwarze wrote:

>>i think it is time to remove an OpenBSD-specific tweak from the .Xr
>>handling in OpenBSD mandoc(1) and make it compatible with bsd.lv
>>mandoc and with groff-1.21.
>>Right now, OpenBSD assumes an implicit .Ns after .Xr's second
>>argument, if more non-punctuation arguments follow.
>>
>>This tweak in mdoc_macro.c was originally added for compatibility
>>with groff-1.15, which is now gone for some time.
>>
>>The patch also scours the base tree, adapting those pages where
>>the rendering would change.

> Of course this is fine by me -- the code is #ifdef'd in my repo
> anyway.

It's always a pleasure to remove code bearing an XXX comment
to the effect that it is ugly and unlikely to go away.  :-)

> Does this warrant a COMPATIBILITY note, as it relates to
> old groff behaviour?

I don't think so.

  Ten-year old groff added an additional blank character to
  the output if some macro was called with more arguments
  than it normally supports; nobody was sure why, it seemed
  a bit illogical.  Maybe it was a bug, but anyway, it was
  fixed in groff half a decade ago.

That sounds quite silly in a manual, doesn't it?
There is no need to document every single ancient groff
idiosyncrasy, that would just bloat the documentation.

Of course it's always a matter of judgement, i think clear
rules are hard to find for deciding what warrants mention
below COMPATIBILITY.  Roughly, i'd say that

 * Recent changes are more important than ancient bugs.
 * Groff/mandoc differences are more important than
   new/old groff differences.
 * Parser incompatibilities are more important than rendering
   differences.
 * Text differences are more important than whitespace
   differences.

Very roughly, i'd maybe say that we should mention it
if it's recent OR affects the parsers OR may affect the
content.

Yours,
  Ingo
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv

      reply	other threads:[~2011-12-04  1:05 UTC|newest]

Thread overview: 3+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2011-12-03 18:16 Ingo Schwarze
2011-12-03 21:44 ` Kristaps Dzonsons
2011-12-04  1:05   ` Ingo Schwarze [this message]

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20111204010540.GO17667@iris.usta.de \
    --to=schwarze@usta.de \
    --cc=tech@mdocml.bsd.lv \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
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).