Re: PATCH: Document @file

[Nick Clifton <nickc at redhat dot com>]

Hi Mark,

> cannot open @value{top_srcdir}/../libiberty/at-file.texi or
> /@value{top_srcdir}/../libiberty/at-file.texi: No such file or directory
> make: [as.1] Error 2 (ignored)
>
> Apparently, texi2pod.pl doesn't support "@include @value{...}"; it
> doesn't expand the @value syntax.  For now, I would like to add the new
> documentation inside:
>
> @ifclear man
> ...
> @end ifclear
>
> so that it is still available in info pages.  I'd rather not try to fix
> texi2pod.pl, since I don't really know perl very well, but if you think
> I should before checking in the changes to as and ld, I will try.

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".

Cheers
  Nick