From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: rcirc manual Date: Fri, 13 Jan 2006 13:21:56 +0200 Message-ID: References: <87ek3hgunn.fsf@killalla.dreaming> Reply-To: Eli Zaretskii NNTP-Posting-Host: main.gmane.org X-Trace: sea.gmane.org 1137161511 10811 80.91.229.2 (13 Jan 2006 14:11:51 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Fri, 13 Jan 2006 14:11:51 +0000 (UTC) Cc: rcyeske@gmail.com, kensanata@gmail.com, emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Fri Jan 13 15:11:46 2006 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by ciao.gmane.org with esmtp (Exim 4.43) id 1ExPeD-00068D-Vf for ged-emacs-devel@m.gmane.org; Fri, 13 Jan 2006 15:11:22 +0100 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1ExPgM-0007Xq-32 for ged-emacs-devel@m.gmane.org; Fri, 13 Jan 2006 09:13:34 -0500 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1ExNkQ-00046c-FC for emacs-devel@gnu.org; Fri, 13 Jan 2006 07:09:38 -0500 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1ExNd7-0002IO-Ep for emacs-devel@gnu.org; Fri, 13 Jan 2006 07:02:09 -0500 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1ExN3m-0007Vr-4a for emacs-devel@gnu.org; Fri, 13 Jan 2006 06:25:35 -0500 Original-Received: from [192.114.186.20] (helo=nitzan.inter.net.il) by monty-python.gnu.org with esmtp (Exim 4.34) id 1ExN6X-0007iJ-M7; Fri, 13 Jan 2006 06:28:26 -0500 Original-Received: from HOME-C4E4A596F7 (IGLD-84-228-246-138.inter.net.il [84.228.246.138]) by nitzan.inter.net.il (MOS 3.7.3-GA) with ESMTP id CLM13856 (AUTH halo1); Fri, 13 Jan 2006 13:21:52 +0200 (IST) Original-To: bkhl@member.fsf.org (=?utf-8?Q?Bj=C3=B6rn_Lindstr=C3=B6m?=) In-reply-to: <87ek3hgunn.fsf@killalla.dreaming> (bkhl@member.fsf.org) X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:48987 Archived-At: > 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.