[Texmacs-dev] Re: Entering macros

[Henri Lesourd]

Ralf Hemmecke wrote:

> Hi Henri,
>
> I tried your little example, but I am completely helpless.
OK.

0) How to read a technical tutorial

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.

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

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

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

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.

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.

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


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.

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

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

==>
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 ;

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


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

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


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


> 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 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. The only trick
is that you must be aware that the TeXmacs document format
is in fact space and carriage-returns aware, and it is not cool,
because you never know for sure what the appropriate formatting
should be, and if it is not correct, TeXmacs either crashes or
silently behaves in strange ways.

Yes, although it saves space, having no space / carriage-return
independent format for TeXmacs documents is a mess, you are
right. This being said, it remains quite possible to hack around
that if you look at an already existing (correct) TeXmacs document,
and redo the same in emacs.


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


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


Best, Henri


P.S. : Any other questions welcomed. I hope the next
 ones will discuss other points more relevant to LP ;-)...