[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[Texmacs-dev] Re: Entering macros

From: Ralf Hemmecke
Subject: [Texmacs-dev] Re: Entering macros
Date: Thu, 24 May 2007 23:07:49 +0200
User-agent: Thunderbird (X11/20070326)

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

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


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.


reply via email to

[Prev in Thread] Current Thread [Next in Thread]