X-Authentication-Warning: delorie.com: mailnull set sender to djgpp-workers-bounces using -f Message-Id: <5.1.0.14.2.20020303135231.02754840@mail.dorsai.org> X-Sender: pjfarley AT mail DOT dorsai DOT org X-Mailer: QUALCOMM Windows Eudora Version 5.1 Date: Sun, 03 Mar 2002 13:53:38 -0500 To: djgpp-workers AT delorie DOT com From: "Peter J. Farley III" Subject: Re: Restructured dir.txi -- please review and comment Cc: Eli Zaretskii Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii"; format=flowed Reply-To: djgpp-workers AT delorie DOT com 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? >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)