Re: rcirc manual

[Eli Zaretskii]

> From: address@hidden (=?utf-8?Q?Bj=C3=B6rn_Lindstr=C3=B6m?=)
> Date: Mon, 09 Jan 2006 18:47:56 +0100
> Cc: address@hidden, address@hidden
> 
> Here's a manual for the recently included rcirc IRC client.

Thanks!

> Suggestions for improvements are much welcomed.

Below.

> @setfilename rcirc.info

Manuals bundled with Emacs need to say this:

  @setfilename ../info/rcirc

to produce the Info manual in the `info' subdirectory.  We also
usually drop the .info extension, to minimize file-name related
problems in restricted environments.

> rcirc is an Emacs IRC client.

I suggest to use @code{rcorc} throughout the manual, so that the name
of the package stands out of the other text.

> * Skipping @code{/away} messages using handlers::

Using @-commands in node names is an absolute no-no in Texinfo.  Look
at the Index node, and you will see that the name of this node loses
the `..' markup (produced from @code) in the Index references.  This
means that index entries in this node will not work.  You need to
remove the @code markup from the node name and from all its references
in all the menus and cross-references.

> Since this is so common, you can use TAB to do nick completion.

I'd suggest @kbd{TAB} here, since this is what the user types.

> This is the reference section of the manual. It is not complete. For
> complete listings of rcirc features, use Emacs built-in documentation.

Please make sure there are two blanks after each dot that ends a
sentence.

> IRC buffers are constantly growing.  If you want to see as much as
> possible at all times, you would want the prompt at the bottom of the
> window when possible.  The following snippet uses a local value for
> @code{scroll-conservatively} to achieve this:

Options and features explained elsewhere in the Emacs documentation
should have an @xref cross-reference leading to them.  Suppose that
whoever reads this does not know what scroll-conservatively is--we
won't want them to waste their time searching the entire Emacs
documentation suite, right?

The same comment is relevant to Flyspell you mention.

Finally, I'd suggest to invest some more effort in indexing.  The
current indexing covers the commands and options, but it Needs More
Work (tm) in the concept index area.  To add more helpful indexing,
re-read the manual, and for each paragraph, ask yourself what phrases
would the reader think about if she wanted to find this specific
information.  Then add @cindex entries for those phrases.

For example, here:

> @item C-c C-r
> @kindex C-c C-r
> @cindex /nick
> This changes your nick to some other name.  Your nick must be unique
> across the network.  Most networks don't allow too many nick changes in
> quick succession, and have restrictions on the valid characters in nick
> names. (Also @code{/nick alex-test})

I'd add 2 entries:

  @cindex change nick
  @cindex nick, how to change

because, if I were to look for a way to change my nick, these are the
phrases I'd think about.

When done in this way, an index will help people use the manual as a
reference, when they need to quickly find a specific piece of
information without wading through the whole document.

> @node Reference, Hacking and Tweaking, Basic Usage, Top
> @chapter Reference
> @cindex reference

This index entry is too general to be useful.  Reference to what?

> @node rcirc commands, Useful IRC commands, Reference, Reference
> @section rcirc commands
> @cindex commands

Too general.  A better index entry would be

  @cindex rcirc commands

> ignoring. All messages by ignored nicks are -- you guessed it --

You want an em-dash here, so you should use ---, three dashes in a
row, not two.

> @node Useful IRC commands, Configuration, rcirc commands, Reference
> @section Useful IRC commands
> @cindex irc commands
> @cindex commands

First, you already had a "@cindex commands" before.  Having multiple
index entries which have the same names is not a very good idea, since
the reader will not easily know which entry to choose.  It is better
to qualify each one of such entries with some additional info.  For
example:

  @cindex commands, frequently-used

However, in this case, just removing this entry is good enough, since
the other one, @cindex irc commands, does the job.

> @node Configuration, , Useful IRC commands, Reference
> @section Configuration
> @cindex configuration

Again, this index entry is too general.  "configuring rcirc" would be
better.  I'd also add @cindex rcirc options or some such.

> @node Hacking and Tweaking, Key Index, Reference, Top
> @chapter Hacking and Tweaking
> @cindex hacking and tweaking
> 
> Here are some examples of stuff you can do to configure rcirc.

This chapter is nice, but without good indexing for each trick,
there's no hope that users will ever be able to find this information
when they most need it, i.e. in a hurry.

> @cindex defining commands
> @cindex commands

Again, the second index entry is redundant and should be removed.