Sorry for jumping into a discussion so late. It's not like I know anything. Eli Zaretskii wrote: >>From: David Kastrup >>Date: 20 May 2004 12:57:11 +0200 >> >> >> >>>A tool such as the one being discussed needs mostly small chinks of >>>plain text interspersed with hyperlinks, something for which >>>Customize (and indeed even Help functions) already have the >>>necessary infrastructure, or at least large parts of it. >>> >>> >>Small? No. An assistant has to _explain_ things, and the ways in >>which they are related. >> >> > >In my experience, long explanations are never read. People nowadays >seem to have no patience for that. That's why tutorials for setting >up software are out and FAQs are in. > > They also require a modicum of literacy to write. > > >>Isolated customization strings don't do that. >> >> > >I didn't say isolated strings. Writing a 10-sentence explanation for >a specific aspect of something doesn't require something as elaborate >as Texinfo. > > I would really hate to see the information separated physically from the code! That's a guarantee one of them will be wrong. Having gotten the negative stuff out of the way, however; I thing better formatting capabilities for DOC strings would be great - as would some form of internationalization. A "pre-processor" like JavaDoc might be very cool. Of course, I am not at this time volunteering! To say that @code{custom} needs work is almost a tautology. But most intelligent folk are rather afraid of it, it seems. Where it does not exist today, there should probably be a "setup" section for each @code{info} topic. Now, a corellation between that text and the related customization settings code -- think "link" like a Note: -- that would be nice too! > > >>You don't get a coherent explanation and layout of what to do in what >>order and what influences what. You get a twisty little maze of >>crosslinks with pieces of information scattered around, and the >>coherent ideas of the design having no place to be sitting. >> >> > >The, IMHO, challenge is to organize those pieces of information in a >way that in every specific case we only display the text that explains >what the user currently cares about. For example, when I need to set >up a port for some service, I don't want to hear a lecture about >TCP/IP and ports in general, just clear and practical suggestions for >coming up with the port number for that specific service. > > > >>That's not what an assistant is supposed to do: an assistant is >>concerned with setting up a package, not with customizing a single >>variable once you have found out that you might want to customize >>_that_ variable. >> >> > <> > Again, the challenge IMHO is to break a complex issue into a sequence > of well-defined short help messages, and a framework that guides the > user thru that sequence. No one will ever read a 10-page explanation > just to set up a package (well, perhaps except you and me). -- <>David A. Cobb, Software Engineer, Public Access Advocate <><>"By God's Grace, I am a Christian man; by my actions a great sinner." -- The Way of a Pilgrim: R.French, Tr. <>Life is too short to tolerate crappy software! <>