PATCH: Document @file

[Mark Mitchell]

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