[Groff] Re: Bug#472903: Acknowledgement (scons: badly formatted manpage)

[Colin Watson]

reassign 472903 scons
thanks

On Sat, Mar 29, 2008 at 11:48:31AM -0700, Ian Zimmerman wrote:
> It seems groff just can't understand the .RE macro.  Removing it (and the
> corresponding .RB) from the definitions at the start of the source leads
> to a normal readable page (albeit without examples being indented).
> 
> Moreover, trying to replace the pair with .IP "" 8 and .PP doesn't work
> either - the indent stays throughout.  groff seems seriously borked in
> this area.

The manual page in question has this in its preamble (before .TH):

  .\" ES - Example Start - indents and turns off line fill
  .de ES
  .RS
  .nf
  ..
  .\" EE - Example End - ends indent and turns line fill back on
  .de EE
  .fi
  .RE
  ..

Recently, I backported a set of changes from groff CVS at the request of
some folks who wanted to be able to depend on them, adding Eric's
an-ext.tmac. Among other things, this defines this pair of macros:

  .\" Start example.
  .de EX
  .  nr mE \\n(.f
  .  nf
  .  nh
  .  ft CW
  ..
  .
  .
  .\" End example.
  .de EE
  .  ft \\n(mE
  .  fi
  .  hy \\n(HY
  ..

.de does nothing if the macro you're trying to define already exists, so
this broke your manual page. Sorry about that. There are two
straightforward ways to avoid this.

One is to simply rename your macro to something else. I'm not sure if
there's a recommended way to avoid this problem in future, though, and I
recognise that that's a problem; I'm CCing the groff list in case they
have any suggestions.

The other is to move your preamble below .TH (so that it comes after the
point where an-ext.tmac is sourced), and to remove the existing macros
before defining your own. The attached patch does this.

By the way, there are some other errors in your manual page, visible
with 'man --warnings=w'. I've attached another patch that repairs these.

Cheers,

-- 
Colin Watson                                       address@hidden

472903.diff
Description: Text Data

scons-misc.diff
Description: Text Data