Emacs setup assistants

Emacs setup assistants

[Lars Magne Ingebrigtsen]

One project that's been on my mind (well, far back of my mind) for a
few years has been to implement something that would make it easy to
set up complex stuff by guiding the user through the process.

This differs from Customize by being a guided tour through the
options, not just a big whopping menu of stuff to twiddle.

For instance, when setting Gnus up for reading news, an assistant
would look around the environment for sensible news server defaults,
present these to the user, ask for corrections, and at the end check
whether the information given is sensible (ie., that the news server
exists).  (That's a pretty trivial example; setting up spam handling
or mail reading is much more complicated.  :-)

My original plan was to use something HTML-like, and use w3, but Per
Abraahmsen suggested using something more TeXinfo like, and I thought
that was a really groovy idea, so here's an example assistant
specification.

(It's a mock-up; no code has been written, and most assistants would
have more pages than one.)

-----------
@title Configuring Gnus for reading news
@node Server name and port
@variable server :string (gnus-getenv-nntpserver)
@variable port :number 119
@validate
(let ((stream
        (condition-case err
           (open-network-stream "nntpd" nil server port)
          (error (setq error err)))))
   (if (memq (process-status stream) '(open run))
       (progn
         (delete-process stream)
         t)
     nil)))
@end validate
@result gnus-select-method (list server port)
@text
To read Usenet news with Gnus, you first have to tell
Gnus where the news server is.

The server name is @variable{server}; port number @variable{port}.
@end text
-----------

Rendering this is another issue.

I'm posting this here (on the Emacs and XEmacs development lists) to
let all y'all know what's up, and get the loud objections that I'm
sure are imminent...  :-)

And also -- would actually extending the texinfo.el parser be a good
idea, or should I just roll my own (which would call texinfo.el
functions, of course)?
 
-- 
(domestic pets only, the antidote for overdose, milk.)
  larsi@gnus.org * Lars Magne Ingebrigtsen

Re: Emacs setup assistants

[David Kastrup]

Lars Magne Ingebrigtsen <larsi@gnus.org> writes:

> One project that's been on my mind (well, far back of my mind) for a
> few years has been to implement something that would make it easy to
> set up complex stuff by guiding the user through the process.
> 
> This differs from Customize by being a guided tour through the
> options, not just a big whopping menu of stuff to twiddle.
> 
> For instance, when setting Gnus up for reading news, an assistant
> would look around the environment for sensible news server defaults,
> present these to the user, ask for corrections, and at the end check
> whether the information given is sensible (ie., that the news server
> exists).  (That's a pretty trivial example; setting up spam handling
> or mail reading is much more complicated.  :-)
> 
> My original plan was to use something HTML-like, and use w3, but Per
> Abraahmsen suggested using something more TeXinfo like, and I thought
> that was a really groovy idea, so here's an example assistant
> specification.
> 
> (It's a mock-up; no code has been written, and most assistants would
> have more pages than one.)
> 
> -----------
> @title Configuring Gnus for reading news
> @node Server name and port
> @variable server :string (gnus-getenv-nntpserver)
> @variable port :number 119
> @validate
> (let ((stream
>         (condition-case err
>            (open-network-stream "nntpd" nil server port)
>           (error (setq error err)))))
>    (if (memq (process-status stream) '(open run))
>        (progn
>          (delete-process stream)
>          t)
>      nil)))
> @end validate
> @result gnus-select-method (list server port)
> @text
> To read Usenet news with Gnus, you first have to tell
> Gnus where the news server is.
> 
> The server name is @variable{server}; port number @variable{port}.
> @end text
> -----------
> 
> Rendering this is another issue.
> 
> I'm posting this here (on the Emacs and XEmacs development lists) to
> let all y'all know what's up, and get the loud objections that I'm
> sure are imminent...  :-)

Well, there currently is the possibility to say:

If you want to enable document parsing permanently, press @kbd{C-x
C-e} after the following expression:
@example
(progn (require 'tex)
       (customize-save-variable 'TeX-master nil "Manual"))
@end example

> And also -- would actually extending the texinfo.el parser be a good
> idea, or should I just roll my own (which would call texinfo.el
> functions, of course)?

I don't see what you are getting at.  Info files are not read by the
texinfo parser.  Is the question whether you should write your own
info reader?

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Emacs setup assistants

[David Kastrup]

Lars Magne Ingebrigtsen <larsi@gnus.org> writes:

> One project that's been on my mind (well, far back of my mind) for a
> few years has been to implement something that would make it easy to
> set up complex stuff by guiding the user through the process.
> 
> This differs from Customize by being a guided tour through the
> options, not just a big whopping menu of stuff to twiddle.
> 
> For instance, when setting Gnus up for reading news, an assistant
> would look around the environment for sensible news server defaults,
> present these to the user, ask for corrections, and at the end check
> whether the information given is sensible (ie., that the news server
> exists).  (That's a pretty trivial example; setting up spam handling
> or mail reading is much more complicated.  :-)
> 
> My original plan was to use something HTML-like, and use w3, but Per
> Abraahmsen suggested using something more TeXinfo like, and I thought
> that was a really groovy idea, so here's an example assistant
> specification.

One thing that is important is that an assistant is readily
accessible, that there is an association between what you are doing
and the relevant assistant.

It would often help if one was able to find the documentation for a
mode.  I would suggest that we create a convention for specifying the
info manual to be used for features of each major and minor mode.
One could then call the mode-specific help to get at that
information.  If it included active customization entries like you
propose, so much the better.

Of course there is a problem: when we are calling the assistant for
minibuffer-mode, we do not just want an overview over all active
minor modes, but also over all prospective ones, like
file-name-shadow-mode.

So there must be a possibility when some mode gets installed to
specify "add this to the directory for minibuffer-mode".  It would
appear that one could probably graft this onto info modes by creating
a separate dir-file for each major mode or other referenceable entity
for an assistant.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Emacs setup assistants

[Lars Magne Ingebrigtsen]

David Kastrup <dak@gnu.org> writes:

> I don't see what you are getting at.  Info files are not read by the
> texinfo parser.  Is the question whether you should write your own
> info reader?

I'm not talking about info -- I'm talking about TeXinfo.  Which is
a language that Emacs can parse.  See `texinfo-format-region'. 

-- 
(domestic pets only, the antidote for overdose, milk.)
  larsi@gnus.org * Lars Magne Ingebrigtsen

Re: Emacs setup assistants

[Per Abrahamsen]

David Kastrup <dak@gnu.org> writes:

David Kastrup <dak@gnu.org> writes:

> I don't see what you are getting at.  Info files are not read by the
> texinfo parser.  Is the question whether you should write your own
> info reader?

The idea is to skip info altogether, and write an texinfo reader.
This way, we could extend the texinfo format with tags needed for
wizards (or saints, or assistants).  

For example embedded widgets and Emacs Lisp, like this

@saint AUC TeX setup
@node Multifile documents

When @LaTeX{} documents grow large, they are often split up in
multiple files.  One file is a "master" file, which includes a number
of nested files.  When formatting the document, you need to run
@code{latex} on the master file.  If you enable multifile support, AUC
@TeX{} will automatically run @code{latex} on the master file, even if
you invoke @kbd{C-c C-c} from one of the nested files.  In order to do
this, AUC TeX will prompt you for a name of a master file first time
you edit a file, and insert the name in a comment at the end of the
file.  

@widget enable-multifile-documents
(checkbox :format "%v Enable multifile documents." (not TeX-master))
@end widget

@embedded Emacs Lisp
(require 'tex)
(setq saint-on-next-function
     (lambda (customize-save-variable 'TeX-master 
              (not (widget-value enable-multifile-parsing))
              "Saint")))
@end embedded

Which would be displayed like this


    AUC TeX setup:  Multifile documents
    
    When LaTeX documents grow large, they are often split up in multiple
    files.  One file is a "master" file, which includes a number of nested
    files.  When formatting the document, you need to run latex on the
    master file.  If you enable multifile support, AUC TeX will
    automatically run latex on the master file, even if you invoke `C-c
    C-c' from one of the nested files.  In order to do this, AUC TeX will
    prompt you for a name of a master file first time you edit a file, and
    insert the name in a comment at the end of the file.
    
    [ ] Enable multifile documents.
    
                          [Cancel]                 [Next]

Re: Emacs setup assistants

[Juri Linkov]

Per Abrahamsen <abraham@dina.kvl.dk> writes:
> The idea is to skip info altogether, and write an texinfo reader.
> This way, we could extend the texinfo format with tags needed for
> wizards (or saints, or assistants).  

Why not use something more Lispish?

(defsaint enable-multifile-documents
          (checkbox :format "%v Enable multifile documents." (not TeX-master))
  "When @LaTeX{} documents grow large, they are often split up in
multiple files.  One file is a "master" file, which includes a number
of nested files.  When formatting the document, you need to run
@code{latex} on the master file.  If you enable multifile support, AUC
@TeX{} will automatically run @code{latex} on the master file, even if
you invoke @kbd{C-c C-c} from one of the nested files.  In order to do
this, AUC TeX will prompt you for a name of a master file first time
you edit a file, and insert the name in a comment at the end of the
file."
  (require 'tex)
  (setq saint-on-next-function
       (lambda (customize-save-variable 'TeX-master 
                (not (widget-value enable-multifile-parsing))
                "Saint"))))

But then it looks very much like defcustom.

So there is a more general question: why not extend Customize
for a guided tour through options?

-- 
Juri Linkov
http://www.jurta.org/emacs/

Re: Emacs setup assistants

[David Kastrup]

Lars Magne Ingebrigtsen <larsi@gnus.org> writes:

> David Kastrup <dak@gnu.org> writes:
> 
> > I don't see what you are getting at.  Info files are not read by
> > the texinfo parser.  Is the question whether you should write your
> > own info reader?
> 
> I'm not talking about info -- I'm talking about TeXinfo.  Which is a
> language that Emacs can parse.  See `texinfo-format-region'.

Ok, then we are talking about two different things here.  You are
talking about the input file format, I am thinking of how to access
the information.  But let us just explore the possibilities of
synergies:

a) is there something to be gained by having the whole Texinfo
machinery available?  Conversion into HTML (with Active-E controls?
Implemented via emcasclient or natively in emacs-w3m?  Or just with
copy&paste recipes to feed into an inferior Lisp buffer), into
printable manuals, into fast accessible info pages?

The info pages, of course, would be extended with controls for
configuring stuff.

I have in current info manuals of mine sections like

    @node Simple customization, Known problems, Keys and lisp, top
    @chapter Simple customization

    Customization options can be found by typing @kbd{M-x customize-group
    @key{RET} preview @key{RET}}. Remember to set the option when you have
    changed it. The list of suggestions can be made very long (and is
    covered in detail in @ref{For advanced users}), but some are:

    @itemize @bullet
    @item Change the color of the preview background

    If you use a non-white background in Emacs, you might have color
    artifacts at the edges of your previews.  Playing around with the option
    @code{preview-transparent-color} in the @code{Preview Appearance} group
    might improve things.  With some settings, the cursor may cover the
    whole background of a preview, however.

    Since this customization group is very specific to the display engine
    in use, you may see somewhat different options under XEmacs.

    @item Showing @code{\label}s
    @cindex Showing @code{\label}s

    When using @previewlatex{}, the @code{\label}s are hidden by the
    previews.  It is possible to make them visible in the output @file{.dvi}
    by using the @LaTeX{} package @code{showkeys} alternatively
    @code{showlabels}.  However, the boxes of these labels will be outside
    the region @previewlatex{} considers as the preview image.  To enable a
    similar mechanism internal to @previewlatex{}, enable the
    @code{showlabels} option in the variable
    @code{preview-default-option-list} in the @code{Preview Latex} group.

[...]

Now it would obviously be _much_ more helpful if we had some window
with an example file open, and we had active buttons in the info text
that made a certain setting and reran preview-latex on the example
window, showing the effects of each change immediately.  When done,
we could press a button for saving the changes.

Also, one would want a certain integration with customize.

And one would want to have alist of derived file names that are tried
in order.  For example, for the tex-mode assistant, the following
info/TeXinfo/whatever files in the assistant directory would have
their indices searched for a particular option:

texmode-de.ass tex-mode-fr.ass texmode-en.ass

(actually, given my mastery of French, I'd not search the middle one).

That way, assistants can explain things in the local languages if
somebody provided a translation/explanation for it.

This would go a long way towards making Emacs more acceptable to
quite a few people: having the teaching materials in local language,
even if the core documentation and function names and so on aren't.

Also when talking about menu entries, it would be nice to have a
button or active field or whatever that would just pop up the relevant
menu in the current Emacs session (in an associated window/frame with
the required mode, obviously).

Or at least to have some trickery for Texinfo editing that would just
insert a tabular representation of some menu into the text, so as to
get reasonable info in the HTML and printed versions.

In short: I think there are a lot of synergies one could gain from
getting some mechanisms for a closer coupling of the info/Texinfo
system with Emacs.  The relevant file format need not be info, but
the ability to get printed and HTML versions at least for
informational purposes should not lightly be dismissed.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Emacs setup assistants

[Richard Stallman]

    @title Configuring Gnus for reading news
    @node Server name and port
    @variable server :string (gnus-getenv-nntpserver)
    @variable port :number 119
    @validate
    (let ((stream

This would require changes in Texinfo, which would
make it very hard.

Can you design it to use existing Texinfo constructs?  For instance,
just use @example instead of @validate.  Use @defopt instead of
@variable.

You can design some convention for giving the extra info
that you need, so it will show up in the Info file or ASCII
output.

Re: Emacs setup assistants

[David Kastrup]

Richard Stallman <rms@gnu.org> writes:

>     @title Configuring Gnus for reading news
>     @node Server name and port
>     @variable server :string (gnus-getenv-nntpserver)
>     @variable port :number 119
>     @validate
>     (let ((stream
> 
> This would require changes in Texinfo, which would
> make it very hard.
> 
> Can you design it to use existing Texinfo constructs?  For instance,
> just use @example instead of @validate.  Use @defopt instead of
> @variable.

I don't see the problem.  One can easily include a macro file that
defines replacements for all of the above when one does a conversion
to printed form or HTML or such.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Emacs setup assistants

[Ted Zlatanov]

On 19 May 2004, dak@gnu.org wrote:

> is there something to be gained by having the whole Texinfo
> machinery available?  

For the writer, Texinfo is well-supported by Emacs already, and it is
easy to write and parse visually (unlike XML, which was also
proposed).

For the parser, the "special" assistant Texinfo data can be separated
easily from the rest of the document with existing Texinfo
conventions (@ifassistant ... @end ifassistant).  If all the Texinfo
commands were available, that would make writing assistants easier in
itself.

> Conversion into HTML (with Active-E controls?  Implemented via
> emcasclient or natively in emacs-w3m?  Or just with copy&paste
> recipes to feed into an inferior Lisp buffer), into printable
> manuals, into fast accessible info pages?
> 
> The info pages, of course, would be extended with controls for
> configuring stuff.

I think assistant conversion to HTML is a waste of time at this
point, because a) Emacs has all the widgets it needs, and b) the
assistants, as proposed by Lars, are ELisp-oriented.  The other
options sound useful in the abstract sense, but they are all just
different renderings of the same data model.

> Now it would obviously be _much_ more helpful if we had some window
> with an example file open, and we had active buttons in the info text
> that made a certain setting and reran preview-latex on the example
> window, showing the effects of each change immediately.  When done,
> we could press a button for saving the changes.

I think everyone can agree on this :)

> Also, one would want a certain integration with customize.

Absolutely, but I think that variables local to the assistant should
also be allowed.  For instance, if the user was choosing between 4
non-exclusive options that could take him down different paths, the
variable to hold the list of options would be convenient but not
necessarily at the global customize level (it would be just a 'set in
this case).

> In short: I think there are a lot of synergies one could gain from
> getting some mechanisms for a closer coupling of the info/Texinfo
> system with Emacs.  The relevant file format need not be info, but
> the ability to get printed and HTML versions at least for
> informational purposes should not lightly be dismissed.

Agreed.

Ted

Re: Emacs setup assistants

[Ted Zlatanov]

On Wed, 19 May 2004, rms@gnu.org wrote:

>     @title Configuring Gnus for reading news
>     @node Server name and port
>     @variable server :string (gnus-getenv-nntpserver)
>     @variable port :number 119
>     @validate
>     (let ((stream
> 
> This would require changes in Texinfo, which would
> make it very hard.
> 
> Can you design it to use existing Texinfo constructs?  For instance,
> just use @example instead of @validate.  Use @defopt instead of
> @variable.

But they are very different things - @validate holds an ELisp action
distinct from @reset, for instance (@reset is needed when we need to
reset the assistant variables to the defaults).  At the very least it
should be @example{validate} or something like that, and by then you
may as well have a separate syntax.

I think with @ifassistant tags, what's above should not be too much
trouble in terms of making changes to Texinfo itself.  There would
have to be a special Emacs-only renderer for the @ifassistant sections
and I don't know how difficult that would be to write, but it should
not affect the other aspects of Texinfo.  The assistant writers can
ensure that every @ifassistant section has alternate text for those
who can't render the section.

> You can design some convention for giving the extra info that you
> need, so it will show up in the Info file or ASCII output.

I really don't think that's possible.  I started writing some of these
assistants for Gnus, and they simply would not make sense outside
Emacs because we need ELisp for variable definition, initialization,
and validation.  Otherwise you have to make up an alternate data
language to achieve the same things, and it's just as painful while
twice as difficult to learn (yes, XML was mentioned).

In HTML you may be able to simulate the assistants with JavaScript or
XForms, but I really don't think that's worth the trouble.  I can't
imagine how an assistant could be rendered in ASCII.

Ted

Re: Emacs setup assistants

[Eli Zaretskii]

> From: David Kastrup <dak@gnu.org>
> Date: 19 May 2004 17:04:16 +0200
> 
> One can easily include a macro file that defines replacements for
> all of the above when one does a conversion to printed form or HTML
> or such.

Please don't: that way lies madness.

The current implementation of Texinfo macros does not lend itself
easily, to put it mildly, to such gross redefinitions.  Moreover, some
built-in directives cannot be redefined at all due to idiosyncrasies
in their processing by makeinfo.  E.g., @defun and its ilk violate the
Texinfo format which generally disallows sole unescaped braces.  Also,
block directives @foo...@end foo are very hard, if at all possible, to
redefine as macros.

Once upon a time, when Texinfo did not yet support HTML, I needed to
produce HTML from Texinfo and tried to do that by redefining built-in
directives.  It was a nightmare to write, debug, and maintain, and
only sort-of worked because the typical Web browser is very permissive
to ugly HTML, as it renders the text on the fly.  Here, you want to
get Info-like ASCII file that needs to be nicely formatted, so the
situation is much worse.

If and when Karl delivers on his long-standing threat to rewrite
makeinfo from scratch, then perhaps it would be possible to implement
the macro expansion (or perhaps redesign the macros altogether, yet
another threat by Karl) so as to allow what you suggest.  But until
and unless that is done, I recommend to stay away of that alternative.

Re: Emacs setup assistants

[Thien-Thi Nguyen]

Ted Zlatanov <tzz@lifelogs.com> writes:

   For the writer, Texinfo is well-supported by Emacs already, and
   it is easy to write and parse visually (unlike XML, which was
   also proposed).

the most well-supported machinery would be straight elisp (which
is also easy to write and parse visually, for some).  i think if i
were to write a setup assistant, i would find the markup approach
cumbersome (as opposed to the assistant-library-API approach),
because it requires understanding the implicit API anyway; using
markup w/o this understanding is a false economy.

additionally, the markup approach introduces markup-validation,
improper-markup-handling, markup-debugging, and the ever-present
(meta-)documentation requirements.  it becomes its own hive of
complexity, requiring assistance from the necessarily small set of
human experts (since the scheme is only newly hatched), as opposed
to the relatively huge number of programmers who can read/write
elisp already roaming the net.  the even larger number of
programmers who can "read/write" xml is not relevant if they don't
know elisp (intersection trumps union, here).

lastly, the the assistant-library-API approach would be more
easily composable than the markup approach (a natural side-effect
of using the extensible editor's extension language -- go figure).
composability is important for the slack it brings, and other
niceties appreciated by lazy programmers.

ok, that's the entirety of my thoughts on setup assitants support
in emacs.  thanks for taking the time to read this.

thi

Re: Emacs setup assistants

[Lars Magne Ingebrigtsen]

Thien-Thi Nguyen <ttn@glug.org> writes:

> the most well-supported machinery would be straight elisp (which
> is also easy to write and parse visually, for some).  i think if i
> were to write a setup assistant, i would find the markup approach
> cumbersome (as opposed to the assistant-library-API approach),
> because it requires understanding the implicit API anyway; using
> markup w/o this understanding is a false economy.

Writing an assistant as straight elisp would be very dull, because
it's so repetitive.  You have inputs, you have branches, you have
text, and writing that programmatically over and over again would be
a pain.

Not to mention difficult to maintain.

The point of the language proposed here (an extension of TeXinfo,
which is a language that most Emacs developers are already familiar
with (to a greater or lesser degree)) is to make it easy and pleasant
to write assistants.  That way, there's a greater chance that they'll
get written, and that they'll be maintained. 

-- 
(domestic pets only, the antidote for overdose, milk.)
  larsi@gnus.org * Lars Magne Ingebrigtsen

Re: Emacs setup assistants

[David Kastrup]

Juri Linkov <juri@jurta.org> writes:

> Per Abrahamsen <abraham@dina.kvl.dk> writes:
> > The idea is to skip info altogether, and write an texinfo reader.
> > This way, we could extend the texinfo format with tags needed for
> > wizards (or saints, or assistants).  
> 
> Why not use something more Lispish?
> 
> (defsaint enable-multifile-documents
>           (checkbox :format "%v Enable multifile documents." (not TeX-master))
>   "When @LaTeX{} documents grow large, they are often split up in
> multiple files.  One file is a "master" file, which includes a number
> of nested files.  When formatting the document, you need to run
> @code{latex} on the master file.  If you enable multifile support, AUC
> @TeX{} will automatically run @code{latex} on the master file, even if
> you invoke @kbd{C-c C-c} from one of the nested files.  In order to do
> this, AUC TeX will prompt you for a name of a master file first time
> you edit a file, and insert the name in a comment at the end of the
> file."
>   (require 'tex)
>   (setq saint-on-next-function
>        (lambda (customize-save-variable 'TeX-master 
>                 (not (widget-value enable-multifile-parsing))
>                 "Saint"))))
> 
> But then it looks very much like defcustom.
> 
> So there is a more general question: why not extend Customize
> for a guided tour through options?

Because it does not lend itself to writing?  For Texinfo, we have
modes that facilitate getting a nice, human-manageable document
source.  We don't have that for some weird stuff of Lisp functions.

And this approach does not lend itself to decentralized translation
efforts: you need to translate an entire Emacs Lisp file, including
customizations, completely, or a translated version will break.  In
contrast, my proposal would give a fallback for assisting on new
options when the current translation is not yet featuring it.

We'll get more people willing to manage and translate a Texinfo
document than the DOC strings of some Elisp file.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Emacs setup assistants

[Eli Zaretskii]

> From: David Kastrup <dak@gnu.org>
> Date: 20 May 2004 09:25:23 +0200
> 
> > So there is a more general question: why not extend Customize
> > for a guided tour through options?
> 
> Because it does not lend itself to writing?  For Texinfo, we have
> modes that facilitate getting a nice, human-manageable document
> source.  We don't have that for some weird stuff of Lisp functions.

Do we really need an elaborate authoring support in this case?  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.

I'm probably missing something (since both Lars and Per would have
already thought about that), but what?

Re: Emacs setup assistants

[Per Abrahamsen]

Juri Linkov <juri@jurta.org> writes:

> Per Abrahamsen <abraham@dina.kvl.dk> writes:
>> The idea is to skip info altogether, and write an texinfo reader.
>> This way, we could extend the texinfo format with tags needed for
>> wizards (or saints, or assistants).  
>
> Why not use something more Lispish?
>
> (defsaint enable-multifile-documents
>           (checkbox :format "%v Enable multifile documents." (not TeX-master))
>   "When @LaTeX{} documents grow large, they are often split up in
> multiple files.  One file is a "master" file, which includes a number
> of nested files.  When formatting the document, you need to run
> @code{latex} on the master file.  If you enable multifile support, AUC
> @TeX{} will automatically run @code{latex} on the master file, even if
> you invoke @kbd{C-c C-c} from one of the nested files.  In order to do
> this, AUC TeX will prompt you for a name of a master file first time
> you edit a file, and insert the name in a comment at the end of the
> file."
>   (require 'tex)
>   (setq saint-on-next-function
>        (lambda (customize-save-variable 'TeX-master 
>                 (not (widget-value enable-multifile-parsing))
>                 "Saint"))))

That would work too, the essential feature being a markup language in
the text part. 

> So there is a more general question: why not extend Customize
> for a guided tour through options?

I don't actually want it to be a "tour through the options".  The
example above isn't the best.  The saints should be task oriented, like
"I want to read news", not technology oriented like customize "this
option hold the name of the primary nntp used by Gnus".  Eventually "I
want to read news" will translate into setting some options in Gnus,
but that should be mostly hidden from the user.

Re: Emacs setup assistants

[David Kastrup]

Eli Zaretskii <eliz@gnu.org> writes:

> > From: David Kastrup <dak@gnu.org>
> > Date: 20 May 2004 09:25:23 +0200
> > 
> > > So there is a more general question: why not extend Customize
> > > for a guided tour through options?
> > 
> > Because it does not lend itself to writing?  For Texinfo, we have
> > modes that facilitate getting a nice, human-manageable document
> > source.  We don't have that for some weird stuff of Lisp functions.
> 
> Do we really need an elaborate authoring support in this case?

Yes.  Installation assistants have to reflect the views of the
learner, not of the person immersed into programming.  And we also
want to have natural language versions of those.

If the format is basically text, we'll get people to particate in
translation and writing.  Few people bother about correcting
ambiguous wording of DOC strings (which feel like they are the realm
of specialists) in the middle of obscure Lisp code.  The necessity
for hand-formatting your DOC strings alone constantly keeps focus of
the real work.  We really don't want to completely abandon Emacs'
support for conveniently writing texts when the task is writing texts.

> 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.  Isolated customization strings don't do that.
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.

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.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Emacs setup assistants

[Richard Stallman]

    a) is there something to be gained by having the whole Texinfo
    machinery available?

If it is useful for the same text to acts also as a manual, then it is
useful to put this in Texinfo.  However, that depends on avoiding the
need for any extensions to Texinfo, so that the current Makeinfo can
process the file.

Re: Emacs setup assistants

[Eli Zaretskii]

> From: David Kastrup <dak@gnu.org>
> 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.

> 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.

> 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).

Re: Emacs setup assistants

[David Kastrup]

Eli Zaretskii <eliz@gnu.org> writes:

> > From: David Kastrup <dak@gnu.org>
> > 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.

I am not talking about long explanations.  I am talking about about
step-by-step explanations of how to customize what for what
functionality.  Take, for example, the preview-latex manual (should be
online at <URL:http://preview-latex.sourceforge.net/manual>. It
contains a section about easy customizations
<URL:http://preview-latex.sourceforge.net/manual/Simple-customization.html#Simple%20customization>
and it contains a section about more advanced topics
<URL:http://preview-latex.sourceforge.net/manual/The-Emacs-interface.html#The%20Emacs%20interface>,
explaining the basic operation of the package and all related
variables you might consider for influencing the stuff.

People tell us that this manual is reasonably good, and that they
read it.  It is hard work to keep it at a consistent high quality.
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.  Exactly because long explanations are not often read, it is
important that we have a few buttons to actually try out, with
hopefully immediate feedback in a separate window.

> > 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.

> Writing a 10-sentence explanation for a specific aspect of something
> doesn't require something as elaborate as Texinfo.

And where do you put this explanation?  How does the user get the
idea to access it in the first place?

> > 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.

But the name of a variable is the worst user interface for a user to
tell the system what he cares about being informed: if he knows the
name of the variable, he already _has_ the information and does not
need an assistant.

> 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.

And so we hide that information in the documentation string of some
variable the user can't have a chance of guessing?

No, if you are looking for information about how to achieve a certain
functionality, you use the concept _index_ of an appropriate document.
Like the package's Texinfo manual.  _Then_ you get to know which
variables to customize just how.  And if you can do the customization
right in the buffer where you looked them up, so much the better.

And we can write special manuals, assistant documents, that are
explicitly designed to provide a short step-by-step procedure for
getting an overview and getting it configured.

Customization strings are not something organized as a step-by-step
recipe.

Such documents save you reading long-winded explanations and trying to
understand them and devise an action for working on them: instead you
click the proposed buttons.

> > 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.

Where should those help messages come from?  Where do you get a
sequence, a coherent layout, an order?

> No one will ever read a 10-page explanation just to set up a package
> (well, perhaps except you and me).

Who is talking about a 10-page explanation?  Again, the preview-latex
manual has a section "Easy Customization" and it has a section "The
Emacs Interface" or such, and the latter has a density of perhaps 6 or
7 lines of text per referenced variable.  That's not a 10-page
explanation, and every variable is entered in the variable index of
the manual.

Basically you say "Ok, our current documentation tends to be so bad
that nobody reads it, because it requires work understanding and
using it.  So let's not try to make it easier to use, and let's not
make it easy for anybody else to write better documentation."

I repeat: people _do_ read our manual, and it is not easy to get a
quality that is consistently high.  Adding some ways to make it both
easier to use and to write good manual sections (or special-purpose
assistant nodes or files) is not a mistake.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Emacs setup assistants

[Ted Zlatanov]

On Thu, 20 May 2004, rms@gnu.org wrote:

    > a) is there something to be gained by having the whole Texinfo
>     machinery available?
> 
> If it is useful for the same text to acts also as a manual, then it is
> useful to put this in Texinfo.  However, that depends on avoiding the
> need for any extensions to Texinfo, so that the current Makeinfo can
> process the file.

Would the @ifassistant ... @end ifassistant tags I proposed work?  It
seems like they would create the least amount of trouble for existing
Texinfo documents and renderers, since they can just ignore those
tags.

Ted

Re: Emacs setup assistants

[Eli Zaretskii]

> From: David Kastrup <dak@gnu.org>
> 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.

> > Writing a 10-sentence explanation for a specific aspect of something
> > doesn't require something as elaborate as Texinfo.
> 
> And where do you put this explanation?

Between the widgets that customize options.

> How does the user get the idea to access it in the first place?

The idea is that the user reads the text in the buffer top to bottom.
Each time there's a small fragment of text followed by an option that
the user may wish to customize; the text explains how to go about
selecting the value for that option.

> > 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.
> 
> But the name of a variable is the worst user interface for a user to
> tell the system what he cares about being informed

Indeed.  That's why I didn't think about organizing by variable names,
like Customize does today.  What we need is some way of creating a
buffer where options are layed out in a certain order defined by the
author of the assistant, and are interspersed with short fragments of
descriptive text.

It would probably make sense to use some kind of outline mode in such
a buffer, whereby the user first sees only an outline of the
customization process (like one line per step); clicking on that line
would then reveal the details of that step.  Other buttons or links
could lead to advanced customization options and in-depth descriptions
for those who want that.

There are several features designed along similar lines floating
around; 2 examples off the top of my head are the Troubleshooting site
for HP printers (sorry, no URL), and that obnoxious paper clip from MS
Office that pops up its stupid advice every now and then.

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.

I hope I made my intent more clear now.

Re: Emacs setup assistants

[Jon Ericson]

"Eli Zaretskii" <eliz@gnu.org> writes:

> 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.

By the way, the above text reminds me of:

http://www.joelonsoftware.com/printerFriendly/uibook/chapters/fog0000000062.html

Executive summary: too much text tends to confuse people who just want
to setup their program to read mail, edit a document or whatever.

Jon

Re: Emacs setup assistants

[Ted Zlatanov]

On Thu, 20 May 2004, eliz@gnu.org wrote:

> It would probably make sense to use some kind of outline mode in such
> a buffer, whereby the user first sees only an outline of the
> customization process (like one line per step); clicking on that line
> would then reveal the details of that step.  

You're thinking like a programmer and/or power user :)

Normal users rarely appreciate this sort of view of the wizard
sequence.  I think that for usability and simplicity, only the
Next/Previous/Cancel buttons should be allowed for navigation.

When Next can lead to multiple choices because the assistant nodes are
a tree instead of straight line, Next should do a depth-first
traversal in a consistent way (maybe alphabetically following nodes on
the same level).  The point is, give the user the illusion of a
straight decision line that they can use back and forth consistently.

I'm not advocating that we copy a certain GUI, only that users will
be more comfortable if we confuse them less.

> Other buttons or links could lead to advanced customization options
> and in-depth descriptions for those who want that.

That's a good idea, but it should be clearly separated from the
regular assistant.  Maybe @assistantadvanced tags should be used to
surround such options, and the user can show or hide them.

> 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.

I absolutely agree Customize could be useful.  So far in my
experiments to find a useful syntax, I have been doing something like
this:

@ifassistant

@node Hello, choose a server

@variable server :string "default.server.com"

@text

You can define the server: @variable{server}

@end text

@next (string-match ".com" server) "Set up a .com server"
@next (string-match ".org" server) "Set up a .org server"

@end ifassistant

and I think the Customize widgetry would fit perfectly inside the
text buffer.  I don't think the regular Customize interface, with all
its text and extra options, will be right, this needs to be a more
lightweight version of the Customize interface.

Ted

Re: Emacs setup assistants

[David Kastrup]

"Eli Zaretskii" <eliz@gnu.org> writes:

> > From: David Kastrup <dak@gnu.org>
> > 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

Re: Emacs setup assistants

[Richard Stallman]

    Indeed.  That's why I didn't think about organizing by variable names,
    like Customize does today.  What we need is some way of creating a
    buffer where options are layed out in a certain order defined by the
    author of the assistant, and are interspersed with short fragments of
    descriptive text.

Maybe we can combine these two ideas, using Texinfo to control
the generation of a kind of Custom buffer.

It needs to limit itself to the existing Texinfo constructs
if it is to be viable.  But it could have special conventions
for what to put in them, which would guide this process.
For instance, an @example containing nothing but one variable name
perhaps followed by a comment could be the direction to insert
the customization info for that variable.

Re: Emacs setup assistants

[Richard Stallman]

    Would the @ifassistant ... @end ifassistant tags I proposed work?  It
    seems like they would create the least amount of trouble for existing
    Texinfo documents and renderers, since they can just ignore those
    tags.

They would probably give error messages for those two tags,
and they would process (rather than ignore) the text between them.

The only way this can be feasible without waiting years is if it
*completely avoids* any new Texinfo directives.

Re: Emacs setup assistants

[Ted Zlatanov]

On Fri, 21 May 2004, rms@gnu.org wrote:

    > Would the @ifassistant ... @end ifassistant tags I proposed work?  It
>     seems like they would create the least amount of trouble for existing
>     Texinfo documents and renderers, since they can just ignore those
>     tags.
> 
> They would probably give error messages for those two tags,
> and they would process (rather than ignore) the text between them.
> 
> The only way this can be feasible without waiting years is if it
> *completely avoids* any new Texinfo directives.

I'm OK with using anything, as long as I can get started on writing
the assistants soon.  Converting from one special tag to another
should be mechanically possible, eventually.

I like Eli's suggestion of @ignore tags.  Those give the maximum
flexibility.

Ted

Re: Emacs setup assistants

[Eli Zaretskii]

> From: David Kastrup <dak@gnu.org>
> Date: 20 May 2004 22:57:08 +0200
> 
> 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.

Agreed.

But I think that Customize and Emacs widgets already provide a
significant portion of the required functionality to do that.

> 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.

I fear that extending Texinfo along these lines would be much more
difficult than extending Customzie and/or widget.

Re: Emacs setup assistants

[Ted Zlatanov]

On Fri, 21 May 2004, eliz@gnu.org wrote:

>> From: Ted Zlatanov <tzz@lifelogs.com>
>> Date: Thu, 20 May 2004 15:07:35 -0400
>> 
>> Normal users rarely appreciate this sort of view of the wizard
>> sequence.
> 
> Then what _do_ they prefer?

Cancel, Next, Previous.

>> The point is, give the user the illusion of a straight decision line
>> that they can use back and forth consistently.
> 
> I agree, but where did my suggestion deviate from this principle?

You said: "It would probably make sense to use some kind of outline
mode in such a buffer, whereby the user first sees only an outline of
the customization process (like one line per step); clicking on that
line would then reveal the details of that step.  Other buttons or
links could lead to advanced customization options and in-depth
descriptions for those who want that."

Unless I misunderstood, you're suggesting that the user should get a
view of the *whole* customization process.  I disagree, I think the
user should get one step at a time, with the aforementioned Cancel,
Next, Previous navigation buttons.  The Advanced button you mentioned
is a bow to the power users, but let's not forget that those who need
assistants appreciate simplicity.

Ted

Re: Emacs setup assistants

[Eli Zaretskii]

> From: Ted Zlatanov <tzz@lifelogs.com>
> Date: Thu, 20 May 2004 15:07:35 -0400
> 
> You're thinking like a programmer and/or power user :)
> 
> Normal users rarely appreciate this sort of view of the wizard
> sequence.

Then what _do_ they prefer?

> The point is, give the user the illusion of a straight decision line
> that they can use back and forth consistently.

I agree, but where did my suggestion deviate from this principle?

> > Other buttons or links could lead to advanced customization options
> > and in-depth descriptions for those who want that.
> 
> That's a good idea, but it should be clearly separated from the
> regular assistant.  Maybe @assistantadvanced tags should be used to
> surround such options, and the user can show or hide them.

A button labeled "Advanced" should be good enough.

> I absolutely agree Customize could be useful.  So far in my
> experiments to find a useful syntax, I have been doing something like
> this:
> 
> @ifassistant

If we go for Texinfo-like syntax, I'd suggest to choose one that will
not require changes in the Texinfo language and its existing parsers.
Here's one possibility to do that:

@ignore @c assistant

@node Hello, choose a server

@variable server :string "default.server.com"

@text

You can define the server: @variable{server}

@end text

....
@end ignore @c end assistant

Re: Emacs setup assistants

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Date: Fri, 21 May 2004 10:12:02 -0400
> 
> The only way this can be feasible without waiting years is if it
> *completely avoids* any new Texinfo directives.

We could surround the non-Texinfo parts by @ignore ..@end ignore.  Or
we could use directives inside comments as in "@c something".

Re: Emacs setup assistants

[Lars Magne Ingebrigtsen]

Ted Zlatanov <tzz@lifelogs.com> writes:

> I'm OK with using anything, as long as I can get started on writing
> the assistants soon.  Converting from one special tag to another
> should be mechanically possible, eventually.

We're kinda talking about (at least) two things at the same time,
here.

1) Embedding actions into the manuals
2) Doing setup assistants

These two things really don't have all that much to do with each
other.  The Emacs manuals are written in TeXinfo and converted into
info and TeX for browsing online and offline.  Assistants are simply
online constructs.  The reason for writing assistants in (something
like) TeXinfo isn't because they would appear in the manuals (that'd
be both awkward and not very helpful), but because TeXinfo is a
language that Emacs developers know, and it's easy and convenient to
write in.

So all this talk about @ignore stuff is nice for 1), but is pretty
irrelevant for 2).  The assistant parser might be an extension of the
texinfo.el parser, or perhaps it won't; we'll see.  But just go ahead
and write an assistant, and I'll hack up a parser and renderer.  :-)

-- 
(domestic pets only, the antidote for overdose, milk.)
  larsi@gnus.org * Lars Magne Ingebrigtsen

Re: Emacs setup assistants

[Per Abrahamsen]

"Eli Zaretskii" <eliz@gnu.org> writes:

> But I think that Customize and Emacs widgets already provide a
> significant portion of the required functionality to do that.

I have always imagined saints implemented on top of widget.el + some
of the customize support functions.  This would also be true if the
specification language resembled Texinfo.

        user interface:  Something resembling Wizards in MS Windows
saints  programmer interface:  Something resembling Texinfo
        implementation:  Builds on widget.el and low level customize functions

Re: Emacs setup assistants

[Per Abrahamsen]

Ted Zlatanov <tzz@lifelogs.com> writes:

> On Fri, 21 May 2004, eliz@gnu.org wrote:
>
>>> From: Ted Zlatanov <tzz@lifelogs.com>
>>> Date: Thu, 20 May 2004 15:07:35 -0400
>>> 
>>> Normal users rarely appreciate this sort of view of the wizard
>>> sequence.
>> 
>> Then what _do_ they prefer?
>
> Cancel, Next, Previous.

Actually, if the process is linear, I think most users would be happy
with an non-introcive outline of the process available somewhere.
Something like:

--------------------------------------------------------------
                    |  Gnus setup:  3.1 News host
  1. Introcution    |
  2. Identity       |  What is the name of your news (nntp) host
  3. Servers        |  
* 3.1 News host     |  _________________
  3.2 Reading mail  |
  3.3 Sending mail  |
  4. Whatever       |  [Previous]  [Cancel]  [Next]
  6. The End        |
---------------------------------------------------------------

Re: Emacs setup assistants

[Eli Zaretskii]

> From: Ted Zlatanov <tzz@lifelogs.com>
> Date: Fri, 21 May 2004 14:04:59 -0400
> 
> Unless I misunderstood, you're suggesting that the user should get a
> view of the *whole* customization process.  I disagree, I think the
> user should get one step at a time, with the aforementioned Cancel,
> Next, Previous navigation buttons.

That doesn't sound like a difference in views worth arguing about:
whether we present the outline of the whole process or only step by
step, is a minor issue, IMHO.  After all, if the window in which we do
that is small enough, they will see only a couple of first steps
anyway.

> The Advanced button you mentioned is a bow to the power users, but
> let's not forget that those who need assistants appreciate
> simplicity.

The simplicity is achieved by hiding the complex things behind a
button.  Those who want only the simple things will not click on it.

Re: Emacs setup assistants

[Richard Stallman]

    We could surround the non-Texinfo parts by @ignore ..@end ignore.  Or
    we could use directives inside comments as in "@c something".

It is an idea worth considering.  It assumes you do NOT run
Makeinfo on the Texinfo file but rather use a completely separate
parser.  I am not sure that is the right way to do it.

However, using it this way can't be right:

    @ignore @c assistant

    @node Hello, choose a server

    @variable server :string "default.server.com"

    @text

    You can define the server: @variable{server}

    @end text

    ....
    @end ignore @c end assistant

It would not make sense to put a @node command into
the @ignore.  There's no sense using @node unless you want
node structure, and @ignore thwarts that.  Only specific
directives for the assistant structure should be marked
as comments.

@c would probably be more convenient for that.


The other alternative is to run the Texinfo text thru Makeinfo.
Then you need to mark the data for the assistant using things
that will feed into the output.  I think that way is easier.

Re: Emacs setup assistants

[Ted Zlatanov]

On Sat, 22 May 2004, abraham@dina.kvl.dk wrote:

> Ted Zlatanov <tzz@lifelogs.com> writes:

>> Cancel, Next, Previous.
> 
> Actually, if the process is linear, I think most users would be happy
> with an non-introcive outline of the process available somewhere.
> Something like:
> 
> --------------------------------------------------------------
>                     |  Gnus setup:  3.1 News host
>   1. Introcution    |
>   2. Identity       |  What is the name of your news (nntp) host
>   3. Servers        |  
> * 3.1 News host     |  _________________
>   3.2 Reading mail  |
>   3.3 Sending mail  |
>   4. Whatever       |  [Previous]  [Cancel]  [Next]
>   6. The End        |
> ---------------------------------------------------------------

I think that's reasonable.  I don't want users to *jump* to 3.3 or 2
from 3.1, that's the major issue I'm raising.

Thanks
Ted

Re: Emacs setup assistants

[David Kastrup]

Ted Zlatanov <tzz@lifelogs.com> writes:

> On Sat, 22 May 2004, abraham@dina.kvl.dk wrote:
> 
> > Ted Zlatanov <tzz@lifelogs.com> writes:
> 
> >> Cancel, Next, Previous.
> > 
> > Actually, if the process is linear, I think most users would be happy
> > with an non-introcive outline of the process available somewhere.
> > Something like:
> > 
> > --------------------------------------------------------------
> >                     |  Gnus setup:  3.1 News host
> >   1. Introcution    |
> >   2. Identity       |  What is the name of your news (nntp) host
> >   3. Servers        |  
> > * 3.1 News host     |  _________________
> >   3.2 Reading mail  |
> >   3.3 Sending mail  |
> >   4. Whatever       |  [Previous]  [Cancel]  [Next]
> >   6. The End        |
> > ---------------------------------------------------------------
> 
> I think that's reasonable.  I don't want users to *jump* to 3.3 or 2
> from 3.1, that's the major issue I'm raising.

It's their beef.

In particular, some might want to look ahead in order to figure what
to answer for the current question.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Emacs setup assistants

[Ted Zlatanov]

On 24 May 2004, dak@gnu.org wrote:

> Ted Zlatanov <tzz@lifelogs.com> writes:

>> I think that's reasonable.  I don't want users to *jump* to 3.3 or
>> 2 from 3.1, that's the major issue I'm raising.
> 
> It's their beef.
> 
> In particular, some might want to look ahead in order to figure what
> to answer for the current question.

I think this would subvert the whole idea of assistants and make them
too much of a power user's tool.  Power users don't need assistants.
I am strongly convinced of this, based on my experience designing
UIs (text and graphical).  If you or other X?Emacs developers feel
the need to provide such an interface, at least make it optional and
off by default.

Ted

Re: Emacs setup assistants

[Juri Linkov]

Ted Zlatanov <tzz@lifelogs.com> writes:
>> In particular, some might want to look ahead in order to figure what
>> to answer for the current question.
>
> I think this would subvert the whole idea of assistants and make them
> too much of a power user's tool.  Power users don't need assistants.

I think everyone who uses Emacs is by definition a power user ;-)

Emacs user = power user.

What is realy needed is a tool which could help Emacs users to
customize things more easily than Customize can do now.  I see
it as something implemented on top of Customize which will allow
to specify a set of related options in one Customize buffer and
to navigate between such buffers along a logically defined path.
And every Customize buffer could have a [Help] button leading
to the appropriate section of the manual.

-- 
Juri Linkov
http://www.jurta.org/emacs/

Re: Emacs setup assistants

[A.J. Rossini]

Juri Linkov <juri@jurta.org> writes:

> Ted Zlatanov <tzz@lifelogs.com> writes:
>>> In particular, some might want to look ahead in order to figure what
>>> to answer for the current question.
>>
>> I think this would subvert the whole idea of assistants and make them
>> too much of a power user's tool.  Power users don't need assistants.
>
> I think everyone who uses Emacs is by definition a power user ;-)
>
> Emacs user = power user.

NO.  Not even close.  I've got staff
scientists/biologists/masters-level statisticians who use it because
ESS (Emacs Speaks Statistics) is the coolest way to do data analysis
(yes, I helped to write it, but I'm not saying so because I'm biased
;-).  

They don't even come close to being power users in the Emacs sense,
let alone qualify as "programmers" except maybe for excel (well, they
are using R, but more as a set of macros and incantation than formal
or proper programming).  

The idea of simple assistants would gain me so much time (not having
to train) that it isn't even funny.  (now on the other hand, I'm the
one who would be writing assistants, so I'm paying attention at this
point, but that's another issue).

Maybe you meant to have a smiley there, but I don't even want these
users to even think about customize.  Maybe "copy my .emacs", but not
much more.

best,
-tony

-- 
rossini@u.washington.edu            http://www.analytics.washington.edu/ 
Biomedical and Health Informatics   University of Washington
Biostatistics, SCHARP/HVTN          Fred Hutchinson Cancer Research Center
UW (Tu/Th/F): 206-616-7630 FAX=206-543-3461 | Voicemail is unreliable
FHCRC  (M/W): 206-667-7025 FAX=206-667-4812 | use Email

CONFIDENTIALITY NOTICE: This e-mail message and any attachments may be
confidential and privileged. If you received this message in error,
please destroy it and notify the sender. Thank you.

Re: Emacs setup assistants

[Miles Bader]

I consider myself an emacs `power user', but I'd really appreciate simple
assistants too -- sometimes you just don't want to slog though all the
manual pages just to get started reading mail (or my current "confused about
gnus" issue, spam setup).

-Miles
-- 
In New York, most people don't have cars, so if you want to kill a person, you
have to take the subway to their house.  And sometimes on the way, the train
is delayed and you get impatient, so you have to kill someone on the subway.
  [George Carlin]

Re: Emacs setup assistants

[David Kastrup]

Miles Bader <miles@gnu.org> writes:

> I consider myself an emacs `power user', but I'd really appreciate simple
> assistants too -- sometimes you just don't want to slog though all the
> manual pages just to get started reading mail (or my current "confused about
> gnus" issue, spam setup).

I don't see how being forced artificially to keep a sequence will
make things simpler.  If you don't want the "complication" of being
able to look ahead, you are not forced to do so.

Personally, I find it rather a nuisance if some software forces a
sequence unto me that basically forces me to completely start over if
I made a mistake at the beginning somewhere.

I can live perfectly well without that sort of "simplicity".

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Emacs setup assistants

[Eli Zaretskii]

> From: Ted Zlatanov <tzz@lifelogs.com>
> Date: Tue, 25 May 2004 14:16:35 -0400
> 
> Power users don't need assistants.

I disagree.  Power users don't need assistance in setting up something
that they are already power users at.  But when they need to set up
something they never did before, they could use assistance.  At least
I do.

RE: Emacs setup assistants

[Berndl, Klaus]

>> From: Ted Zlatanov <tzz@lifelogs.com>
>> Date: Tue, 25 May 2004 14:16:35 -0400
>> 
>> Power users don't need assistants.

>I disagree.  Power users don't need assistance in setting up something
>that they are already power users at.  But when they need to set up
>something they never did before, they could use assistance.  At least
>I do.

Me too - i consider myself as a power-user of Emacs and in most cases i would bet that i'm able to find out what i need by using apropos, the info-manual etc... but what i really hate is wasting my time by digging around all the manuals when setting up things could also be offered more simple by a well designed assistant.

It's always the same game: There a two takewrs in this game, one is the author of a software (e.g. a complex and powerful emacs-addon, like auctex, semantic, ecb, gnus etc. etc.) and the user of a software (here acting for all the other billions of users of the same software). And one of these two takers must invest time and effort to make this peace of software best usable: If the author desides to offer good manuals and also good assistants then he must invest maybe a lot of time and effort for this but all other users will save a lot of time. On the other hand, if the author of a software wants to save time then all users have to spend a lot of time.... now every one can compute for himself, what is better for all the time available at the world ;-)

IMO (X)Emacs  should offer a well designed backbone so package-authors (and the core-Emacs-authors too) can offer assistants so user's live will become  easier... The live of Emacs-newbies is hard enough ;-)

Klaus

Re: Emacs setup assistants

[Ted Zlatanov]

On Wed, 26 May 2004, eliz@gnu.org wrote:

>> From: Ted Zlatanov <tzz@lifelogs.com>
>> Date: Tue, 25 May 2004 14:16:35 -0400
>> 
>> Power users don't need assistants.
> 
> I disagree.  Power users don't need assistance in setting up something
> that they are already power users at.  But when they need to set up
> something they never did before, they could use assistance.  At least
> I do.

Power users don't need assistants so much because they know where to
look (M-x apropos, etc.) - that's what I meant.  It's not an absolute
rule, but I think it's safe to say that assistants should not *target*
power users, and if those are assisted as well, so much the better.

Ted

Re: Emacs setup assistants

[Ted Zlatanov]

On 26 May 2004, dak@gnu.org wrote:

> I don't see how being forced artificially to keep a sequence will
> make things simpler.  If you don't want the "complication" of being
> able to look ahead, you are not forced to do so.
> 
> Personally, I find it rather a nuisance if some software forces a
> sequence unto me that basically forces me to completely start over if
> I made a mistake at the beginning somewhere.

I am OK with such free navigation as long as it's optional and off by
default.  I just don't want to spend time developing it, but it's a
perfectly fine feature.

> I can live perfectly well without that sort of "simplicity".

Well, yes, and you're unlikely to need assistants as well :) Think
about new Emacs users.  I have seen plenty over the years, and I speak
from experience when I say that if they get assistants, free
navigation by default would be a disservice.  Simplicity in UI design
is a feature, not a lack thereof.

Ted

Re: Emacs setup assistants

[Ted Zlatanov]

On Tue, 25 May 2004, rossini@blindglobe.net wrote:

> The idea of simple assistants would gain me so much time (not having
> to train) that it isn't even funny.  (now on the other hand, I'm the
> one who would be writing assistants, so I'm paying attention at this
> point, but that's another issue).

If you or anyone else want to start writing the text of such
assistants, I can try to fit them into what Lars has already done for
the Gnus assistant.el code.

Ted

Re: Emacs setup assistants

[Stefan Monnier]

>> Actually, if the process is linear, I think most users would be happy
>> with an non-introcive outline of the process available somewhere.
>> Something like:
>> 
>> --------------------------------------------------------------
>> |  Gnus setup:  3.1 News host
>> 1. Introcution    |
>> 2. Identity       |  What is the name of your news (nntp) host
>> 3. Servers        |  
>> 3.1 News host     |  _________________
>> 3.2 Reading mail  |
>> 3.3 Sending mail  |
>> 4. Whatever       |  [Previous]  [Cancel]  [Next]
>> 6. The End        |
>> ---------------------------------------------------------------

I think I've seen something very much like the above in some installers on
Mac OS X.  I thought it was indeed much better than the "peephole" offered
by typical assistants I'd seen before.

> I think that's reasonable.

I find it much more than reasonable.  This helps users understand what's
going on and where they're going.  I'dargue that "the end" should be
replaced by something more useful along the lines of "commit" (tho probably
les technical-sounding) to express the fact that anything you do before
that is harmless.
Also each settable-item should come with a way to view or revert to the
"current" value as well as the "default" value.

> I don't want users to *jump* to 3.3 or 2
> from 3.1, that's the major issue I'm raising.

I think it only makes sense to prevent users from doing something if we
can't make the result sensible.  I.e. jumping from 3.1 to 2 should *not*
be prevented since it should simply do the same as hitting `previous' twice.
It might make sense to prevent the user from jumping from 3.1 to 3.3 if
there's a good technical reason.  But nothing should prevent the
user from jumping from 3.3 to 3.1 and then back to 3.3.  In the above
example, I can't think of any good reason why a user can't jump straight to
3.3 since setting up "sending mail" should not have any dependency w.r.t
"news host": the suggested ordering is arbitrary anyway, so the user should
be free to do things in another order.

To prevent users from getting confused, items in the outline that have not
been completed yet should be dimmed/highlighted.


        Stefan

Re: Emacs setup assistants

[Per Abrahamsen]

Juri Linkov <juri@jurta.org> writes:

> Emacs user = power user.

I want 

  Emacs user = everybody

And with everybody, I mean *everybody*, not "people to stupid to use a
power tool", which is what some people mean by everybody.

Linus shouldn't be the only one dreaming of world dominance.

Re: Emacs setup assistants

[Juri Linkov]

rossini@blindglobe.net (A.J. Rossini) writes:
> Juri Linkov <juri@jurta.org> writes:
>> I think everyone who uses Emacs is by definition a power user ;-)
>>
> Maybe you meant to have a smiley there, but I don't even want these
> users to even think about customize.  Maybe "copy my .emacs", but not
> much more.

That was a half-joke.  I mean Emacs gives the user the power.

But surely Emacs users have different levels of experience.

Many non-Emacs assistants or simple options windows of various
programs provide some kind of [Advanced] button which leads to
a separate page with more settings for more experienced users.

Emacs assistants could provide something similar as well: on the
highest level to have a minimal set of basic options to set up
things to a working state, and somewhere on deeper levels of the
customization outline provide options that require more knowledge
but allow more customization.

And there is nothing wrong with using assistants even by experienced
Emacs users when assistants allow to customize simple things faster
than by reading manuals and manually modifying .emacs.

-- 
Juri Linkov
http://www.jurta.org/emacs/

Re: Emacs setup assistants

[David Kastrup]

Ted Zlatanov <tzz@lifelogs.com> writes:

> On 26 May 2004, dak@gnu.org wrote:
> 
> > I don't see how being forced artificially to keep a sequence will
> > make things simpler.  If you don't want the "complication" of
> > being able to look ahead, you are not forced to do so.
> > 
> > Personally, I find it rather a nuisance if some software forces a
> > sequence unto me that basically forces me to completely start over
> > if I made a mistake at the beginning somewhere.
> 
> I am OK with such free navigation as long as it's optional and off
> by default.

What does "off by default" mean?  Should we disable the cursor keys so
that, unless you customize a secret obscure variable, you don't get a
chance to amend your choices?

> > I can live perfectly well without that sort of "simplicity".
> 
> Well, yes, and you're unlikely to need assistants as well :) Think
> about new Emacs users.  I have seen plenty over the years, and I
> speak from experience when I say that if they get assistants, free
> navigation by default would be a disservice.

It is not "by default".  I am not suggesting that Emacs should press
wildly upon the cursor keys, or that the user has to move from one
item to another manually.

> Simplicity in UI design is a feature, not a lack thereof.

It is not simplicity if I have to start over from scratch if I had
made a wrong choice.  It is not simplicity if I am not allowed to see
consequenes of what I am working with.

Simplicity is served by having a natural sequence from start to end,
not by punishing the user severely if he finds he made a mistake or
wants to amend a choice he made earlier, necessitating temporarily
not following the sequence.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Emacs setup assistants

[Ted Zlatanov]

On 26 May 2004, monnier@iro.umontreal.ca wrote:

> I think it only makes sense to prevent users from doing something if we
> can't make the result sensible.  I.e. jumping from 3.1 to 2 should *not*
> be prevented since it should simply do the same as hitting `previous' twice.
> It might make sense to prevent the user from jumping from 3.1 to 3.3 if
> there's a good technical reason.  But nothing should prevent the
> user from jumping from 3.3 to 3.1 and then back to 3.3.  In the above
> example, I can't think of any good reason why a user can't jump straight to
> 3.3 since setting up "sending mail" should not have any dependency w.r.t
> "news host": the suggested ordering is arbitrary anyway, so the user should
> be free to do things in another order.
> 
> To prevent users from getting confused, items in the outline that have not
> been completed yet should be dimmed/highlighted.

I disagree with this design choice, as I've mentioned already.  I
think it complicates the UI unnecessarily and does not bring any real
functionality to assistants.  If, however, you or anyone else chooses
to implement it and make it the default navigation interface, I won't
argue.  Any assistant is better than nothing.

I'm currently trying to get the Gnus assistant.el to be useful, if
anyone is interesting in helping.

Ted

Re: Emacs setup assistants

[René Kyllingstad]

* Ted Zlatanov:
>  On 26 May 2004, monnier@iro.umontreal.ca wrote:
>  
> > I think it only makes sense to prevent users from doing something if we
> > can't make the result sensible.  I.e. jumping from 3.1 to 2 should
> > *not* be prevented since it should simply do the same as hitting
> > `previous' twice.  It might make sense to prevent the user from jumping
> > from 3.1 to 3.3 if there's a good technical reason.  But nothing should
> > prevent the user from jumping from 3.3 to 3.1 and then back to 3.3.  In
> > the above example, I can't think of any good reason why a user can't
> > jump straight to
> > 3.3 since setting up "sending mail" should not have any dependency w.r.t
> > "news host": the suggested ordering is arbitrary anyway, so the user should
> > be free to do things in another order.
> > 
> > To prevent users from getting confused, items in the outline that have
> > not been completed yet should be dimmed/highlighted.
>  
>  I disagree with this design choice, as I've mentioned already.  I
>  think it complicates the UI unnecessarily and does not bring any real
>  functionality to assistants.  If, however, you or anyone else chooses
>  to implement it and make it the default navigation interface, I won't
>  argue.  Any assistant is better than nothing.

FWIW: I consider myself a power user, and I would be very happy to have
assistants implemented as outlined (with a clear view of which steps are to
be performed, and some flexibility in moving betweem them for
commiting/applying the changes) for the reasons David K. and Stefan
M. outlined.

I would certainly use them myself (for example for setting up spam
filtering in Gnus), and it would allow me to introduce (X)Emacs to other
people without forcing them to spend a lot of time up front reading the
manuals and getting comfortable with (even basic) elisp.

There, one more datapoint in the "what would (power) users want" debate :)


-- René

Re: Emacs setup assistants

[René Kyllingstad]

* Ted Zlatanov:
>  On 26 May 2004, monnier@iro.umontreal.ca wrote:
>  
> > I think it only makes sense to prevent users from doing something if we
> > can't make the result sensible.  I.e. jumping from 3.1 to 2 should
> > *not* be prevented since it should simply do the same as hitting
> > `previous' twice.  It might make sense to prevent the user from jumping
> > from 3.1 to 3.3 if there's a good technical reason.  But nothing should
> > prevent the user from jumping from 3.3 to 3.1 and then back to 3.3.  In
> > the above example, I can't think of any good reason why a user can't
> > jump straight to
> > 3.3 since setting up "sending mail" should not have any dependency w.r.t
> > "news host": the suggested ordering is arbitrary anyway, so the user should
> > be free to do things in another order.
> > 
> > To prevent users from getting confused, items in the outline that have
> > not been completed yet should be dimmed/highlighted.
>  
>  I disagree with this design choice, as I've mentioned already.  I
>  think it complicates the UI unnecessarily and does not bring any real
>  functionality to assistants.  If, however, you or anyone else chooses
>  to implement it and make it the default navigation interface, I won't
>  argue.  Any assistant is better than nothing.

FWIW: I consider myself a power user, and I would be very happy to have
assistants implemented as outlined (with a clear view of which steps are to
be performed, and some flexibility in moving betweem them for
commiting/applying the changes) for the reasons David K. and Stefan
M. outlined.

I would certainly use them myself (for example for setting up spam
filtering in Gnus), and it would allow me to introduce (X)Emacs to other
people without forcing them to spend a lot of time up front reading the
manuals and getting comfortable with (even basic) elisp.

There, one more datapoint in the "what would (power) users want" debate :)


-- René

Re: Emacs setup assistants

[Richard Stallman]

    I disagree.  Power users don't need assistance in setting up something
    that they are already power users at.  But when they need to set up
    something they never did before, they could use assistance.  At least
    I do.

I agree with that.  I would like to have something like assistants for
configuring things that need configuration.

However, we should aim to make assistants easy to use for beginners,
and that is the hard part.  Making them handier for more experienced
(generally) users should be an easier job.

Re: Emacs setup assistants

[David A. Cobb]

[-- Attachment #1: Type: text/plain, Size: 3243 bytes --]

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

Eli Zaretskii wrote:

>>From: David Kastrup <dak@gnu.org>
>>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!
<>

[-- Attachment #2: Superbiskit.vcf --]
[-- Type: text/x-vcard, Size: 260 bytes --]

begin:vcard
fn:David A. Cobb
n:Cobb;David A.
adr:;;7 Lenox Av #1;West Warwick;RI;02893-3918;USA
email;internet:Superbiskit@cox.net
title:Independent Software Consultant
note:PGP Key ID#0x4C293929 effective 01/28/2004
x-mozilla-html:TRUE
version:2.1
end:vcard

Re: Emacs setup assistants

[Per Abrahamsen]

"David A. Cobb" <Superbiskit@cox.net> writes:

> I would really hate to see the information separated physically from
> the code!  That's a guarantee one of them will be wrong.

There are two levels of documentation.  One is tool-centric, and the
other is user centric.  Both are needed.  Tool-centric documentation
says "I'm a tool, here is what I can do".  User-centric documentation
says "I'm a user.  I have this problem.  Here is how I solved it".

The tool-centric documentation should be as close to the code as
possible, in order to stay complete and up to date.  Doc-strings and
Customize are great for providing tool-centric documentation.

But user-centric documentation needs another viewpoint.  Assistants
are supposed to be user-centric, otherwise they would just be another
interface to Customize.  I don't care whether they are written in a
markup language with embedded Lisp, or on Lisp with an embedded markup
language.  But if they are written in Lisp, they will (logically) be
separate from the main code body, unlike doc strings and defcustoms.