Mail Archives: djgpp-workers/2002/03/03/13:50:53
At 01:29 PM 3/3/02 +0200, Eli Zaretskii wrote:
>On Sat, 2 Mar 2002, Peter J. Farley III wrote:
>
>> The problem is that FOOb.zip as a section name does not tell me
>> anything about what it is the programs in that package do.
>
>We could add some info in parentheses, like this:
>
> From gccNNNb.zip (The GNU Compiler Collection):
How is that so different from my suggestion:
GNU C programming documentation @strong{From gccNNNb.zip}
or this one:
DJGPP: Basic Documentation @strong{From djdevNNN.zip}
(Other than the fact that I didn't use "GNU Compiler Collection", which
could easily be done. I would have no problem with that.)
>> >Well, can you explain what help do you need, and how does the
>> >current shape of DIR prevent you from finding the info?
<Snipped>
>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.
However, all of this philosophy has gotten *way* OT for
djgpp-workers. I propose that we take this part of the discussion over
to the bug-texinfo list.
>> In the interim, if it will help you more, I can just "fix up" the
>> current dir.txi with some text re-arrangement.
>
>There's no rush, so I'm hesitatnt to ask you to do something that
>might be thrown away. I think it's best to decide what we want
first,
>and only then invest the effort to do it.
Well, let me put together a "dir.txi" as I suggested, and then tell me
what you think of it.
>> In particular, the fileutils, shellutils and textutils sections can
>> and probably should be positioned *before* the "Miscellaneous"
>> section.
>
>"Miscellaneous" should go last, by its very definition: it includes
>everything that doesn't have a better classification. We should make
>sure that no important packages end up there, though; if they do,
it's
>probably a sign that our classification needs work ;-).
Agreed. I will work on a simpler set of changes and get back to the
list when I have something.
---------------------------------------------------------
Peter J. Farley III (pjfarley AT dorsai DOT org)
- Raw text -