Discussion on the structure and purpose of /info/dir

[Peter J. Farley III]

Hi all,

This is a continuation of a discussion I have been having with Eli 
Zaretskii on the purpose and structure of the "/info/dir" file.  I am 
repeating the relevant last part of the discussion so others can chip 
in if they choose.

The context was a discussion on the djgpp-workers list of the 
"/info/dir" file distributed with the DJGPP GNU implementation.

My basic argument is that "/info/dir" is insufficient to the needs of 
either new users or experts when the person invoking info does not know 
in advance the name of the utility they need to use to accomplish some 
task.  I make a suggestion below on what structure *would* satisfy 
those needs, one that has broad, general entries at the start, 
functional breakdowns of the available utilities in the middle, and an 
alphabetical list at the end.  I also suggest that a concept index is 
not out of order for "/info/dir".

Opinions and comments welcome.

Prior discussion:

>> >Well, can you explain what help do you need, and how does the
>> >current shape of DIR prevent you from finding the info?
>
>> The problem is that the organization of the sections fails to 
enable
>> info users to find a utility whose name they do not know, much less 

>> which package it might be contained in.  I believe that a set of
>> categorical sections, in *addition* to an alphabetical section for
>> those who know the name already, is an invaluable aid when one
>> consults info to *find* the utility to accomplish a task.
>
>> As I have been writing this reply, I realized that what I think I
>> would like to see would be something that "/info/dir" is not 
intended
>> to be in its current incarnation
>
>Exactly. DIR is just a menu; menus in Info are not supposed to be
>used for searching the docs efficiently.
>
>Did you ever try "info --apropos SUBJECT"?  It's a bit slow, but
>that's the way you are supposed to look for solutions to problems for 

>which you don't know what packages deal with them.

I never used --apropos before.  So I just tried it, to see if it would 
find the textutil "cut" program.  I used the phrases "cutting text", 
"deleting text" and "selecting text".  You are right, it is somewhat 
slow, but it also fails to find "cut" for any of those phrases:

M:\>info --apropos="cutting text"
info: No available info files have "cutting text" in their indices.

M:\>info --apropos="deleting text"
info: No available info files have "deleting text" in their indices.

M:\>info --apropos="selecting text"
info: No available info files have "selecting text" in their indices.

Now, I realize these failures are because the indices in the underlying 
info files don't have any of those phrases in them, and the indices are 
all that info has to work with.  Better indices would yield better 
results.

But do you see why frustration can easily set in?  This is why I must 
disagree with the premise that "/info/dir" is "just a menu".  This is 
the place where a person starts to look for information that they need. 
It should be much more than "just a menu".  At the very least, it 
should be a very *structured* menu, with what journalism students are 
taught to call the "inverted pyramid" shape: The most general and broad 
information at the top, with more details in the middle parts and the 
most detail at the end.  This is how many reference books are 
organized, because it works.  People can find what they need in 
incremental steps, and can drill down to as much detail as they need.

And I think the idea of a "concept index" for "/info/dir" is not out of 
place. Why shouldn't someone looking for a way to delete certain 
amounts of text from each line of a file have an easier way to find the 
"cut" program?

That is what I think will help both newbies and experts alike. It 
probably requires adding multiple copies of menu entries from each 
package to both the "middle" or functional category section and to the 
"index" or "Individual utilities"/"Miscellaneous" sections, and that 
means more work in each individual package on the contents of the docs, 
which traditionally get done last and least.
---------------------------------------------------------
Peter J. Farley III (address@hidden)