[Texmacs-dev] Re: Entering macros

[Ralf Hemmecke]

On 05/24/2007 08:11 PM, Henri Lesourd wrote:
> 0) How to read a technical tutorial

Oh, that is going to be interesting... ;-)

> Although I tried not to adopt the absolutely undrinkeable style
> of other kinds of documentation where you absolutely need
> to read *everything* from the beginning, like, e.g. the UNIX
> man ;-(..., 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? ;-)

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

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.

> Thus, from the very beginning, if you read this, you know that this
> Source tree thing is important.

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

> More generally, it is important, and very useful to be familiar
> with the kind of style used in technical documentation, namely,
> it starts stupidely by explaining very basic things, and then
> builds on it. As a consequence of this way of writing, the
> *very first* thing you must think when you do not understand
> something is : << There is something else needed to understand.
> This thing should have been said before >>.

Of course. Search for "inactive". The first thing I found is the sentence:

  ... here we will use the 'inactive*' tag which, in WYSIWYG mode,
  can be used to turn a piece of the document in its inactive form:

After that I know that "inactive*" has something to do with "inactive 
form", but I am missing a definition of "inactive form".

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

> To a certain extent, it is possible to write technical documentation
> in a more intuitive style, but there are limits, what you say cannot
> be self-contained all the time, otherwise it becomes really difficult
> to write the documentation.

I am not saying that you did a bad job. I learnt something from your 
tutorial. But I am still frustrated. Just a suggestion to the TeXmacs 
developers. Find someone who wants to learn TeXmacs, sit together with 
him and look what problems arise if he *doesn't get help*. Exactly that 
should be documented. Write about how difficult it is an how to overcome 
those little errors. I cannot do it, since I just waste time in looking 
for a solution that experts just find too simple to tell me.

> Anyway, the question of how to write a good technical documentation
> is important and interesting, and too often, people stupidly assume
> that you should magically know what I just said. Of course it is
> not true.

> 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.
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. Certainly, a reasonably bright person will find out. But why 
must there be guessing. Write it in the tutorial. That arrow key belongs 
to the interface of entering commands.
f) Frustration. I don't see a 4 I just see <plus|2|2...>.
Even worse. I can press ENTER several times, but the cursor does not 
move from the ... position.
So I must have done something completely wrong. (Of course now I know 
that I should switch to WYSIWYG mode. But the whole idea of source 
mode/wysiwyg mode is not so obvious.
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.

> If you do this part completely, then you will start having much
> better clues about how working with markup works in TeXmacs,
> and what is the difference between source mode and wysiwyg
> mode (please note that the exercise in 1.3.2. is intended to be
> done in wysiwyg mode).

Oh, you are telling me afterwards. Thank you, I am already frustrated. 
;-) Put that in the tutorial and not in the texmacs-dev email archive.

> 2) Inputting macros
>
> Next you can jump to section 3.2., and try what it describes
> about macro programming and variables.
>
> When inputting and modifying the definitions of the
> macros (i.e., <assign|...>, and the like), you should
> be in Source mode.

Please put that into the tutorial. And repeat an a), b), c), etc.
for entering that <assign|italunder|<macro... thing.
Redundancy is never a bad thing and here you should add when to press 
the arrow key.

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

> Sorry to repeat, but to make this point clear : this is
> very basic, and exactly the same as with HTML :
>
> -> when you are editing the markup with a text editor,
>  it is like the source edit mode of TeXmacs ;
> -> when you are looking at your HTML page in a
>  browser, it is like the WYSIWYG mode of TeXmacs ;

> ==>
> There is a point in my tutorial that is not accurate
> for you : you should use Alt-Left and Alt-Right,
> the keyboard shortcuts Shift-Ctrl-Left and Shift-Ctrl-Right
> do not work on standard TeXmacs (the point is that I
> wrote this tutorial for people using a slightly modified
> version of TeXmacs).

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

> ==>
> The special keyboard shortcuts you need to be able to
> edit the markup for macro definitions is :
>
> -> Alt-Left ; Alt-Right : input a new parameter to
>  the left or to the right ;

Have you tried the following? (source mode)

\abc ALT-Left param ALT-Left text Arrow-Left

That doesn't look like parameters. Since I don't know all the details, I 
have simply overread that above you said something about "macro 
definitions".

> -> Alt-A : when you are *inside the body* of a macro
>  definition, you *must* use Alt-A to input a variable
>  occurrence. This occurence then appears as brown
>  text.

That is a good description. It highlights an important part.

> > So I start with a new buffer. Let me give here the exact keystrokes.
> >
> > \assign ENTER
> > italunder ARROWleft
> > \macro ENTER
> What do you mean exactly by "ARROWleft", or "ALT-ARROWright" ?

I wanted to make clear that I don't write the letters L e f t, but 
rather pressing the left arrow key.

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

> > In order to learn TeXmacs, one needs to sit together with an 
> > knowledgable TeXmacs user and have the flow explained.

> No, you just need to be used to the kind of upleasant style in
> which technical documentation is written.

Don't worry I am used to that. But the documentation should be 
sufficiently helpful and sufficiently correct (and tell me what to do if 
I make an error).

> > I cannot always invest so much time to write such an email.
> > TeXmacs makes me feel stupid and helpless. :-(

> You will have the same problem with any piece of software for which
> you have no clue and that you must learn only by means of reading
> the documentation.

I do this all the time, but (sorry to say) TeXmacs is one of the 
programs that gave me most frustration.

> > I would feel much more confident if I had a clear definition of the 
> > TeXmacs style language

> The definition in Help->Reference guide->TeXmacs primitives and
> in Help->Reference guide->Stylesheet language are pretty clear and
> complete. These documents are the reference about the TeXmacs
> style language, by the way.

> > at hand and I could type everything in by hand. 

> You can type everything by hand, e.g. in emacs.

That was not what I meant. I just wanted to type in the control sequence 
string in TeXmacs and later let TeXmacs parse it. If I have to switch to 
Emacs, I would never come back.

> > Yes everything, including < an | and >. I have the impression you 
> > could win a lot of users if you allow that, parse the string and 
> > complain (with an appropriate error message) if something is wrong.
>
> I agree with this. On the other hand, once you are used to it,
> the Source editing mode is not that bad : it provides you with
> some kind of structured editing, and with syntax coloring.

Yes, but I guess, many people turn their back to TeXmacs before they are 
sufficiently familiar with the source editing mode.

> > Currently, the cursor simply refuses to go to this or that place 
> > without telling me why.

> This is just because you are not working in Source editing mode.

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

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

> 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. But I cannot currently see that it will overtake the world. Sorry.

Ralf