[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: MH-E manual update

From: Eli Zaretskii
Subject: Re: MH-E manual update
Date: Sun, 12 Mar 2006 00:10:00 +0200

> cc: address@hidden, address@hidden
> Comments: In-reply-to Eli Zaretskii <address@hidden>
>    message dated "Sat, 11 Mar 2006 16:30:14 +0200."
> Date: Sat, 11 Mar 2006 12:08:10 -0800
> From: Bill Wohler <address@hidden>
> > Some indexing commands need work, IMHO.  Here's one example:
> > 
> >     @cindex Emacs, mark
> >     @cindex Emacs, point
> >     @cindex Emacs, region
> > 
> > It is not useful to have several index entries all starting with the
> > same string and pointing to the same page.  I'd change this to
> > 
> >     @cindex Emacs mark, point and region
> > 
> > Actually, it might be better yet to reverse the parts of the index
> > entries for the individual terms:
> > 
> >     @cindex mark, in Emacs
> >     @cindex point, in Emacs
> >     @cindex region, in Emacs
> > 
> > and then you can discard the entries without ", in Emacs" altogether.
> I disagree. You can't look at this example in isolation. If you're in
> the index with a lot of other "Emacs" entries, you might not find the
> "region" entry using your suggested entry since it would sorted under
> "m".

Sorry, I don't understand.  My last suggestion was to remove the
entries that begin with "Emacs, " altogether, so how are the other
"Emacs" entries relevant?

Anyway, it sounds like you are thinking about a user who looks at the
printed version, while I think about someone who looks at the on-line
Info version.  In the latter case, typing "i Emacs RET" will
(eventually) get us to the above entries as well, so nothing is lost.
OTOH, with your entries, typing "i Emacs TAB" will show a very long list
of entries, which is not too good, I think.  In particular, a reader
who wants to find the description of point is more likely to type
"i point TAB" or "i point RET" than "i Emacs, point".

> > Here's another similar example:
> > 
> >     @cindex @samp{Draft-Folder:} MH profile component
> >     @cindex @samp{Path:} MH profile component
> >     @cindex @samp{Previous-Sequence:} MH profile component
> >     @cindex @samp{Unseen-Sequence:} MH profile component
> >     @cindex MH profile component, @samp{Draft-Folder:}
> >     @cindex MH profile component, @samp{Path:}
> >     @cindex MH profile component, @samp{Previous-Sequence:}
> >     @cindex MH profile component, @samp{Unseen-Sequence:}
> > 
> > Again, I'd modify the first 4 slightly, like this:
> > 
> >     @cindex @samp{Draft-Folder:}, MH profile component
> >     @cindex @samp{Path:}, MH profile component
> >     @cindex @samp{Previous-Sequence:}, MH profile component
> >     @cindex @samp{Unseen-Sequence:}, MH profile component
> > 
> > and drop the other 4.
> I disagree, but for a different reason. The user might know that he's
> looking for an "MH profile component" but can't quite remember the name.

That's why I suggested an entry for "MH profile component".  With that
problem out of your way, you don't need this redundancy.

> This indexing technique provides a nice quick-reference table.

Index is not the proper vehicle for quick-reference tables.  If you
want a quick reference, add a short section that summarizes these
commands/options, and have an index entry that points to it:

  @cindex MH profile components, quick reference

> Now makeinfo ensures there is only entry per node

?? Perhaps there's a Texinfo feature I'm not aware of--could you show
this at work?

> so I thought it would
> be a good idea to add appropriate index entries to each paragraph,
> independent of the context. That way, if you move the paragraph, the
> index entries go with it. Thoughts?

I didn't suggest to limit yourself to a single entry per node.  I
suggested not to have several entries that coincide in too many
initial characters.  The reason is that it makes TAB-completion less
efficient in the `i' command.  The `i' command is the key to using the
manual as a reference, so anything that gets in the way of it is
annoying when you just need to find that one piece of information.

> Question: Cross-references with five arguments are preceded by
> "section" in printed output (texi2pdf), but not in info output. Where
> there is a URL to the same document, I insert a @uref in @ifhtml. I've
> been inserting the word "section" before the @uref to be consistent with
> the printed manual, but now I'm thinking I should just drop the word
> "section" to be consistent with Info and let @uref do what it wants to
> do. Thoughts?

I agree that dropping the "section" part is a good idea.

reply via email to

[Prev in Thread] Current Thread [Next in Thread]