Re: Feature request: generate documentation from C files

[Simon Josefsson]

"Eli Zaretskii" <address@hidden> writes:

>> From: Simon Josefsson <address@hidden>
>> Date: Sun, 02 Nov 2003 14:52:42 +0100
>> 
>> >> (*) Mostly because I can M-x man RET on a function to immediately
>> >> access its documentation.  Nothing like that for info, as far as I
>> >> know..
>> >
>> > Try "C-h TAB" (with point somewhere on the name of a function).
>> 
>> Hm, I just get: C-h TAB (translated from C-h <tab>) is undefined
>
> Oops, sorry, I meant "C-h S".

The docstring says it only looks in 'the relevant manuals', which
appear to depend on which major mode I'm in.  How can I add, e.g., the
libidn manual, to the list of 'relevant manuals' for c-mode?

>> > We still need some markup for references to other parts of the docs,
>> > and for references to symbols: names of functions, variables, and
>> > arguments/meta-syntactic elements.
>> 
>> Yes, although I think %NULL, strlen(), @string etc is less obtrusive
>> than the texinfo/SGML/whatever markup, within a C source comment.
>
> They might be less obtrusive, but they are not enough to express an
> xref to another document.
>
> They _may_ be enough for @code, @var, and the like, but we need to
> define and agree upon replacements.  xrefs require more complex
> markup.

Yes, although I'm not sure I see the need to express @xrefs within a C
source comment, what meaning would it have when you output man pages,
HTML, docbook etc?  I'm trying to find a markup that will allow me to
express things that can be usefully rendered in many output formats,
not just texinfo.  A lowest common denominator.  For the Texinfo
manual, which I agree should contain @xrefs, I can write those @xrefs
as part of the manual itself, before or after I do @include
texi/strlen.texi to get the concise function definition.

It is not only the markup that has to work across the output formats,
the stylistic content must work as well.  If you are not careful, when
documenting a function in pure Texinfo, the result is not useful in a
man page, and vice versa.

It would be nice if references worked, but using @xref directly lead
to some problems I don't know how to solve (like, what should be
generated for man-pages?).

> Btw, using "strlen()" is simply a bad habit: it looks like a call to
> `strlen' with no arguments, which is not what you want.

Right, although it is a widely spread idiom when talking about the C
language, so for a informal markup it might work.  The texinfo output
for it doesn't have to include (), it could look like @code{strlen} so
the resulting manual look correct.