Re: MH-E manual update

[Bill Wohler]

Eli Zaretskii <address@hidden> wrote:

> > 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.

WOW! I never knew about the `i' command. That's awesome! Yes, since I
never knew about the `i' command, I was thinking about the user looking
at the index directly, whether it be in Info or HTML or PDF.

> OTOH, with your entries, typing "i Emacs TAB" will show a very long list
> of entries, which is not too good, I think.

I think it's WONDERFUL!

>                                              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".

Since the audience of the MH-E user includes someone who does not
know Emacs (see Info node (mh-e) Preface), having an index section that
starts with Emacs, is useful since they might not remember the term
"point" but would know that it is an Emacs' thingy.

Don't laugh. *I* used MH-E before I used Emacs. This was in 1985.

> > > 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...

...which needs to be updated manually and easily gets out of date.
No, thanks.

>   @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?

Just to double-check what I think I once saw, I added two index entries
"@cindex foo" in a node and ran makeinfo (version 4.8) and texi2pdf
(version (GNU Texinfo 4.8) 1.34), and noted that there was only one
entry in each of the info, HTML, and PDF indexes. Try it!

> > 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.
> ...

My question was independent of your suggestions. It's something I've
been thinking about for some time. Sorry if that wasn't clear.

Let's say I have two paragraphs in a chapter that mention
`image-load-path'. Conventional wisdom puts the "@vindex
image-load-path" entry before the first paragraph that mentions it. The
problem with this is that when I later move the first paragraph with
index entry to another node, the old node now lacks an index entry. Or,
if I were to move the second paragraph to another node, the new node now
lacks an index entry. By just always adding an index entry, you save
time in asking yourself if you need an index entry or not in the first
place (just add it), and you eliminate the chance that the editor will
forget to update the index appropriately.

> > 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.

Thanks for the feedback!

-- 
Bill Wohler <address@hidden>  http://www.newt.com/wohler/  GnuPG ID:610BD9AD
Maintainer of comp.mail.mh FAQ and MH-E. Vote Libertarian!
If you're passed on the right, you're in the wrong lane.