Re: Emacs setup assistants

[David Kastrup]

"Eli Zaretskii" <address@hidden> writes:

> > From: David Kastrup <address@hidden>
> > Date: 20 May 2004 19:00:41 +0200
> > 
> > If we could replace things like
> > "To do this, press M-x customize-variable RET
> > preview-default-option-list RET and make sure that [...]" with
> > "press here to customize this behavior", then people would not be
> > forced to jump between customization buffers and manual forth and
> > back.
> 
> I support this goal.
> 
> > > > Isolated customization strings don't do that.
> > > 
> > > I didn't say isolated strings.
> > 
> > You said, this is nothing that could not be done with variable
> > documentation/customize documentation.  This stuff is
> > variable-specific.  You have no idea in what sequence the user might
> > try customizing variables.  Therefore, you are working with isolated
> > strings.  They are not arranged by topic, but by variables.
> > 
> > That's isolated, without context.
> 
> I think we might be miscommunicating.  The text I had in mind was
> normal text that we see even today in the Customize buffer.  For
> example, here is the text we see at the beginning of that buffer:
> 
>     This is a customization buffer for group Emacs.
>     `Raised' buttons show active fields; type RET or click mouse-1
>     on an active field to invoke its action.  Editing an option value
>     changes the text in the buffer; invoke the State button and
>     choose the Set operation to set the option value.
>     Invoke Help for more information.
> 
> We could have similar text fragments that guide the user thru the
> setup process.

But those text fragments would have to appear between the variables
in question.  And explanatory texts are more effective if you can
highlight stuff, include cross references to the manual and so on.

Anyway, you think that something like assistants should best be
tackled from the angle of documentation strings, I think that it
would be better to approach this from printable manuals, like Texinfo
stuff.

Our disagreement would become less relevant if the manual and the
documentation strings were written basically in the same language.  We
already had a proposal of using stuff like @var{...} or so to mark up
variables in the DOC strings.  If we allow at least a solid subset of
Texinfo, with cross references and fonts and similar hoopla, we don't
need to solve our "italics or not" and similar problems separately for
info and DOC strings.

If this language also makes it possible to create widgets and active
code, that would be an advantage.  We would probably want to
preprocess this super-Texinfo before turning it into a printed or
HTML version: it would be nice if an Emacs-internal makeinfo could
just show the the available menus and menu structure by calling them
by name and keymap, for example.

> In short, I'm talking about specialized interactive tutorial, and it
> seemed to me that Customize, if appropriately enhanced and
> augmented, could do the job.  But even if not, I don't see why an
> infrastructure for such a feature could not have some other Lispy
> foundation, rather than a Texinfo foundation.

Because "Lispy foundations" mix text and code in a manner that does
not have a human-readable appeal.  And that means that it becomes
less feasible for a _programmer_ to start with a skeleton, and then
let a _writer_ without much Lisp experience improve the material.

A format which I can throw at somebody not knowing Emacs and tell him
"could you proof-read this for me?" is a nice multiplier.  In
particular, since you can also throw it at somebody not Emacs-savvy
and ask him "could you translate this into a different language for
me?".

We will at some time probably need to convert from and back to XML, so
that people may use their favorite XML editors and tools for helping.
However, as an internal format XML is not a good idea within Emacs: we
already noticed that there are rather few existing DOC strings that
actually clash with Texinfo.  With < > tag syntax, we'd have much
more of a problem.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum