[Texmacs-dev] Re: Entering macros

[Henri Lesourd]

Ralf Hemmecke wrote:

> > the fact remains that my tutorial is a little bit like
> > a book of mathematics : reading is not sufficient, you must
> > redo the exercises with a piece of paper and a pencil.
>
>
> Hmm, was it OK, that I used my computer and TeXmacs? ;-)
That's what I meant : the technical documentation tells you how
to do things, it doesn't only tells a story. More precisely, it tells
things that are difficult to remember if you don't really practice.


> > As far as my own TeXmacs tutorial is concerned, you should
> > definitely have started page 3, section 1.2.1. The very first
> > sentence tells you :
> > <<
> > In the TeXmacs editor, use Document/View/Edit source tree
> > (or Shift-Tab) to switch between the usual WYSIWYG mode
> > and the source mode.
> >  >>
>
>
> First. I already knew about Document/View/Edit source tree BTW, 
> Shift-Tab is not the same as Document/View/Edit source tree on my 
> machine. But that is probably, because I am running the debian etch 
> version of TeXmacs???
My fault : Shift-Tab is specific to the configuration for which I wrote
the tutorial. But if you add :
[[
(kbd-map
 ("S-tab" (toggle-preamble)))
]]

, this keyboard shortcut should become available, although its not
mandatory to have this for the purpose of the tutorial itself.


> Second. Read that sentence again. It tells me that I *can* switch. In 
> a tutorial I would expect to read that I *should* now switch to 
> "source tree mode". Believe it or not, that makes a difference for 
> beginners.
You are definitely right. I will change my tutorial in such a way that
no such kind of ambiguities remains.


> Of course, I was so happy when I found out about this menu entry. 
> Happily enough, such an important thing is burried three mouse clicks 
> away. That should be called "user friendly".
The thing is that this feature should be balanced with its frequency of
used compared to the others. And its not very much used if the users
do not write stylesheets.

More generally, redefining menus and keyboard layout in TeXmacs
is an easy thing, but we never found somebody sufficiently opinionated
to tell us : "OK, your menus & keyboards are bad, I propose you this
much better configuration". Otherwise, I guess that with a little bit of
user pressure, we would evolve TeXmacs to allow some kind of "skin"
mechanism that users could easily customize.


> ((According to your claim above, at that place in the document I 
> should probably be in source code mode so that statement is completely 
> irrelevant for me then.))
Yes, if you are in source mode, everything is inactive, thus using
this tag is irrelevant.


> > 1) Do the basic exercises
>
>
> > You should read the paragraphs 1.3.1. and 1.3.2., and *redo what
> > is shown* (especially for section 1.3.2., which is a full-blown 
> > exercise,
> > telling you exactly what to do : see the points a), b), ..., h) in 
> > the text)
> > while reading the tutorial, in such a way that you are sure you really
> > understand what is meant in the tutorial, and that everything works
> > the way it is said.
>
>
> OK, let me do it and let me show you that I am completely stupid.

This is not specific to you : everybody is completely stupid in front
of an unknown software. But due to lack of space, I cannot tell you
about my early experiences with GW-Basic 2.01 ;-). But I remember
spending a address@hidden amount of time figuring out simple things, I
tell you this.


> 1.3.2. (As you have generously told me above, I now switch to source 
> tree mode.)
>
> a) fine
> b) fine
> c) fine
> d) fine
> e) After typing "2" I have to *guess* that I now should press 
> ARROWright in order to jump over the |. That is a little detail. But 
> it is important.

Right. This is missing from my text.


> I would simply suggest, you add a footnote telling people again at 
> that place that they should switch to wysiwyg mode if they don't see a 
> 4. Such redundancy is extremely helpful.

Yes.


> > For inputting the macros themselves (i.e., see what they do,
> > not only their corresponding markup), you must of course
> > go back to wysiwyg mode, which is the mode when the
> > markup becomes *active*.
>
>
> Oh, shouldn't that be in the tutorial that source mode has something 
> to do with being inactive and wysiwyg mode has a connection to active? 
> Don't thing that is completely obvious for a beginner.

No, this thing has to be explained, all the more because the very concept of
active and inactive is an important concept of its own in computer science.

The problem here is that helping people learning TeXmacs is only part
of my job, thus what I did is wrote this tutorial & had people coming in
my office raising questions. Of course, its not exactly the same now that
it should also work across the Internet.


> Yes, I read over it. But it simply told me that the tutorial is not 
> up-to-date. (Another point of possible frustration.)

Yes, it is not up to date, currently.


> Have you tried the following? (source mode)
>
> \abc ALT-Left param ALT-Left text Arrow-Left
>
> That doesn't look like parameters.

When you type only :
<<
\abc
>>

it is not a macro definition, it is a macro *instance*. The macro definition
spells like that:
<<
\assign[Enter]
abc[Left]\macro[Enter]
...
>>

, and now, when the cursor is inside the <macro|...> tag, when you do 
Alt-Left/Right,
you are inserting a new parameter.

In other words :
[[
<abc|1|2> is an *instance* of the macro "abc(x, y)" ;
<assign|abc|<macro|x|y|...>> is the *definition* of the macro "abc(x, y)".
]]


> > If we say that "[Left]" exactly means : "pressing and releasing the 
> > left arrow
> > of the keyboard once", and "[Alt-Left]" means "Pushing the Alt key, then
> > pressing and releasing the left arrow of the keyboard, then releasing 
> > Alt",
> > then the exact sequence of keystrokes for imputting the first 
> > definition of
> > the macro "italunder", along with one instance of it is :
> >
> > A) Starting from a new buffer, in WYSIWYG mode :
> > {{
> > \assign [Enter]
> > italunder [Left] \macro [Enter]
> > \em [Enter]
> > \underline [Enter]
> > Hello! [Enter]
> > \italunder [Enter]
> > }}
> >
> > Then, try Document->View->Edit source tree, to see the whole
> > corresponding markup.
> >
> >
> > B) Starting from a new buffer, in Source mode :
> > {{
> > \assign [Enter]
> > italunder [Left] \macro [Enter]
> > \em [Enter]
> > \underline [Enter]
> > Hello! [Left][Left][Left][Left]
> > \italunder [Enter]
> > }}
> >
> > Then, do Document->View->Edit source tree, to see how the
> > markup is expanded.
> >
> > Note that this time, when you were inputting markup, no
> > unintuitive disappearing of the current tag happened : you
> > were in source mode, thus you saw everything. On the other
> > hand, what your markup was *doing* was not visible, your
> > markup was not *active*.
>
>
> Henri, that is wonderful and it definitely belongs exactly in that 
> form (entering in source and wysiwyg mode) into the tutorial. That is 
> terribly helpful.
So finally, we found the right way to describe these address@hidden examples. 
I will
reuse this style, then.


> I do this all the time, but (sorry to say) TeXmacs is one of the 
> programs that gave me most frustration.
Perhaps we can change that (or perhaps if its already too late for you, 
we can
analyze the roots of your sufferings in order to avoid it for the others 
;-)...


> OK. I don't remember how exactly I came to that "inactive" statement, 
> but I am unable to just remove the
>
>   <inactive|...>
>
> around the <xyz|aaa|bb>.
Go inside the <inactive|...>, just at the 1st position inside, and then
hit "Ctrl-backspace" (structured delete), and it will remove the surrounding
node.


> Further, the macro abc appears on 3 lines. When I entered it, it was 
> just one line. Then I think I pressed ENTER right before the last > 
> and the 3 line thing appeared. I can press BACKSPACE or DEL as often 
> as I want, I don't get the old format back.

Yes, it is impossible to do it.


> Unfortunately, the mouse is not context sensitive. I would like to get 
> some appropriate hint what I can do with the object under the cursor. 
> Do you think such little details don't frustrate?
This part of the structured editor is not perfect.


> > P.S. : Any other questions welcomed. I hope the next
> >  ones will discuss other points more relevant to LP ;-)...
>
>
> What do you expect from a frustrated user? Should I invest my time in 
> a product that is utterly hard to learn? I know that a lot of other 
> people refuse to use TeXmacs for similar reasons. TeXmacs surely has 
> good ideas in it.

As in any (well designed) software, the number of things to know to be
able to do almost everything remains small.


> But I cannot currently see that it will overtake the world. Sorry.
Another approach would be to write *yourself* a good documentation,
in such a way that it doesn't remains "utterly hard to learn", as you say.

This is not at all an impossible thing to do, and it is very often
how Free Software works, as far as I know.

Otherwise, if what you need is a "product", there are several other
alternatives to TeXmacs that you can *buy*. The difference in this
case is that you cannot have any influence at all on the software,
because the source code is not available. The difference is also that
the very day the corp. producing the software closes, this very software
disappears : as a result, no matter how much comfortable it was to learn
the software, all the knowledge you gained becomes instantly unuseable.

But in any case, if as you put it, lots of people refuse to use TeXmacs
(or any other software) for similar reasons, but in the same time these
very people want everything to be perfectly done and in the same time,
do nothing for it, what can I do for these people ? I can tell you the
answer : nothing, because it is the appropriate answer to people who
want to do nothing.

Sorry, because you know, life is short, and there is a finite amount
of minutes in a human life : one day, its finished. Thus taking care
of not wasting these precious minutes is one important duty of any
reasonable man, IMHO.