<<< Date Index >>>     <<< Thread Index >>>

Re: Searching in the index is not documented - tentative patch.



Hi, everybody!

On Thu, Aug 17, 2006 at 06:29:49PM +0200, Rado S wrote:
> =- Alan Mackenzie wrote on Thu 17.Aug'06 at 16:14:08 +0100 -=

> > As a beginner, I didn't know where to look. Despite searching
> > long and hard in the manual for the answers to these questions,
> > I didn't find them. {...}
> > Hence, I'm suggesting to the Mutt team, in a respectful fashion,
> > that it could be helpful to enhance the manual.

> Good docs are generally underappreciated to work on.
> Working on documentation is not rewarding (enough) for coders, they
> prefer to work on technical/ functional improvement rather than
> docs. As long as there are such things to fix, this won't change,
> and there is a lot of technical stuff to fix for mutt.
>  That's because unlike improving code -- where you immediately see
> the technical benefit when the changes work and people who asked for
> it to be implemented report back -- improved docs go unnoticed since
> you hardly can see a benefit there: if it helped, people are happy
> but quiet about it.
>  Coders more easily see the need to improve code than docs, since
> they use the code themselves, but they know their stuff so don't
> need any docs at all. As long as the stuff is _somehow_ documented,
> all is fine for them. Plus, it takes _a lot_ more time to improve
> whole docs than a small piece of code.

I am a developer, and I've spent ~200 hours knocking "my" manual into
shape.

[ .... ]

OK, here's a tentative patch for the manual.  Please bear in mind that
I've not used DocBook before, so it most likely contains syntax errors
and other solecisms.

#########################################################################

*** manual.xml.3.26.head        2006-08-17 19:13:08.000000000 +0100
--- manual.xml.acm.head 2006-08-17 21:54:24.760889320 +0100
***************
*** 394,399 ****
--- 394,409 ----
  
  </para>
  
+ <para>
+ Each of the search commands takes an argument string.  If this is a simple
+ string, the search interprets it as a regular expression, and searches through
+ the current mailbox for the next/previous mail whose Subject: or From: header
+ matches it.  (This is the default setup - to configure it, see <link
+ linkend="simple_search">&dollar;simple&lowbar;search</link>.)  If, on the
+ other hand, the argument string contains a '~', it is interpreted as a pattern
+ to be sought (see <link linkend="patterns">&dollar;Patterns</link>).
+ </para>
+ 
  <sect3>
  <title>Status Flags</title>
  
***************
*** 3500,3508 ****
  <title>Patterns</title>
  
  <para>
! Many of Mutt's commands allow you to specify a pattern to match
! (limit, tag-pattern, delete-pattern, etc.).  There are several ways to select
! messages:
  </para>
  
  <para>
--- 3510,3518 ----
  <title>Patterns</title>
  
  <para>
! Many of Mutt's commands allow you to specify a pattern to match (limit,
! tag-pattern, delete-pattern, search (in the index), etc.).  There are several
! ways to select messages:
  </para>
  
  <para>

#########################################################################

-- 
Alan Mackenzie (Munich, Germany)