Re: Emacs setup assistants

[David A. Cobb]

Sorry for jumping into a discussion so late.  It's not like I know anything.

Eli Zaretskii wrote:

> > From: David Kastrup <address@hidden>
> > 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!
<>

Superbiskit.vcf
Description: Vcard