Why I can't use `info' in emacs?

Why I can't use `info' in emacs?

[Ronald]

It works in bash.
But in emacs, either I use`M-x info' or `C-h C-i',
it can't display the info page.

btw:
``man 3 printf" ,  how to do it with info?
What's better man, woman or info?

Re: Why I can't use `info' in emacs?

[Harald Hanche-Olsen]

+ Ronald <followait@163.com>:

| It works in bash.
| But in emacs, either I use`M-x info' or `C-h C-i',
| it can't display the info page.

So most likely, Info-default-directory-list is set up wrong.

| btw:
| ``man 3 printf" ,  how to do it with info?

You can't.

| What's better man, woman or info?

The manual page for woman states quite clearly that "woman is better
than man" (or used to, last time I looked at it).

That said, you have little choice.  If the information you seek is
available as a man page, use (wo)man.  If it is available as an info
file, use info.  In the (no longer very) rare cases that it is
available in both formats, the info version is usually more up-to-date
and detailed.

-- 
* Harald Hanche-Olsen     <URL:http://www.math.ntnu.no/~hanche/>
- It is undesirable to believe a proposition
  when there is no ground whatsoever for supposing it is true.
  -- Bertrand Russell

Re: Why I can't use `info' in emacs?

[Ronald]

> | ``man 3 printf" ,  how to do it with info?
>
> You can't.

Take `printf' for example, how to view programmer's doc (not the shell doc) 
? 

Re: Why I can't use `info' in emacs?

[Eli Zaretskii]

> From: Ronald <followait@163.com>
> Date: Fri, 15 Dec 2006 07:59:03 +0800
> 
> It works in bash.
> But in emacs, either I use`M-x info' or `C-h C-i',
> it can't display the info page.

First, I assume you meant "C-h i", not "C-h C-i".

Second, what does ``can't display the info page'' mean, exactly?  What
happens after "C-h i"?

> ``man 3 printf" ,  how to do it with info?

There are several ways.  If you are sure you are looking for the C
library function `printf', type "C-h S c-mode RET printf RET".

If you are not sure what `printf' you are looking for, try "M-x
info-apropos RET".

(The above might not work if you are not running Emacs 22.)

> What's better man, woman or info?

Inside Emacs, use Info first, and if you cannot find the documentation
of whatever you are looking for, I suggest to use woman, since it's
more portable across platforms supported by Emacs.

Re: Why I can't use `info' in emacs?

[Ronald]

Eli Zaretskii wrote:
>> From: Ronald <followait@163.com>
>> Date: Fri, 15 Dec 2006 07:59:03 +0800
>>
>> It works in bash.
>> But in emacs, either I use`M-x info' or `C-h C-i',
>> it can't display the info page.
> 
> First, I assume you meant "C-h i", not "C-h C-i".
> 
> Second, what does ``can't display the info page'' mean, exactly?  What
> happens after "C-h i"?
> 
I'd like to see the info page for the word where the point is.
When I type ``C-h C-i" it says there is no info node for that word.
But in bash there is.
I was told to add the path to Info-default-directory-list, but I don't 
know where it is.

``C-h i" works fine.

What I need is very simple, open the info page for the word where the 
point is.

>> ``man 3 printf" ,  how to do it with info?
> 
> There are several ways.  If you are sure you are looking for the C
> library function `printf', type "C-h S c-mode RET printf RET".
> 
> If you are not sure what `printf' you are looking for, try "M-x
> info-apropos RET".
> 
> (The above might not work if you are not running Emacs 22.)
> 
I think the key sequence is too long for convenience.

Re: Why I can't use `info' in emacs?

[Ronald]

Eli Zaretskii wrote:
 >> From: Ronald <followait@163.com>
 >> Date: Fri, 15 Dec 2006 07:59:03 +0800
 >>
 >> It works in bash.
 >> But in emacs, either I use`M-x info' or `C-h C-i',
 >> it can't display the info page.
 >
 > First, I assume you meant "C-h i", not "C-h C-i".
 >
 > Second, what does ``can't display the info page'' mean, exactly?  What
 > happens after "C-h i"?
 >
I'd like to see the info page for the word where the point is.
When I type ``C-h C-i" it says there is no info node for that word.
But in bash there is.
I was told to add the path to Info-default-directory-list, but I don't 
know where it is.

``C-h i" works fine.

What I need is very simple, open the info page for the word where the 
point is.

 >> ``man 3 printf" ,  how to do it with info?
 >
 > There are several ways.  If you are sure you are looking for the C
 > library function `printf', type "C-h S c-mode RET printf RET".
 >
 > If you are not sure what `printf' you are looking for, try "M-x
 > info-apropos RET".
 >
 > (The above might not work if you are not running Emacs 22.)
 >
I think the key sequence is too long for convenience.

Re: Why I can't use `info' in emacs?

[Eli Zaretskii]

> Date: Fri, 15 Dec 2006 17:20:23 +0800
> From: Ronald <followait@163.com>
> CC:  help-gnu-emacs@gnu.org
> > 
> I'd like to see the info page for the word where the point is.
> When I type ``C-h C-i" it says there is no info node for that word.
> But in bash there is.

What version of Emacs do you have?  I assume it's Emacs 21.x, because
in that version `C-h C-i' was running the command info-lookup-symbol,
and it was buggy.  In Emacs 22, info-lookup-symbol is bound to `C-h S', 
and it does work for me in the situation you described (point is on
printf).  Please consider upgrading.

> >> ``man 3 printf" ,  how to do it with info?
> > 
> > There are several ways.  If you are sure you are looking for the C
> > library function `printf', type "C-h S c-mode RET printf RET".
> 
> I think the key sequence is too long for convenience.

Don't be ridiculous, it's exactly 3 characters longer than "man 3
printf".  And if you are already in a buffer whose major mode is C,
and point is on `printf', all you need to type is "C-h S RET", which
is only 3 keystrokes.

Re: Why I can't use `info' in emacs?

[Robert Thorpe]

Ronald wrote:
> > | ``man 3 printf" ,  how to do it with info?
> >
> > You can't.
>
> Take `printf' for example, how to view programmer's doc (not the shell doc)

Use M-x man printf(3)

WoMan gives you a completion list if you press tab.

Re: Why I can't use `info' in emacs?

[Hadron Quark]

Eli Zaretskii <eliz@gnu.org> writes:

>> Date: Fri, 15 Dec 2006 17:20:23 +0800
>> From: Ronald <followait@163.com>
>> CC:  help-gnu-emacs@gnu.org
>> > 
>> I'd like to see the info page for the word where the point is.
>> When I type ``C-h C-i" it says there is no info node for that word.
>> But in bash there is.
>
> What version of Emacs do you have?  I assume it's Emacs 21.x, because
> in that version `C-h C-i' was running the command info-lookup-symbol,
> and it was buggy.  In Emacs 22, info-lookup-symbol is bound to `C-h S', 
> and it does work for me in the situation you described (point is on
> printf).  Please consider upgrading.
>
>> >> ``man 3 printf" ,  how to do it with info?
>> > 
>> > There are several ways.  If you are sure you are looking for the C
>> > library function `printf', type "C-h S c-mode RET printf RET".
>> 
>> I think the key sequence is too long for convenience.
>
> Don't be ridiculous, it's exactly 3 characters longer than "man 3
> printf".  And if you are already in a buffer whose major mode is C,
> and point is on `printf', all you need to type is "C-h S RET", which
> is only 3 keystrokes.

How is one supposed to set this up?

On my emacs-snapshot printf is not a documented symbol. I have

(defun jump-man-page ()
  (interactive)
  (manual-entry (current-word))
  )

assigned to a key in cc-mode



-- 

Re: Why I can't use `info' in emacs?

[Robert Thorpe]

Hadron Quark wrote:
> Eli Zaretskii <eliz@gnu.org> writes:
> >> Date: Fri, 15 Dec 2006 17:20:23 +0800
> >> From: Ronald <followait@163.com>
> >> CC:  help-gnu-emacs@gnu.org
> >> >
> >> I'd like to see the info page for the word where the point is.
> >> When I type ``C-h C-i" it says there is no info node for that word.
> >> But in bash there is.
> >
> > What version of Emacs do you have?  I assume it's Emacs 21.x, because
> > in that version `C-h C-i' was running the command info-lookup-symbol,
> > and it was buggy.  In Emacs 22, info-lookup-symbol is bound to `C-h S',
> > and it does work for me in the situation you described (point is on
> > printf).  Please consider upgrading.
> >
> >> >> ``man 3 printf" ,  how to do it with info?
> >> >
> >> > There are several ways.  If you are sure you are looking for the C
> >> > library function `printf', type "C-h S c-mode RET printf RET".
> >>
> >> I think the key sequence is too long for convenience.
> >
> > Don't be ridiculous, it's exactly 3 characters longer than "man 3
> > printf".  And if you are already in a buffer whose major mode is C,
> > and point is on `printf', all you need to type is "C-h S RET", which
> > is only 3 keystrokes.
>
> How is one supposed to set this up?

This works if you are on a fairly GNUy system.  One that has GNUlibc,
such as a "linux" distribution.  If this is the case then there should
be an info node called libc or glibc.  If that is the case then just
pressing C-h S over a symbol documented in the manual should bring up
that symbols info-page.
Possible reasons why this doesn't work are:-
* Distribution does not set Info paths correctly
* Distribution does not ship with Glibc manual
If either of the above are the case then complain loudly.

This keystroke is C-h C-i in Emacs21 and C-h S in Emacs22.

> On my emacs-snapshot printf is not a documented symbol.

It's not documented by Emacs, it's documented in the Info docs that
come with GLibc.

> I have
>
> (defun jump-man-page ()
>   (interactive)
>   (manual-entry (current-word))
>   )
>
> assigned to a key in cc-mode

As other posters have said C-h S is better, the GNU info pages are
better than their man-pages.

Re: Why I can't use `info' in emacs?

[Hadron Quark]

"Robert Thorpe" <rthorpe@realworldtech.com> writes:

> Hadron Quark wrote:
>> Eli Zaretskii <eliz@gnu.org> writes:
>> >> Date: Fri, 15 Dec 2006 17:20:23 +0800
>> >> From: Ronald <followait@163.com>
>> >> CC:  help-gnu-emacs@gnu.org
>> >> >
>> >> I'd like to see the info page for the word where the point is.
>> >> When I type ``C-h C-i" it says there is no info node for that word.
>> >> But in bash there is.
>> >
>> > What version of Emacs do you have?  I assume it's Emacs 21.x, because
>> > in that version `C-h C-i' was running the command info-lookup-symbol,
>> > and it was buggy.  In Emacs 22, info-lookup-symbol is bound to `C-h S',
>> > and it does work for me in the situation you described (point is on
>> > printf).  Please consider upgrading.
>> >
>> >> >> ``man 3 printf" ,  how to do it with info?
>> >> >
>> >> > There are several ways.  If you are sure you are looking for the C
>> >> > library function `printf', type "C-h S c-mode RET printf RET".
>> >>
>> >> I think the key sequence is too long for convenience.
>> >
>> > Don't be ridiculous, it's exactly 3 characters longer than "man 3
>> > printf".  And if you are already in a buffer whose major mode is C,
>> > and point is on `printf', all you need to type is "C-h S RET", which
>> > is only 3 keystrokes.
>>
>> How is one supposed to set this up?
>
> This works if you are on a fairly GNUy system.  One that has GNUlibc,
> such as a "linux" distribution.  If this is the case then there should
> be an info node called libc or glibc.  If that is the case then just
> pressing C-h S over a symbol documented in the manual should bring up
> that symbols info-page.
> Possible reasons why this doesn't work are:-
> * Distribution does not set Info paths correctly
> * Distribution does not ship with Glibc manual
> If either of the above are the case then complain loudly.
>
> This keystroke is C-h C-i in Emacs21 and C-h S in Emacs22.
>
>> On my emacs-snapshot printf is not a documented symbol.
>
> It's not documented by Emacs, it's documented in the Info docs that
> come with GLibc.
>
>> I have
>>
>> (defun jump-man-page ()
>>   (interactive)
>>   (manual-entry (current-word))
>>   )
>>
>> assigned to a key in cc-mode
>
> As other posters have said C-h S is better, the GNU info pages are
> better than their man-pages.
>

Thanks again Robert. First I heard of all this : when I asked before
people helped me out with the man pages!

I will dig around.

-- 

Re: Why I can't use `info' in emacs?

[Eli Zaretskii]

> From: "Robert Thorpe" <rthorpe@realworldtech.com>
> Date: 15 Dec 2006 04:40:59 -0800
> 
> Ronald wrote:
> > > | ``man 3 printf" ,  how to do it with info?
> > >
> > > You can't.
> >
> > Take `printf' for example, how to view programmer's doc (not the shell doc)
> 
> Use M-x man printf(3)

The OP explicitly wanted "to do it with info", see above.

Re: Why I can't use `info' in emacs?

[Hadron Quark]

"Robert Thorpe" <rthorpe@realworldtech.com> writes:

> It's not documented by Emacs, it's documented in the Info docs that
> come with GLibc.

I installed the glibc info package on my ubuntu system. restarted
emacs. Here are some outputs from the info pages for glibc and the man
pages for printf:

(a) man page using manual-entry(current-word):

,----
| PRINTF(3)                                      Linux Programmer’s Manual                                     PRINTF(3)
| 
| NAME
|        printf, fprintf, sprintf, snprintf, vprintf, vfprintf, vsprintf, vsnprintf - formatted output conversion
| 
| SYNOPSIS
|        #include <stdio.h>
| 
|        int printf(const char *format, ...);
|        int fprintf(FILE *stream, const char *format, ...);
|        int sprintf(char *str, const char *format, ...);
|        int snprintf(char *str, size_t size, const char *format, ...);
| 
|        #include <stdarg.h>
| 
|        int vprintf(const char *format, va_list ap);
|        int vfprintf(FILE *stream, const char *format, va_list ap);
|        int vsprintf(char *str, const char *format, va_list ap);
|        int vsnprintf(char *str, size_t size, const char *format, va_list ap);
| 
| DESCRIPTION
|        The  functions  in  the  printf() family produce output according to a format as described below. The functions
|        printf() and vprintf() write output to stdout, the standard output stream; fprintf() and vfprintf() write  out‐
|        put to the given output stream; sprintf(), snprintf(), vsprintf() and vsnprintf() write to the character string
|        str.
| 
`----

(b) info entry: 

,----
| 12.12.7 Formatted Output Functions
| ----------------------------------
| 
| This section describes how to call `printf' and related functions.
| Prototypes for these functions are in the header file `stdio.h'.
| Because these functions take a variable number of arguments, you _must_
| declare prototypes for them before using them.  Of course, the easiest
| way to make sure you have all the right prototypes is to just include
| `stdio.h'.  
| 
|  -- Function: int printf (const char *TEMPLATE, ...)
|      The `printf' function prints the optional arguments under the
|      control of the template string TEMPLATE to the stream `stdout'.
|      It returns the number of characters printed, or a negative value
|      if there was an output error.
| 
`----


Surely the man pages are superior in this instance for a programmer?

Re: Why I can't use `info' in emacs?

[Robert Thorpe]

Hadron Quark wrote:
> "Robert Thorpe" <rthorpe@realworldtech.com> writes:
>
> > It's not documented by Emacs, it's documented in the Info docs that
> > come with GLibc.
>
> I installed the glibc info package on my ubuntu system. restarted
> emacs. Here are some outputs from the info pages for glibc and the man
> pages for printf:
>
> (a) man page using manual-entry(current-word):
>
> ,----
> | PRINTF(3)                                      Linux Programmer's Manual                                     <snip>
> Surely the man pages are superior in this instance for a programmer?

It depends.  The GLibc manual is odd in that it's maintained in both
TexInfo format and Man format.  The TexInfo manual is used to generate
the HTML manual.  Sometimes the Man is better than the info, often it's
the other way around.

In this case Info returns much less documentation.  However, the info
manual is structured a little differently.  Hit "u" from the node where
you are and you'll see all the other stuff in the same section:-

* Formatted Output Basics     Some examples to get you started.
* Output Conversion Syntax    General syntax of conversion
specifications.
* Table of Output Conversions Summary of output conversions and what
they do.
* Integer Conversions         Details about formatting of integers.
* Floating-Point Conversions  Details about formatting of
floating-point numbers.
* Other Output Conversions    Details about formatting of strings,
characters, pointers, and the like.
* Formatted Output Functions  Descriptions of the actual functions.
* Dynamic Output              Functions that allocate memory for the
output.
* Variable Arguments Output   `vprintf' and friends.
* Parsing a Template String   What kinds of args does a given template
call for?
* Example of Parsing          Sample program using
`parse_printf_format'.

Hit 'u' again and you'll get more info on I/O functions.  The Info
manual explains all sorts of things like customizing printf that the
man-page doesn't cover.

The man-page is quite thorough in this case, but it is a little
confusing in one respect, It says "Linux Programmer's Manual".  I
have no idea why it says this, since printf is provided by Glibc.
Perhaps it dates from the time of Linux 2.1 when Linux had a different
C library.  More likely it's been written by someone in the Linux
project for continuity purposes, because people expect it there from
the days when Linux had it's own Libc.  If you are looking at the same
man page as me, then it documents many printf like functions, but not
quite all of them, not parse_printf_format for example.

Often the best manual depends on the function(!) The person who has
written the code tends to document it well in the manual they
themselves use.

Re: Why I can't use `info' in emacs?

[Hadron Quark]

"Robert Thorpe" <rthorpe@realworldtech.com> writes:

> In this case Info returns much less documentation.  However, the info
> manual is structured a little differently.  Hit "u" from the node where
> you are and you'll see all the other stuff in the same section:-
>
> * Formatted Output Basics     Some examples to get you started.
> * Output Conversion Syntax    General syntax of conversion
> specifications.
> * Table of Output Conversions Summary of output conversions and what
> they do.
> * Integer Conversions         Details about formatting of integers.
> * Floating-Point Conversions  Details about formatting of
> floating-point numbers.
> * Other Output Conversions    Details about formatting of strings,
> characters, pointers, and the like.
> * Formatted Output Functions  Descriptions of the actual functions.
> * Dynamic Output              Functions that allocate memory for the
> output.
> * Variable Arguments Output   `vprintf' and friends.
> * Parsing a Template String   What kinds of args does a given template
> call for?
> * Example of Parsing          Sample program using
> `parse_printf_format'.
>
> Hit 'u' again and you'll get more info on I/O functions.  The Info
> manual explains all sorts of things like customizing printf that the
> man-page doesn't cover.

I can see a reason for both. Thanks for the "info" .. lol.

As an aside, one thing that has really surprised me at the moment though is the lack
of man pages / info pages for the gtk 2.0 libraries - making it
impossible to bring up help in the emacs "IDE".

Re: Why I can't use `info' in emacs?

[Eli Zaretskii]

> From: Hadron Quark <hadronquark@gmail.com>
> Date: Fri, 15 Dec 2006 15:25:55 +0100
> 
> Surely the man pages are superior in this instance for a programmer?

How is the man page superior?

Re: Why I can't use `info' in emacs?

[Hadron Quark]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Hadron Quark <hadronquark@gmail.com>
>> Date: Fri, 15 Dec 2006 15:25:55 +0100
>> 
>> Surely the man pages are superior in this instance for a programmer?
>
> How is the man page superior?
>

Did you look at the excerpts which came up from the context. For a
programmer bringing up the API it is blatantly obvious, in this case,
which first stage info is more useful.

-- 

Re: Why I can't use `info' in emacs?

[Robert Thorpe]

Hadron Quark wrote:
> "Robert Thorpe" <rthorpe@realworldtech.com> writes:
<snip>
> I can see a reason for both. Thanks for the "info" .. lol.
>
> As an aside, one thing that has really surprised me at the moment though is the lack
> of man pages / info pages for the gtk 2.0 libraries - making it
> impossible to bring up help in the emacs "IDE".

Yes.  That is irritating, especially since the docs for the original
GTK did support Info.  Now they only generate DocBook formats.  This
was because of a decision to use a similar sort of comment extraction
system to the one Emacs uses for C-h f, C-h v etc.

Re: Why I can't use `info' in emacs?

[Robert Thorpe]

Hadron Quark wrote:
> Eli Zaretskii <eliz@gnu.org> writes:
>
> >> From: Hadron Quark <hadronquark@gmail.com>
> >> Date: Fri, 15 Dec 2006 15:25:55 +0100
> >>
> >> Surely the man pages are superior in this instance for a programmer?
> >
> > How is the man page superior?
> >
>
> Did you look at the excerpts which came up from the context. For a
> programmer bringing up the API it is blatantly obvious, in this case,
> which first stage info is more useful.

The most common reason I have for looking at API docs is to remind me
of the order of arguments in a function.  Mostly I can remember the
functions purpose.  We're all different.

Re: Why I can't use `info' in emacs?

[Eli Zaretskii]

> From: Hadron Quark <hadronquark@gmail.com>
> Date: Fri, 15 Dec 2006 17:27:23 +0100
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> From: Hadron Quark <hadronquark@gmail.com>
> >> Date: Fri, 15 Dec 2006 15:25:55 +0100
> >> 
> >> Surely the man pages are superior in this instance for a programmer?
> >
> > How is the man page superior?
> >
> 
> Did you look at the excerpts which came up from the context. For a
> programmer bringing up the API it is blatantly obvious, in this case,
> which first stage info is more useful.

I did look at the excerpts.  Perhaps I don't qualify as a
``programmer'', although I'm coding away for more years than I can
remember, but please believe me that it is not obvious to me what you
meant, let alone ``blatantly obvious''.  Please consider explaining
that.

Btw, in case it's unclear, the reason I asked my question is that I'm
trying to figure out what needs to be improved to make the Info system
better suited to programmers' needs, not because I wanted to tease
you.  FWIW, I'm using Info exclusively for many years, and I have yet
to see a single case where man pages are better (except when an Info
manual does not exist).  It could be that the glibc manual needs some
work to make it more useful, but it's hard to guess what to do without
specific details.  For example, what information did you want to find,
and how the Info manual defeated that?

Re: Why I can't use `info' in emacs?

[Hadron Quark]

"Robert Thorpe" <rthorpe@realworldtech.com> writes:

> Hadron Quark wrote:
>> Eli Zaretskii <eliz@gnu.org> writes:
>>
>> >> From: Hadron Quark <hadronquark@gmail.com>
>> >> Date: Fri, 15 Dec 2006 15:25:55 +0100
>> >>
>> >> Surely the man pages are superior in this instance for a programmer?
>> >
>> > How is the man page superior?
>> >
>>
>> Did you look at the excerpts which came up from the context. For a
>> programmer bringing up the API it is blatantly obvious, in this case,
>> which first stage info is more useful.
>
> The most common reason I have for looking at API docs is to remind me
> of the order of arguments in a function.  Mostly I can remember the
> functions purpose.  We're all different.
>

Hence the man page is superior :-;

-- 

Re: Why I can't use `info' in emacs?

[Eli Zaretskii]

> From: Hadron Quark <hadronquark@gmail.com>
> Date: Sat, 16 Dec 2006 20:21:32 +0100
> >
> > The most common reason I have for looking at API docs is to remind me
> > of the order of arguments in a function.  Mostly I can remember the
> > functions purpose.  We're all different.
> >
> 
> Hence the man page is superior :-;

The information about the arguments is there in the Info manual as
well.

Re: Why I can't use `info' in emacs?

[Hadron Quark]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Hadron Quark <hadronquark@gmail.com>
>> Date: Sat, 16 Dec 2006 20:21:32 +0100
>> >
>> > The most common reason I have for looking at API docs is to remind me
>> > of the order of arguments in a function.  Mostly I can remember the
>> > functions purpose.  We're all different.
>> >
>> 
>> Hence the man page is superior :-;
>
> The information about the arguments is there in the Info manual as
> well.
>

Again : Did you *read* the excerpts I posted coming up from the code? As a first
page context help, the man page is superior to the info file node which
first appears. From a programming perspective. Here it is again :

(a) man page using manual-entry(current-word):

,----
| PRINTF(3)                                      Linux Programmer’s Manual                                     PRINTF(3)
| 
| NAME
|        printf, fprintf, sprintf, snprintf, vprintf, vfprintf, vsprintf, vsnprintf - formatted output conversion
| 
| SYNOPSIS
|        #include <stdio.h>
| 
|        int printf(const char *format, ...);
|        int fprintf(FILE *stream, const char *format, ...);
|        int sprintf(char *str, const char *format, ...);
|        int snprintf(char *str, size_t size, const char *format, ...);
| 
|        #include <stdarg.h>
| 
|        int vprintf(const char *format, va_list ap);
|        int vfprintf(FILE *stream, const char *format, va_list ap);
|        int vsprintf(char *str, const char *format, va_list ap);
|        int vsnprintf(char *str, size_t size, const char *format, va_list ap);
| 
| DESCRIPTION
|        The  functions  in  the  printf() family produce output according to a format as described below. The functions
|        printf() and vprintf() write output to stdout, the standard output stream; fprintf() and vfprintf() write  out‐
|        put to the given output stream; sprintf(), snprintf(), vsprintf() and vsnprintf() write to the character string
|        str.
| 
`----

(b) info entry: 

,----
| 12.12.7 Formatted Output Functions
| ----------------------------------
| 
| This section describes how to call `printf' and related functions.
| Prototypes for these functions are in the header file `stdio.h'.
| Because these functions take a variable number of arguments, you _must_
| declare prototypes for them before using them.  Of course, the easiest
| way to make sure you have all the right prototypes is to just include
| `stdio.h'.  
| 
|  -- Function: int printf (const char *TEMPLATE, ...)
|      The `printf' function prints the optional arguments under the
|      control of the template string TEMPLATE to the stream `stdout'.
|      It returns the number of characters printed, or a negative value
|      if there was an output error.
| 
`----



-- 

Re: Why I can't use `info' in emacs?

[Eli Zaretskii]

> From: Hadron Quark <hadronquark@gmail.com>
> Date: Sat, 16 Dec 2006 23:30:08 +0100
> 
> Again : Did you *read* the excerpts I posted coming up from the code? As a first
> page context help, the man page is superior to the info file node which
> first appears. From a programming perspective. Here it is again :

Instead of insisting that the superiority is obvious, why don't you
tell what you, from your programming perspective, expect to find when
you ask the help system about a function?  Then, if that information
is missing from the glibc manual, perhaps some day it will be added.

If you keep insisting that it's obvious, one thing is certain: the
manual will never be changed to your liking.  Maybe that is your
goal...

Re: Why I can't use `info' in emacs?

[Giorgos Keramidas]

On 15 Dec 2006 06:57:13 -0800,
"Robert Thorpe" <rthorpe@realworldtech.com> wrote:
>Hadron Quark wrote:
>>"Robert Thorpe" <rthorpe@realworldtech.com> writes:
>>> It's not documented by Emacs, it's documented in the Info docs that
>>> come with GLibc.
>>
>> I installed the glibc info package on my ubuntu system. restarted
>> emacs. Here are some outputs from the info pages for glibc and the man
>> pages for printf:
>>
>> (a) man page using manual-entry(current-word):
>>
>> ,----
>> | PRINTF(3)    Linux Programmer's Manual    <snip>
>>
>> Surely the man pages are superior in this instance for a programmer?
>
> It depends.  [...]
> The man-page is quite thorough in this case, but it is a little
> confusing in one respect, It says "Linux Programmer's Manual".  I
> have no idea why it says this, since printf is provided by Glibc.

That's because man pages are organized in sections.  The section title
for manpages in section 3 is "Linux Programmer's Manual" on Linux.  On
other systems, section 3 may have a slightly different title.  Here, for
instance, on a FreeBSD system, the title is:

PRINTF(3)             FreeBSD Library Functions Manual            PRINTF(3)

Re: Why I can't use `info' in emacs?

[Robert Thorpe]

Hadron Quark wrote:
> "Robert Thorpe" <rthorpe@realworldtech.com> writes:
> > Hadron Quark wrote:
> >> Eli Zaretskii <eliz@gnu.org> writes:
> >>
> >> >> From: Hadron Quark <hadronquark@gmail.com>
> >> >> Date: Fri, 15 Dec 2006 15:25:55 +0100
> >> >>
> >> >> Surely the man pages are superior in this instance for a programmer?
> >> >
> >> > How is the man page superior?
> >> >
> >>
> >> Did you look at the excerpts which came up from the context. For a
> >> programmer bringing up the API it is blatantly obvious, in this case,
> >> which first stage info is more useful.
> >
> > The most common reason I have for looking at API docs is to remind me
> > of the order of arguments in a function.  Mostly I can remember the
> > functions purpose.  We're all different.
> >
>
> Hence the man page is superior :-;

For this particular purpose both contain the same information.

The Man page contains:-
int printf(const char *format, ...);
And the Info page:-
-- Function: int printf (const char *TEMPLATE, ...)

Re: Why I can't use `info' in emacs?

[Robert Thorpe]

Giorgos Keramidas wrote:
> On 15 Dec 2006 06:57:13 -0800,
> "Robert Thorpe" <rthorpe@realworldtech.com> wrote:
> >Hadron Quark wrote:
> >>"Robert Thorpe" <rthorpe@realworldtech.com> writes:
> >>> It's not documented by Emacs, it's documented in the Info docs that
> >>> come with GLibc.
> >>
> >> I installed the glibc info package on my ubuntu system. restarted
> >> emacs. Here are some outputs from the info pages for glibc and the man
> >> pages for printf:
> >>
> >> (a) man page using manual-entry(current-word):
> >>
> >> ,----
> >> | PRINTF(3)    Linux Programmer's Manual    <snip>
> >>
> >> Surely the man pages are superior in this instance for a programmer?
> >
> > It depends.  [...]
> > The man-page is quite thorough in this case, but it is a little
> > confusing in one respect, It says "Linux Programmer's Manual".  I
> > have no idea why it says this, since printf is provided by Glibc.
>
> That's because man pages are organized in sections.  The section title
> for manpages in section 3 is "Linux Programmer's Manual" on Linux.  On
> other systems, section 3 may have a slightly different title.  Here, for
> instance, on a FreeBSD system, the title is:
>
> PRINTF(3)             FreeBSD Library Functions Manual            PRINTF(3)

I don't agree.  Individual man pages should have titles, not just
sections of the manual.

In the old days when Unix all came from AT&T it made sense if the man
page simply announced the purpose of the section, eg "Unix Library
Function Manual".  This was, I believe the title of section 3 of the
Unix manual.

These days in free *nixes have bits coming from all over the place.
Now it makes sense if the title of the man page reflects the origin of
the command.  In section 3 of the manual I have Perl docs, libc docs
and linux docs.  There's probably some other stuff in there I haven't
mentioned.

The FreeBSD entry is entirely correct, since FreeBSD's libc is
maintained with FreeBSD.

Re: Why I can't use `info' in emacs?

[Hadron Quark]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Hadron Quark <hadronquark@gmail.com>
>> Date: Sat, 16 Dec 2006 23:30:08 +0100
>> 
>> Again : Did you *read* the excerpts I posted coming up from the code? As a first
>> page context help, the man page is superior to the info file node which
>> first appears. From a programming perspective. Here it is again :
>
> Instead of insisting that the superiority is obvious, why don't you
> tell what you, from your programming perspective, expect to find when
> you ask the help system about a function?  Then, if that information
> is missing from the glibc manual, perhaps some day it will be added.
>
> If you keep insisting that it's obvious, one thing is certain: the
> manual will never be changed to your liking.  Maybe that is your
> goal...

I would have thought that me stating I wanted context help from the code
would make it obvious if you look at the two excerpts. 

One gives the function API and the overview, the other doesnt.

Re: Why I can't use `info' in emacs?

[Hadron Quark]

"Robert Thorpe" <rthorpe@realworldtech.com> writes:

> Hadron Quark wrote:
>> "Robert Thorpe" <rthorpe@realworldtech.com> writes:
>> > Hadron Quark wrote:
>> >> Eli Zaretskii <eliz@gnu.org> writes:
>> >>
>> >> >> From: Hadron Quark <hadronquark@gmail.com>
>> >> >> Date: Fri, 15 Dec 2006 15:25:55 +0100
>> >> >>
>> >> >> Surely the man pages are superior in this instance for a programmer?
>> >> >
>> >> > How is the man page superior?
>> >> >
>> >>
>> >> Did you look at the excerpts which came up from the context. For a
>> >> programmer bringing up the API it is blatantly obvious, in this case,
>> >> which first stage info is more useful.
>> >
>> > The most common reason I have for looking at API docs is to remind me
>> > of the order of arguments in a function.  Mostly I can remember the
>> > functions purpose.  We're all different.
>> >
>>
>> Hence the man page is superior :-;
>
> For this particular purpose both contain the same information.
>
> The Man page contains:-
> int printf(const char *format, ...);
> And the Info page:-
> -- Function: int printf (const char *TEMPLATE, ...)
>

No they dont. The man page is the complete man page for printf.

My examples were just the top few lines.

-- 

Re: Why I can't use `info' in emacs?

[Robert Thorpe]

Hadron Quark wrote:
> "Robert Thorpe" <rthorpe@realworldtech.com> writes:
> > Hadron Quark wrote:
> >> "Robert Thorpe" <rthorpe@realworldtech.com> writes:
> >> > Hadron Quark wrote:
> >> >> Eli Zaretskii <eliz@gnu.org> writes:
> >> >>
> >> >> >> From: Hadron Quark <hadronquark@gmail.com>
> >> >> >> Date: Fri, 15 Dec 2006 15:25:55 +0100
> >> >> >>
> >> >> >> Surely the man pages are superior in this instance for a programmer?
> >> >> >
> >> >> > How is the man page superior?
> >> >> >
> >> >>
> >> >> Did you look at the excerpts which came up from the context. For a
> >> >> programmer bringing up the API it is blatantly obvious, in this case,
> >> >> which first stage info is more useful.
> >> >
> >> > The most common reason I have for looking at API docs is to remind me
> >> > of the order of arguments in a function.  Mostly I can remember the
> >> > functions purpose.  We're all different.
> >> >
> >>
> >> Hence the man page is superior :-;
> >
> > For this particular purpose both contain the same information.
> >
> > The Man page contains:-
> > int printf(const char *format, ...);
> > And the Info page:-
> > -- Function: int printf (const char *TEMPLATE, ...)
> >
>
> No they dont.

Speaking of my own usage of docs I said:-
"The most common reason I have for looking at API docs is to remind me
of the order of arguments in a function."
This was the topic under discussion.  From that point of view both the
man page and info node are similar since they give the prototype of the
function in the first few lines of the response.

> The man page is the complete man page for printf.

Not really.  The man page documents only a few of the capabilities of
printf and friends that are specified by standards bodies.  If you want
to read about all their capabilities you must use the info pages or
HTML pages.

Re: Why I can't use `info' in emacs?

[Hadron Quark]

"Robert Thorpe" <rthorpe@realworldtech.com> writes:

> Hadron Quark wrote:
>> "Robert Thorpe" <rthorpe@realworldtech.com> writes:
>> > Hadron Quark wrote:
>> >> "Robert Thorpe" <rthorpe@realworldtech.com> writes:
>> >> > Hadron Quark wrote:
>> >> >> Eli Zaretskii <eliz@gnu.org> writes:
>> >> >>
>> >> >> >> From: Hadron Quark <hadronquark@gmail.com>
>> >> >> >> Date: Fri, 15 Dec 2006 15:25:55 +0100
>> >> >> >>
>> >> >> >> Surely the man pages are superior in this instance for a programmer?
>> >> >> >
>> >> >> > How is the man page superior?
>> >> >> >
>> >> >>
>> >> >> Did you look at the excerpts which came up from the context. For a
>> >> >> programmer bringing up the API it is blatantly obvious, in this case,
>> >> >> which first stage info is more useful.
>> >> >
>> >> > The most common reason I have for looking at API docs is to remind me
>> >> > of the order of arguments in a function.  Mostly I can remember the
>> >> > functions purpose.  We're all different.
>> >> >
>> >>
>> >> Hence the man page is superior :-;
>> >
>> > For this particular purpose both contain the same information.
>> >
>> > The Man page contains:-
>> > int printf(const char *format, ...);
>> > And the Info page:-
>> > -- Function: int printf (const char *TEMPLATE, ...)
>> >
>>
>> No they dont.
>
> Speaking of my own usage of docs I said:-
> "The most common reason I have for looking at API docs is to remind me
> of the order of arguments in a function."
> This was the topic under discussion.  From that point of view both the
> man page and info node are similar since they give the prototype of the
> function in the first few lines of the response.
>
>> The man page is the complete man page for printf.
>
> Not really.  The man page documents only a few of the capabilities of
> printf and friends that are specified by standards bodies.  If you want
> to read about all their capabilities you must use the info pages or
> HTML pages.
>

if you think that first level "info" page which comes up is more
applicable for a programmer then fine. Personally I dont. man pages are
the de-facto linux standard with info coming second. In this case the
man page which comes up in emacs has far more pertinent information than
the info page which comes up. For me. Maybe we have to beg to differ.

Re: Why I can't use `info' in emacs?

[Robert Thorpe]

Hadron Quark wrote:
> "Robert Thorpe" <rthorpe@realworldtech.com> writes:
> if you think that first level "info" page which comes up is more
> applicable for a programmer then fine. Personally I dont. man pages are
> the de-facto linux standard with info coming second. In this case the
> man page which comes up in emacs has far more pertinent information than
> the info page which comes up. For me. Maybe we have to beg to differ.

I think so.
Personally, I want complete and accurate documentation of functions
preferably written by their authors.  That's why for glibc functions I
use info (and for linux functions I use man).  I don't mind
occasionally having to type "u" to get to the higher level when I'm
reading docs on functions of some particular class.

I'd also point out that Vim in the de-facto standard editor for Linux ;)

Re: Why I can't use `info' in emacs?

[Eli Zaretskii]

> From: Hadron Quark <hadronquark@gmail.com>
> Date: Mon, 18 Dec 2006 13:54:54 +0100
> 
> One gives the function API and the overview, the other doesnt.

Would a cross-reference to the section with the rest of the
information help?

Re: Why I can't use `info' in emacs?

[Giorgos Keramidas]

On 18 Dec 2006 03:51:43 -0800,
"Robert Thorpe" <rthorpe@realworldtech.com> wrote:
>Giorgos Keramidas wrote:
>>On 15 Dec 2006 06:57:13 -0800,
>>"Robert Thorpe" <rthorpe@realworldtech.com> wrote:
>>>> ,----
>>>> | PRINTF(3)    Linux Programmer's Manual    <snip>
>>>>
>>>> Surely the man pages are superior in this instance for a programmer?
>>>
>>> It depends.  [...]
>>> The man-page is quite thorough in this case, but it is a little
>>> confusing in one respect, It says "Linux Programmer's Manual".  I
>>> have no idea why it says this, since printf is provided by Glibc.
>>
>> That's because man pages are organized in sections.  The section title
>> for manpages in section 3 is "Linux Programmer's Manual" on Linux.  On
>> other systems, section 3 may have a slightly different title.  Here, for
>> instance, on a FreeBSD system, the title is:
>>
>> PRINTF(3)             FreeBSD Library Functions Manual            PRINTF(3)
>
> I don't agree.  Individual man pages should have titles, not just
> sections of the manual.

I think there may have been a moderate amount of confusion here.  I thought
you didn't know why the header says "Linux Programmer's Manual", not that
you knew all about manpage sections but you disagreed with the content of
the text.

The most commonly used packages for writing manpages are "man" and "mandoc"
these days.  They both provide ways to set the manpage header to a
package-specific string, so if you don't like the Glibc manpage headers,
then maybe it's a good idea to contact teh Glibc authors :)

> In the old days when Unix all came from AT&T it made sense if the man
> page simply announced the purpose of the section, eg "Unix Library
> Function Manual".  This was, I believe the title of section 3 of the
> Unix manual.
>
> These days in free *nixes have bits coming from all over the place.
> Now it makes sense if the title of the man page reflects the origin of
> the command.  In section 3 of the manual I have Perl docs, libc docs
> and linux docs.  There's probably some other stuff in there I haven't
> mentioned.

Yep.  Agreed 100%.

> The FreeBSD entry is entirely correct, since FreeBSD's libc is
> maintained with FreeBSD.

Since it is up to the manpage author to set the header to something like
"GNU C Library Functions Manual", or even "SDL API Reference", even in
FreeBSD some manpages have the 'wrong' header, by your criteria :-/

Re: Why I can't use `info' in emacs?

[Robert Thorpe]

Giorgos Keramidas wrote:
> On 18 Dec 2006 03:51:43 -0800,
> "Robert Thorpe" <rthorpe@realworldtech.com> wrote:
> >Giorgos Keramidas wrote:
> >>On 15 Dec 2006 06:57:13 -0800,
> >>"Robert Thorpe" <rthorpe@realworldtech.com> wrote:
> >>>> ,----
> >>>> | PRINTF(3)    Linux Programmer's Manual    <snip>
> >>>>
> >>>> Surely the man pages are superior in this instance for a programmer?
> >>>
> >>> It depends.  [...]
> >>> The man-page is quite thorough in this case, but it is a little
> >>> confusing in one respect, It says "Linux Programmer's Manual".  I
> >>> have no idea why it says this, since printf is provided by Glibc.
> >>
> >> That's because man pages are organized in sections.  The section title
> >> for manpages in section 3 is "Linux Programmer's Manual" on Linux.  On
> >> other systems, section 3 may have a slightly different title.  Here, for
> >> instance, on a FreeBSD system, the title is:
> >>
> >> PRINTF(3)             FreeBSD Library Functions Manual            PRINTF(3)
> >
> > I don't agree.  Individual man pages should have titles, not just
> > sections of the manual.
>
> I think there may have been a moderate amount of confusion here.  I thought
> you didn't know why the header says "Linux Programmer's Manual", not that
> you knew all about manpage sections but you disagreed with the content of
> the text.

Fair point.

> The most commonly used packages for writing manpages are "man" and "mandoc"
> these days.  They both provide ways to set the manpage header to a
> package-specific string, so if you don't like the Glibc manpage headers,
> then maybe it's a good idea to contact teh Glibc authors :)

Glibc doesn't contain man-pages.  The man pages were written mainly by
the people who document the linux kernel, that's why it says "Linux
Programmer's Manual".  This is an overhang from the days when Linux
used Libc6 which was maintained by Linux kernel folks.  It's confusing
because they don't maintain that part of the system anymore.

> Yep.  Agreed 100%.
>
> > The FreeBSD entry is entirely correct, since FreeBSD's libc is
> > maintained with FreeBSD.
>
> Since it is up to the manpage author to set the header to something like
> "GNU C Library Functions Manual", or even "SDL API Reference", even in
> FreeBSD some manpages have the 'wrong' header, by your criteria :-/

Yep.  It's a fairly common problem, not restricted to manpages either.