rcirc manual

rcirc manual

[Björn Lindström]

[-- Attachment #1: Type: text/plain, Size: 435 bytes --]

Here's a manual for the recently included rcirc IRC client.

The responsible parties are

Alex Schroeder
Björn Lindström (me)

Alex is already an Emacs developer, and I have just sent a request for a
form to assign@gnu.org.

I hope that my first attempt at Texinfo isn't too awful, and that it can
be included in Emacs as soon as the paperwork is done.

Suggestions for improvements are much welcomed.

Here it is:


[-- Attachment #2: rcirc manual --]
[-- Type: application/x-texinfo, Size: 17915 bytes --]

[-- Attachment #3: Type: text/plain, Size: 142 bytes --]

_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-devel

Re: rcirc manual

[Eli Zaretskii]

> From: bkhl@member.fsf.org (=?utf-8?Q?Bj=C3=B6rn_Lindstr=C3=B6m?=)
> Date: Mon, 09 Jan 2006 18:47:56 +0100
> Cc: kensanata@gmail.com, rcyeske@gmail.com
> 
> 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.

Re: rcirc manual

[Alex Schroeder]

Thanks for the feedback on the manual, Eli.

As for the em dash suggestion: Is there a convention or tradition for
the GNU manuals to prefer em dashes?  I'm reading The Elements of
Typographical Style by Robert Bringhurst, at the moment.  On p 80 he
says: "The em dash is the nineteenth-century standard, still
prescribed in many editorial style books, but the em dash is too long
for use with the best text faces.  [...] Used as a phrase marker --
thus -- the en dash is set with a normal word space either side."  I
think in European typography in general, em dashes are rarely used.

Re: rcirc manual

[Eli Zaretskii]

> Date: Fri, 13 Jan 2006 15:10:13 +0100
> From: Alex Schroeder <kensanata@gmail.com>
> 
> Thanks for the feedback on the manual, Eli.

You're welcome.

> As for the em dash suggestion: Is there a convention or tradition for
> the GNU manuals to prefer em dashes?

What would you use instead? en-dash?  The Texinfo manual says that
en-dash is used in numerical ranges, which is not what we want here.

And yes, GNU manuals use em-dash, although I don't know whether this
is mandatory.  The Texinfo manual, which is a de-facto standard for
GNU manuals, says to use em-dash.

Re: rcirc manual

[Alex Schroeder]

> What would you use instead? en-dash?  The Texinfo manual says that
> en-dash is used in numerical ranges, which is not what we want here.

Yeah, I would use SPC en dash SPC, or SPC -- SPC in texinfo.  But
using em dash is fine with me as well, if that is the recommendation
for the GNU project.  I was just curious because I had recently read
the Bringhurst book which said that using em dash in this situation
was "old school".

Re: rcirc manual

[Thien-Thi Nguyen]

Eli Zaretskii <eliz@gnu.org> writes:

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

i also see @key{TAB} in several places in the other .texi files,
at least an order of magnitude more frequently, too.

thi

Re: rcirc manual

[Eli Zaretskii]

> Cc: bkhl@member.fsf.org (=?iso-8859-1?q?Bj=F6rn_Lindstr=F6m?=), 
>   rcyeske@gmail.com,
> 	  kensanata@gmail.com,  emacs-devel@gnu.org
> From: Thien-Thi Nguyen <ttn@gnu.org>
> Date: 13 Jan 2006 10:48:42 -0500
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > I'd suggest @kbd{TAB} here, since this is what the user types.
> 
> i also see @key{TAB} in several places in the other .texi files,
> at least an order of magnitude more frequently, too.

@key{TAB} is typeset to show an image of a key on a keyboard.  I think
it is not the right markup in this case, because this manual does not
talk about keys, it talks about typing a TAB.

Re: rcirc manual

[Robert J. Chassell]

    @key{TAB} is typeset to show an image of a key on a keyboard.  I
    think it is not the right markup in this case, because this manual
    does not talk about keys, it talks about typing a TAB.

>From the Texinfo Manual:

  (texinfo)kbd

    Use the `@kbd' command for characters of input to be typed by users.
    For example, to refer to the characters `M-a', write:

         @kbd{M-a}

    and to refer to the characters `M-x shell', write:

         @kbd{M-x shell}

  (texinfo)key

    Use the `@key' command for the conventional name for a key on a
    keyboard, as in:

         @key{RET}

      You can use the `@key' command within the argument of an `@kbd'
    command when the sequence of characters to be typed includes one or
    more keys that are described by name.

      For example, to produce `C-x <ESC>' you would type:

         @kbd{C-x @key{ESC}}

-- 
    Robert J. Chassell                         
    bob@rattlesnake.com                         GnuPG Key ID: 004B4AC8
    http://www.rattlesnake.com                  http://www.teak.cc

Re: rcirc manual

[Eli Zaretskii]

> Date: Fri, 13 Jan 2006 22:16:23 +0000 (UTC)
> From: "Robert J. Chassell" <bob@rattlesnake.com>
> 
>     @key{TAB} is typeset to show an image of a key on a keyboard.  I
>     think it is not the right markup in this case, because this manual
>     does not talk about keys, it talks about typing a TAB.
> 
> >From the Texinfo Manual:

Bob, I know what the Texinfo manual says about this issue, I just
think it's not 100% clear what it means in practice.  For example, you
could use either @kbd{M-@key{x}} or @kbd{M-x} (since `x' ``describes a
key by name''), but the Texinfo manual doesn't touch this dilemma.

Over the years, I formed a personal opinion about this, based on the
way @key typesets its argument in print, and that opinion was what I
wrote: @key is appropriate when talking about keys on the keyboard,
like in the Emacs manual chapter which explains the
Backspace/Delete/DEL issue or in the "Inserting Text" section that
explains the basics.  Everywhere else, with rare exceptions, I think
the effect of @key is not what you want; in particular @kbd{M-@key{x}}
looks ugly.

So, in the situation like the one which led to this discussion, if the
text is something like "press the TAB key", then @key{TAB} is the
right markup, but if the text says "you can use TAB for completion",
I'd use @kbd{TAB}.

Re: rcirc manual

[Robert J. Chassell]

   >     @key{TAB} is typeset to show an image of a key on a keyboard.  I
   >     think it is not the right markup in this case, because this manual
   >     does not talk about keys, it talks about typing a TAB.

        Use the `@kbd' command for characters of input to be typed by
        users. ...

        Use the `@key' command for the conventional name for a key on
        a keyboard ...

   Bob, I know what the Texinfo manual says about this issue, I just
   think it's not 100% clear what it means in practice.  For example, you
   could use either @kbd{M-@key{x}} or @kbd{M-x} (since `x' ``describes a
   key by name''), but the Texinfo manual doesn't touch this dilemma.

My keyboard has a key labelled "Tab" but conventionally, its input can
be sent either by pressing that key or by pressing C-i.  So it seems
to be that in the question of the rcirc manual, @kbd{TAB} makes most
sense.

   ... @key is appropriate when talking about keys on the keyboard,
   like in the Emacs manual chapter which explains the
   Backspace/Delete/DEL issue ...

Yes, I agree.

   I think the effect of @key is not what you want; in particular
   @kbd{M-@key{x}} looks ugly.

I just tested the example, @kbd{C-x @key{ESC}}, in Texinfo.  (No one
that I know would write @kbd{M-@key{x}}.  Instead, he or she would
write either @kbd{M-x} or @key{M-x}.)  For @kbd{C-x @key{ESC}}, both
the Info and the DVI outputs look fine to me.  I particularly like
this output since it tells me, perhaps wrongly, that I am supposed to
press the <ESC> key and not C-[.

   ... if the text is something like "press the TAB key", then
   @key{TAB} is the right markup, but if the text says "you can use
   TAB for completion", I'd use @kbd{TAB}.

Yes.  I agree.  Of course, everyone must check lest someone say "press
the TAB key" when he or she really means "you can use TAB ...", but
that is a different issue.

-- 
    Robert J. Chassell                         
    bob@rattlesnake.com                         GnuPG Key ID: 004B4AC8
    http://www.rattlesnake.com                  http://www.teak.cc

Re: rcirc manual

[Eli Zaretskii]

> Date: Sat, 14 Jan 2006 12:20:30 +0000 (UTC)
> From: "Robert J. Chassell" <bob@rattlesnake.com>
> CC: karl@freefriends.org, emacs-devel@gnu.org
> 
>    I think the effect of @key is not what you want; in particular
>    @kbd{M-@key{x}} looks ugly.
> 
> (No one that I know would write @kbd{M-@key{x}}.  Instead, he or she
> would write either @kbd{M-x} or @key{M-x}.)

AFAIU, @key{M-x} is wrong, since there's no key labeled "M-x".

> Yes.  I agree.  Of course, everyone must check lest someone say "press
> the TAB key" when he or she really means "you can use TAB ...", but
> that is a different issue.

If there's _any_ justification for using @key outside the keyboard
description, it's to make a point that "C-x ESC" does not mean one
must type "C-x E S C", i.e. type the literal characters E, S, and C.
I don't think there could be such confusion in the phrase "you can use
TAB".

Re: rcirc manual

[Richard M. Stallman]

    As for the em dash suggestion: Is there a convention or tradition for
    the GNU manuals to prefer em dashes?

We use em dashes following generally TeX recommendations.
I'd rather not consider the question of changing this practice.

Re: rcirc manual

[Robert J. Chassell]

    AFAIU, @key{M-x} is wrong, since there's no key labeled "M-x".

Ah ... I think of this as pressing the Meta key and the `X' key
simultaneously.  Thus, the Texinfo Manual does talk of these
instances:

    (texinfo)key 

        Use the `@key' command for the conventional name for a key on
        a keyboard ...

However, this terminology may be confusing.  Some people refer to a
`keychord' when they speak of C-x or M-C-f.  Perhaps the Texinfo node
should be changed to `for a key or keychord' rather than simply `for a
key'.

However, the word `key' does have an established meaning.  When I run
`describe-bindings' in this *mail* buffer, `C-x' is labeled `key' and
`Prefix Command' is labeled `binding'.

Perhaps the phrase `keychord' should be used occasionally, as in
(eintr)Note for Novices

    Sometimes a combination like this is called a keychord, since it
    is similar to the way you play a chord on a piano.

But it seems to me that most of the time, the Texinfo Manual should
follow the regular meaning of `key'.

-- 
    Robert J. Chassell                         
    bob@rattlesnake.com                         GnuPG Key ID: 004B4AC8
    http://www.rattlesnake.com                  http://www.teak.cc

Re: rcirc manual

[Richard M. Stallman]

      For example, you
    could use either @kbd{M-@key{x}} or @kbd{M-x} (since `x' ``describes a
    key by name''), but the Texinfo manual doesn't touch this dilemma.

For key names that are spelled out, such as TAB, always use @key.
That includes @kbd{M-@key{TAB}}.  You will see that in the Emacs
manual.

There is an exception for index entries.

Re: rcirc manual

[Eli Zaretskii]

> From: "Richard M. Stallman" <rms@gnu.org>
> CC: bob@rattlesnake.com, karl@freefriends.org, emacs-devel@gnu.org
> Date: Sun, 15 Jan 2006 02:49:56 -0500
> 
>       For example, you
>     could use either @kbd{M-@key{x}} or @kbd{M-x} (since `x' ``describes a
>     key by name''), but the Texinfo manual doesn't touch this dilemma.
> 
> For key names that are spelled out, such as TAB, always use @key.
> That includes @kbd{M-@key{TAB}}.  You will see that in the Emacs
> manual.

That's mostly true, but the manual also has @kbd{TAB} and @kbd{C-c TAB},
for example.

In any case, the explanation in the Texinfo manual should be more
clear on this, IMHO.  It should explain what keys are suitable for
@key, and why.

Re: rcirc manual

[Karl Berry]

    In any case, the explanation in the Texinfo manual should be more
    clear on this, IMHO.  It should explain what keys are suitable for
    @key, and why.

Here is what the `key' node says now.  Documentation improvements are
always welcome, of course.  I'm not too clear myself on exactly how to
make it better.


@node key
@subsection @code{@@key}@{@var{key-name}@}
@findex key

Use the @code{@@key} command for the conventional name for a key on a
keyboard, as in:

@example
@@key@{RET@}
@end example

You can use the @code{@@key} command within the argument of an
@code{@@kbd} command when the sequence of characters to be typed
includes one or more keys that are described by name.

[...]

There are subtleties to handling words like `meta' or `ctrl' that are
names of modifier keys.  When mentioning a character in which the
modifier key is used, such as @kbd{Meta-a}, use the @code{@@kbd} command
alone; do not use the @code{@@key} command; but when you are referring
to the modifier key in isolation, use the @code{@@key} command.  For
example, write @samp{@@kbd@{Meta-a@}} to produce @kbd{Meta-a} and
@samp{@@key@{META@}} to produce @key{META}.

Re: rcirc manual

[Robert J. Chassell]

   In any case, the explanation in the Texinfo manual should be more
   clear on this, IMHO.  It should explain what keys are suitable for
   @key, and why.

Yes.  In the past I thought the explanation was clear enough, but I'm wrong.
Eli is right.

-- 
    Robert J. Chassell                         
    bob@rattlesnake.com                         GnuPG Key ID: 004B4AC8
    http://www.rattlesnake.com                  http://www.teak.cc

Re: rcirc manual

[Richard M. Stallman]

@key should be used for an individual key on the keyboard,
whenever you refer to it.  It should not be used for "keychords".

Thus, the correct way to refer to typing TAB while holding down META
is @kbd{M-@key{TAB}}.  And the way to refer in the text to typing just
TAB is _always_ with @key{TAB}.

Karl, if this isn't clear in the Texinfo manual, could you clarify it?

Re: rcirc manual

[Eli Zaretskii]

> Date: Sun, 15 Jan 2006 16:23:45 -0600
> From: karl@freefriends.org (Karl Berry)
> Cc: rms@gnu.org, bob@rattlesnake.com, emacs-devel@gnu.org
> 
> @node key
> @subsection @code{@@key}@{@var{key-name}@}
> @findex key
> 
> Use the @code{@@key} command for the conventional name for a key on a
> keyboard, as in:
> 
> @example
> @@key@{RET@}
> @end example
> 
> You can use the @code{@@key} command within the argument of an
> @code{@@kbd} command when the sequence of characters to be typed
> includes one or more keys that are described by name.
> 
> [...]

This still doesn't spell out what I think it should: that @key is for
keys whose names are more than 1 character long.  And the reason for
that is to avoid the user confusion, since @kbd{RET} _could_ be
interpreted as @kbd{R E T}.  There's no such confusion in the
single-character key case.

Re: rcirc manual

[Richard M. Stallman]

    That's mostly true, but the manual also has @kbd{TAB} and @kbd{C-c TAB},
    for example.

All the occurrences of @kbd{TAB} should be @key{TAB}, except for
this one

   vip.texi:1571:@kindex 011 @kbd{TAB} (@code{indent-for-tab-command})

which should be just TAB (we don't use @key in index entries,
and @kbd inside @kindex is redundant).

Could you fix them?

Both occurrences of @kbd{C-c TAB} should be @kbd{C-c @key{TAB}}.
Would you please fix them?

Re: rcirc manual

[Eli Zaretskii]

> From: "Richard M. Stallman" <rms@gnu.org>
> CC: bob@rattlesnake.com, karl@freefriends.org, emacs-devel@gnu.org
> Date: Mon, 16 Jan 2006 09:15:26 -0500
> 
>     That's mostly true, but the manual also has @kbd{TAB} and @kbd{C-c TAB},
>     for example.
> 
> All the occurrences of @kbd{TAB} should be @key{TAB}, except for
> this one
> 
>    vip.texi:1571:@kindex 011 @kbd{TAB} (@code{indent-for-tab-command})
> 
> which should be just TAB (we don't use @key in index entries,
> and @kbd inside @kindex is redundant).
> 
> Could you fix them?
> 
> Both occurrences of @kbd{C-c TAB} should be @kbd{C-c @key{TAB}}.
> Would you please fix them?

Done.

Re: rcirc manual

[Alex Schroeder]

[-- Attachment #1: Type: text/plain, Size: 96 bytes --]

I've updated the rcirc manual according to Eli's suggestions and added
a lot of index entries.


[-- Attachment #2: rcirc.texi --]
[-- Type: application/texinfo, Size: 21329 bytes --]

[-- Attachment #3: Type: text/plain, Size: 142 bytes --]

_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-devel

Re: rcirc manual

[Eli Zaretskii]

> From: Alex Schroeder <alex@gnu.org>
> Date: Mon, 23 Jan 2006 01:09:17 +0100
> 
> I've updated the rcirc manual according to Eli's suggestions and added
> a lot of index entries.

Thanks, I installed it in CVS.