Re: example queries for nnir

[Harry Putnam <reader@newsguy.com>]

Kai.Grossjohann@CS.Uni-Dortmund.DE (Kai Großjohann) writes:


[...]

> > 
> > So, there is no way to search just the body by itself?
> 
> This depends on the format file.  In a `region...end' stanza, the BOTH
> keyword means that the words are index both in the given field and in
> the global field.  If you put LOCAL there, the words are only put into
> the given field, and not in the global field.

Unless there is the possibility of a `body' field, how can the above
allow a body only search?

> 
> Btw, I think `stemming SOUNDEX' is not a working combination.  Use
> just `SOUNDEX' instead.

OK .. thanks

> > [...] snipped good examples
> > 
> > 
> > > > ;; . . . . . . . . . . . . . . . . . . . . . . . . . . . . The
> > > > ;; second variable to set is `nnir-search-engine'.  Choose one of the
> > > > ;; engines listed in `nnir-engines'.
> > > 
> > > I have now included an explicit pointer to the variable
> > > documentation.  I have also tried to beef up the documentation for
> > > nnir-engines.  Did it help?  New version on ftp server,
> > > ftp://ls6-ftp.cs.uni-dortmund.de/pub/src/emacs/
> > 
> > Checking that version, I see what is changed but it still doesn't make
> > it clear how using the engines in that alist might look when included
> > in nnir variables.
> 
> Are you saying that (setq nnir-search-engine 'wais) and (setq
> nnir-search-engine 'imap) is not sufficient and that I should include
> the full list of allowed symbols?

Very sorry Kai, but I thought we were discussing the opening comments
in nnir.el.  Which should probably include the examples you refer to
above. Those that  appear in that actual code as documnet strings.  I had not
noticed those examples which probably means many new users would not either.

So no, I'm not saying all possible examples need to be shown only that
the examples should appear with the discussion in opening comments as well.

> 
> > Going form this:
> >   nnir-engines's value is 
> >   ((glimpse nnir-run-glimpse
> >             ((group . "Group spec: ")))
> >    (wais nnir-run-waissearch nil)
> >    (excite nnir-run-excite-search nil)
> >    (imap nnir-run-imap nil))
> > 
> > to this:
> > (setq nnir-search-engine 'glimpse)
> > 
> > Is not apparent from nnir.el  comments, unless you know a little lisp.
> 
> Hm.  Okay.  Hm.  What can I do?  List the allowed symbols for the
> default value in the doc string?  Tell the user what to type to learn
> which symbols are allowed?

Probably best to include the examples in the opening comments where
the variable are first mentioned, *and* instruct how to see the doc
string documentation.  Sorry if this seems like over kill but it seems
to me this should all be included where the discussion of nnir
varilables takes place.

> > Including some simple examples of actual settings might be more
> > usefull.
> 
> I have tried to do this in the doc string for nnir-engines.

Yes I see that now.. I had missed it in my previous post.

> > Indicating which are default setting would help too. Nnir.el does
> > this for the some of the variables pertaining to glimpse and wais
> > already.
> 
> If you don't change a variable, type C-h v to get the default value.
> If you change a variable, M-x find-variable RET might help.

Yes, for experienced emacs users this is common knowledge but you
seemed to feel it was necessary to mention some defaults in the
opening nnir.el comments like:

   ;; . . . . . . . . . . . . . . . . . . . . . . . . The variable
   ;; `nnir-wais-remove-prefix' should contain a regex matching exactly
   ;; this prefix.  It defaults to `$HOME/Mail/' (note the trailing
   ;; slash).

and:

  ;; . . . . . . . . . . . . . . . . . .The `nnir-glimpse-home'
  ;; variable should be set to the value of the `-H' option which allows
  ;; one to search this Glimpse index.  I have indexed my whole home
  ;; directory with Glimpse, so I assume a default of `$HOME'.

I think this is a good practice and was only suggesting that any of
the variables discussed in comments should also have any defaults
pointed out.

> > ## variable nnir-mail-backend example settings:
> > 
> > ## If gnus-secondary-select-methods is set to only one of either nnml
> > ## or nnmh backend then nnir will default to that backend (Kai, is
> > ## this true?)
> 
> No, the default value for nnir-mail-backend is (nnml ""), regardless
> of the gnus-secondary-select-methods setting.
> 
> Should I change the default value to be (car
> gnus-secondary-select-methods)? 

Err no.... probably not since that would probably give confusing
results to people with nnfolder or whatever.  Probably sufficient to
mention that `nnml ""' is the default.  Also it is clearly pointed out
in nnir.el comments that nnml and nnmh are the only backends supported.

> 
> > ## If more than one mail backend is used then nnir-mail-backend can be 
> > ## set like this (must be nnml or nnmh):
> > ## (setq nnir-mail-backend  '(BACKEND "NAME"))  <==(probably not accurate)
> > ## (setq nnir-mail-backend '(nnml "my-server"))
> 
> Also see the documentation for nnir-mail-backend which says that it
> might be best to get the value from gnus-secondary-select-methods.
> 
> You must include _all_ server parameters.
> 
> > ## variable nnir-search-engines example settings:
> > ## (setq nnir-search-engine 'BACKEND)
> > ## (setq nnir-search-engine 'glimpse)
> > ## (setq nnir-search-engine 'wais)
> 
> I have included `wais' and `imap' examples in the documentation for
> nnir-engines. 
> 
> > Similar examples following the sections on glimpse and wais, in there
> > `setq' format for inclusion in gnus would be nice too:
> > Something like:
> > 
> > (setq nnir-glimpse-remove-prefix "/PATH/DIRECTORY/")
> > 
> > or
> > 
> > (setq nnir-glimpse-home "/PATH/DIRECTORY/"/
> 
> I have now tried to do this.  What do you think about the new version?

I don't see that in the opening comments.  The variable documentation
is superb now.  I may be all wet thinking these examplse should also
appear there but it seems to follow if it makes sense to have the
discussion in the opening comments.  Not a big issue I guess.