Dear Steve,

If I use the -n option in gap to prevent echoing in my emacs shell
window, then I can not access the help system. Here is what happens:
(using emacs 19.22)

yes, this is correct. "-n" will prevent all line editing features including
history and help. However, there is an EMACS mode "gap-process", written by
Michael Smith (Michael.Smith@Pell.ANU.Edu.AU), which might help (the el file
is in gap3r4p0/etc). This mode implements "?" with output redirection into
another buffer, but there are problems with large help sections. I will try
to find out if Michael has already updated his mode.

Another question - with the manual growing several hundred pages every
release, it's getting hard to even know what is even available. Has
anyone written a converter to info? Such a format would make it easy
to browse the manual.

There was a discussion on that subject some time ago, I will append the
relevant mail. It should not be too hard to write such a convert, but at the
moment no one in Aachen has enough time to do so. If anyone has already
written a convert, please upload it into our incoming directory. If anyone
needs information about the structure of the latex files, please contact
"Gap-Trouble@Math.RWTH-Aachen.DE".

best wishes
Frank

=============================================================================
Date: Fri, 12 Mar 1993 17:18:13 +0100
Comment: GAP Forum
Originator: gap-forum@samson.math.rwth-aachen.de
Errors-To: martin@samson
Reply-To: <gap-forum@samson>
Sender: gap-forum@samson
Version: 5.31 -- Copyright (c) 1991, Anastasios Kotsikonas
From: martin@bert.math.rwth-aachen.de (  Martin Schoenert)
To: Multiple recipients of list <gap-forum@samson>
Subject: Re: RE: new GAP for OS/2 with hypertext documentation


Arnaldo Mandel writes in his e-mail message of 1993/03/11

One of the things I miss on GAP is good online documentation, fur the
unix environment implementation. My favorite choice would be an Emacs
info document, although I can survive other formats which allow fast
online search (thus, havin the manual online as a .dvi or .ps file
will not cut it). Is there any hope that such a thing will ever
appear? Maybe this IPF hypertext can be ported.

I would like to know which features of GNU EMACS' info mode you miss in
GAP's on-line help. I think that both allow roughly the same.

1) You know exactly what you are looking for:

In EMACS you use 'g <name-of-node>'.

In GAP you use '?<name-of-section>'.

2) You know roughly what you are looking for:

In EMACS you go to one of the indices (say with 'g concept index'),
find the most likely candidate and with 'm <choice>' you go there.

In GAP you use '??<short string>', select the most likely candidate
and with '?<name>' you go there.

3) You want to browse around in the manual:

In EMACS you go to the top node, select a section and go there
with 'm <section>'. In the section you again use 'm <subsection>'
to go to the next subsection.

In GAP you say '?chapters', select a chapter and go there with
'?<chapter>'. Then you read the first section of the chapter and
find references (of the form (see "<section>")) to all the
sections in this chapter. Then you again use '?<section>' to
go to the section you are interested in.

4) You want to go to the next or previous node/section:

In EMACS you use 'n' and 'p'.

In GAP you use '?>' and '?<'.

5) You want to go from a subsection to a section:

In EMACS you use 'u'.

In GAP you use '?<<'.

6) You want to go from a subsection to the next node section:

In EMACS you use 'u' and 'n'.

In GAP you use '?>>'.

7) You want to follow a cross reference.

In EMACS you use 'f <reference-name>'.

In GAP cross references are again of the form (see "<section>")
and you use '?<section>'.

8) You want to go to the last section that you visited before the
current one:

In EMACS you use 'l'.

In GAP you use '?-'.

One feature I like in David Gillespie's enhanced EMACS's info mode (it is
not in the standard info mode) that is missing in GAP is the function
','. With 'i' you first specify an pattern. Then ',' lets you visit in
turn all nodes that have index entries that match this pattern.

One feature I dislike in EMACS' info mode is that I still find it
difficult to decipher the information at the top of each node which
should tell me where I am. I find GAP's top line much easier to read.

David Sibley replied in his e-mail message of 1993/03/11

Eh? I find the GAP online documentation to be excellent. It's much
faster and more efficient than anything I ever experienced with EMACS
info files, where you have to know where an item is in the heirarchy.

"excellent": why, thank you. "faster": I don't think so. In EMACS a
special file (info-file) is generated from the TeX manual. This file
contains information that allows EMACS' info mode to go very fast from
node to node. In GAP the online help always works from the original
LaTeX files. To find a node it has to search the 'manual.toc' file, open
the chapter file, search linearly to the section, etc. It seems to be
fast enough though.

Lee Schumacher replied in his e-mail message of 1993/03/11

The ? and ?? are quite useful, its true, but hardly a substitute for a
real structured info tree. The problem with the GAP facilities is
that you need to know the NAME of the function or concept before you
can find it. Of course the topic of discourse in GAP is sufficiently
narrow that this is not a problem in general. However I did read the
manual off line first and now ? is useful more as a memory jogger.
Note that emacs info files are intended more for learing new concepts
and groups of commands or functions. If you just want to find a
command and you have a pretty good idea what the name is then you
use apropos, which provides all of the functionality of ? and ??.

I argue that the GAP manual is tree structured (into chapters and
sections), and that the online help allows you to search through this
structure. In the online help the top node is '?chapters', with
references to the first sections of all chapters. And the first section
of each chapter contains references (of the form (see "<section>")) of
all the sections of this chapter. So the tree is quite shallow (of depth
2, except in "Group", where it has depth 3), but it's a tree
nevertheless.

The chapter that you get with '?About GAP' is certainly not a reference
manual. It's main purpose is to learn about the (new) concepts in GAP.
I know that not all sections of this chapter are easily read online, but
the first few certainly are.

Arnaldo Mandel replied in his email of 1993/03/11

I don't [find GAP's online help more convenient than EMACS' info].
But the whole discussion is boiling down to a matter of
personal preferences. Since I live most of the time within emacs, and
maintain it here, it is perhaps natural that I have become addicted to
info. On the other hand, I will retract my complaints about lack of
"good online documentation" (I had no intention of putting down ? and
??), and qualify it instead as a "lack of an online manual of the
kind *I* find convenient".

Now, perhaps I would have kept to myself about info, if it wasn't for
the circunstance that a hypertext version of GAP documentation had been
created, for another plataform. The source code for GAP shows that
emacs was a heavily used tool for development; maybe the developers of
GAP would have something to say on this matter.

I havn't ever used OS/2's IPF. Also Hypertext is such a buzzword. Could
somebody enligthen me about IPF's features?

I use EMACS a lot. Actually I probably would be lost without EMACS.I
don't think it would be too difficult to make a TeXinfo manual for GAP,
but we are certainly not considering it in the moment. (I don't miss a
GAP info-file for EMACS, but then I probably have to use the manual less
often than others ;-).

Martin.

-- .- .-. - .. -.  .-.. --- ...- . ...  .- -. -. .. -.- .-
Martin Sch"onert,   Martin.Schoenert@Math.RWTH-Aachen.DE,  +49 241 804551
Lehrstuhl D f"ur Mathematik, Templergraben 64, RWTH, D 51 Aachen, Germany