unofficial mirror of emacs-devel@gnu.org 
 help / color / mirror / code / Atom feed
From: Richard Stallman <rms@gnu.org>
Cc: juri@jurta.org, emacs-devel@gnu.org, monnier@iro.umontreal.ca,
	karl@freefriends.org
Subject: Re: Documentation for "Clone Buffers" (corrected version)
Date: Sun, 21 Mar 2004 00:00:27 -0500	[thread overview]
Message-ID: <E1B4v4V-0000IM-8S@fencepost.gnu.org> (raw)
In-Reply-To: <3405-Sat20Mar2004160433+0200-eliz@elta.co.il>

    > Thus my original idea (although I guess I did not fully explain it):
    > 1have one subnode of dir for commands, one for library functions, one for
    > file formats, etc., analogous to the man sections.  Keep the top level
    > dir itself for the manuals as a whole.

I agree that we should find a way to collect commands, collect library
functions for C, collect file formats, etc.  However, having a node in
`dir' with a list of commands, and another with a list of library
functions, etc., seems like an inconvenient way to do it.

The feature we want is to have an index of all commands.  We could do
this by creating a node which lists all commands, combining info from
various manuals.  But we could also make the combination virtually.
Manuals could identify themselves as containing relevant entries for
a certain area, and info could search the index of each manual.

So imagine that there is a node in `dir' that has a menu which
contains all the manuals that describe commands.  When you ask to
search for a command `foo', info would find this node, find all the
manuals it points to, then search the index of each manual for `foo'.

Perhaps the existing `@dircategory' command usable for manuals to
insert themselves into these nodes when appropriate.  Karl, will it
work, or does it need some change?

In the Unix Manual, "library function" implicit means "C library
function".  GNU users use many languages; we cannot assume that
"function" means "C function".  So I think that we should have
a "manual section" for each language, which would list library
functions for that language.  You would want to do something like

  info C strcpy

to look up the C function strcpy.  `C' would specify the "section" of
the manual to look in; it would equivalent to `man 2' and `man 3'.



The other issue is precisely how to search each manual.  Searching the
index is useful in some cases, but which index?  The Emacs Manual has
a "Command Index", but searching in that index for `emacs' won't find
it.

This same example also illustrates the common case of a manual
that documentsjust a small number of commands (or whatever).
It would be silly for the Emacs manual to have an index
of shell commands, because it defines only one.

So a manual that adds itself to the node for "commands" needs to 
specify how to search that manual for a command.  There should be
at least two ways to do it:

1. Specify an index to search for a desired command name.

2. Specify specific command names documented in the manual.

We could do this with stylized menu items in the Top node.
A menu item like this

   * `emacs' Shell Command: Entering Emacs.

could specify where to find the specific command `emacs',
and a menu item like this

   * Index of Shell Commands: NODE NAME.

could specify to look for a shell command in index NODE NAME.

Likewise we could have

   * JPEG file format: NODE NAME.

or

   * Index of C Functions: NODE NAME.


    That would work, but do we really have the power to enforce such an
    organization of DIR?

Not to worry.  If we implement this and support it with GNU manuals,
people will find it useful and will adapt their manuals to fit it.

  reply	other threads:[~2004-03-21  5:00 UTC|newest]

Thread overview: 144+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
     [not found] <E1Ax1Br-0005C3-OL@fencepost.gnu.org>
2004-03-05 10:05 ` Documentation for "Clone Buffers" (corrected version) Alan Mackenzie
2004-03-09 15:40   ` David Kastrup
2004-03-10 11:29     ` Alan Mackenzie
2004-03-12  5:12       ` Luc Teirlinck
2004-03-12 16:34         ` Karl Berry
2004-03-14  2:32           ` Luc Teirlinck
2004-03-14  7:36             ` Eli Zaretskii
2004-03-14 18:17               ` Luc Teirlinck
2004-03-14 18:24                 ` Eli Zaretskii
2004-03-14 18:37                   ` Luc Teirlinck
2004-03-14 19:58                 ` Karl Berry
2004-03-15  3:14                   ` Luc Teirlinck
2004-03-15  6:46                     ` Eli Zaretskii
2004-03-15 23:35                       ` Luc Teirlinck
2004-03-16  5:37                         ` Eli Zaretskii
2004-03-15 23:41                       ` Luc Teirlinck
2004-03-16 12:09                   ` Richard Stallman
2004-03-14 13:39             ` Karl Berry
2004-03-14 16:57               ` Eli Zaretskii
2004-03-15  4:57             ` Richard Stallman
2004-03-12  5:22       ` Luc Teirlinck
2004-03-12  1:24     ` Luc Teirlinck
2004-03-15  5:05       ` Juri Linkov
2004-03-15 13:27         ` Stefan Monnier
2004-03-15 17:06           ` Miles Bader
2004-03-15 17:08           ` David Kastrup
2004-03-16  7:02           ` Juri Linkov
2004-03-12  2:45     ` Miles Bader
2004-03-09 23:40   ` Alex Schroeder
2004-03-12 10:57     ` Kai Grossjohann
2004-04-25  4:32       ` Juri Linkov
2004-04-25 13:37         ` Karl Berry
2004-06-17 16:33         ` C-h C-i Juri Linkov
2004-06-17 10:29           ` Karl Fogel
2004-06-18  7:16             ` Juri Linkov
2004-06-18  8:18               ` Karl Fogel
2004-06-18 14:55                 ` Juri Linkov
2004-06-18 12:33                   ` Karl Fogel
2004-06-18 19:00                     ` Juri Linkov
2004-06-19  3:19               ` Richard Stallman
2004-06-19  0:19                 ` Karl Fogel
2004-06-20  0:42                   ` Juanma Barranquero
2004-06-20  1:17                     ` Miles Bader
2004-06-20  1:29                       ` Juanma Barranquero
2004-06-20  1:51                         ` One possible bug-tracking system Karl Fogel
2004-06-20 13:23                           ` Alex Schroeder
2004-06-20 12:42                             ` Karl Fogel
2004-06-20 19:39                               ` Luc Teirlinck
2004-06-20 13:38                                 ` Karl Fogel
2004-06-21  9:31                                   ` Richard Stallman
2004-06-21  9:41                                     ` Juanma Barranquero
2004-06-22 23:17                                       ` Richard Stallman
2004-06-21 12:02                                     ` Arne Jørgensen
2004-06-22 23:16                                       ` Richard Stallman
2004-06-21 18:26                                     ` Karl Fogel
2004-06-21 22:28                                       ` Juri Linkov
2004-06-22  2:00                                       ` Marcelo Toledo
2004-06-22 23:17                                       ` Richard Stallman
2004-06-20 19:18                   ` C-h C-i Richard Stallman
2004-06-20 20:47                     ` Luc Teirlinck
2004-06-20 23:15                       ` Juri Linkov
2004-06-20 23:37                         ` Luc Teirlinck
2004-06-22  2:49                         ` Richard Stallman
2004-06-22  2:48                       ` Richard Stallman
2004-06-21  5:20                     ` Eli Zaretskii
2004-06-22  2:49                       ` Richard Stallman
2004-06-22  5:20                         ` Eli Zaretskii
2004-06-26 10:41                         ` Eli Zaretskii
2004-06-22  2:04                     ` Luc Teirlinck
2004-06-22 23:17                       ` Richard Stallman
2004-06-18 21:51           ` Richard Stallman
2004-03-14 21:55     ` Documentation for "Clone Buffers" (corrected version) Stefan Monnier
2004-03-16 12:09       ` Richard Stallman
2004-03-15  6:28     ` Juri Linkov
2004-03-16 19:03       ` Richard Stallman
2004-03-10  3:37   ` Miles Bader
2004-03-10 18:45   ` Richard Stallman
2004-03-10 18:45   ` Richard Stallman
2004-03-11 14:55     ` Alan Mackenzie
2004-03-14  5:53       ` Eli Zaretskii
2004-03-14  9:48         ` David Kastrup
2004-03-14 16:50           ` Eli Zaretskii
2004-03-16 12:09             ` Richard Stallman
2004-03-15 18:18           ` Matthew Mundell
2004-03-15  5:18         ` Juri Linkov
2004-03-15  6:52           ` Eli Zaretskii
2004-03-15 13:34             ` Stefan Monnier
2004-03-15 14:35               ` Luc Teirlinck
2004-03-15 20:03                 ` Eli Zaretskii
2004-03-15 20:40                   ` Luc Teirlinck
2004-03-15 19:55               ` Eli Zaretskii
2004-03-16 19:02               ` Richard Stallman
2004-03-16  7:05             ` Juri Linkov
2004-03-16 19:43               ` Eli Zaretskii
2004-03-18  7:21                 ` Juri Linkov
2004-03-19  5:01                 ` Richard Stallman
2004-03-18 18:37               ` Karl Berry
2004-03-18 18:53                 ` Stefan Monnier
2004-03-19 14:11                   ` Karl Berry
2004-03-19 17:13                     ` Stefan Monnier
2004-03-21  4:58                       ` Richard Stallman
2004-03-19 14:59                   ` Eli Zaretskii
2004-03-19 17:31                     ` Stefan Monnier
2004-03-19 17:47                       ` Karl Berry
2004-03-20 14:04                         ` Eli Zaretskii
2004-03-21  5:00                           ` Richard Stallman [this message]
2004-03-21  6:19                             ` Eli Zaretskii
2004-03-22  5:24                               ` Richard Stallman
2004-03-22  6:40                                 ` Eli Zaretskii
2004-03-22  5:24                               ` Richard Stallman
2004-03-22  6:33                                 ` Eli Zaretskii
2004-03-23  3:04                                   ` Richard Stallman
2004-03-21 17:18                             ` Karl Berry
2004-03-22  5:25                               ` Richard Stallman
2004-03-22  7:26                                 ` Eli Zaretskii
2004-03-23  3:04                                   ` Richard Stallman
2004-03-23  3:04                                   ` Richard Stallman
2004-03-23  6:10                                     ` Eli Zaretskii
2004-03-24  5:34                                       ` Richard Stallman
2004-03-22 16:13                           ` Stefan Monnier
2004-03-22 16:10                         ` Stefan Monnier
2004-03-23  0:20                           ` Kim F. Storm
2004-03-23  2:26                             ` Stefan Monnier
2004-03-23  6:19                               ` Eli Zaretskii
2004-03-20 14:37                       ` Eli Zaretskii
2004-03-20 18:01                   ` Richard Stallman
2004-03-19 15:01                 ` Eli Zaretskii
2004-03-19 15:15                   ` Karl Berry
2004-03-20 14:07                     ` Eli Zaretskii
2004-03-20 14:15                       ` Karl Berry
2004-03-20 15:15                         ` Eli Zaretskii
2004-03-20 19:27                           ` Miles Bader
2004-03-21  5:55                             ` Eli Zaretskii
2004-03-22  5:25                               ` Richard Stallman
2004-03-22  6:12                                 ` Eli Zaretskii
2004-03-21  5:00                           ` Richard Stallman
2004-03-21  6:28                             ` Eli Zaretskii
2004-03-20 18:01                 ` Richard Stallman
2004-03-21  5:51                   ` Eli Zaretskii
2004-03-22  5:25                     ` Richard Stallman
2004-03-22  6:29                       ` Eli Zaretskii
2004-03-15  4:56       ` Richard Stallman
2004-03-10 18:45   ` Richard Stallman
2004-02-25 10:15 Alan Mackenzie

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: https://www.gnu.org/software/emacs/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=E1B4v4V-0000IM-8S@fencepost.gnu.org \
    --to=rms@gnu.org \
    --cc=emacs-devel@gnu.org \
    --cc=juri@jurta.org \
    --cc=karl@freefriends.org \
    --cc=monnier@iro.umontreal.ca \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).