This is the mail archive of the
binutils@sourceware.org
mailing list for the binutils project.
Re: PATCH: Document @file
Nick Clifton wrote:
> Hmm - so this would mean that the man pages would not document the @file
> syntax ? I think that that would be a bad idea. In my opinion the best
> thing to do would be to fix texi2pod.pl, since that will presumably help
> everybody (who writes docs) not just us. But since I am not a perl
> hacker either I can quite sympathize with not wanting to muck about
> inside that script.
>
> So instead, I would be happy with a patch that used the "@ifclear man
> ... @end ifclear" thunk as described above, but only if it also included
> a "@ifset man <short description of @file> @end ifset" thunk and also a
> comment saying "remove the @ifset man thunk and the @ifclear man
> prototectors once texi2pod.pl accepts @value".
Just to close the loop, I bit the bullet and fixed texi2pod.pl. I've
submitted that patch. At present, I'm planning just to leave the
documentation for as/ld in limbo, until that patch is either accepted or
rejected.
However, the current situation is a bit ugly. The current status is
that binutils documents @file (but you need a makeinfo more recent than
4.2, which means people building with 4.2 get errors in their builds),
and that as/ld/gprof do not mention @file at all in their manuals. If
there's anything you'd like me to do to mitigate the situation in the
short term, let me know.
--
Mark Mitchell
CodeSourcery, LLC
mark@codesourcery.com
(916) 791-8304