mailing-list for TeXmacs Users

[Enrique Perez-Terron <address@hidden>]

On Tue, 2003-10-21 at 17:45, Javier Arántegui Jiménez wrote:

> I will try to do some examples if I am able to understand how the style 
> files 
> work. It requires more knowledge of TeXmacs than I want to know.

I made an experiment. I copied
/usr/share/TeXmacs/packages/section/section-book.ts to
~/.TeXmacs/packages/section/section-book.ts, and changed the part that
says

<assign|section*|<macro ...<arg|name>...

and made it

<assign|section*|<macro ...<with|color|red|<arg|name>>...

In order for this change to take effect, I found that I had to 

 1. quit TeXmacs, 
 2. delete the file ~/.TeXmacs/system/cache/__book__
 3. restart TeXmacs.

Of course, I also had to make sure the document actually used the book
style, Document->Style->book, and that the document used the section
macro (Text->Section->Section).

The result is that the section title now appears in red. Subsection
titles still appear in black.

In order to determine where do make this change, I first used emacs to
look at my .tm file. I had selected a word and made it red and italics,
and the word appeared in emacs like this:

<with|font shape|italic|<with|color|red|word>>

I also saw that the section started with the text

<section|First Section>

where "First Section" was the actual section title.

In section-book.ts I found

  <assign|section|<macro|name|<assign|sectionnr|<plus|<apply|sectionnr>|1>><a\
  pply|resetsection><apply|header-secondary|<arg|name>|<apply|thesection>|<tr\
  anslate|Section|english|<value|language>>><assign|thelabel|<apply|thesectio\
  n>><apply|toc-normal-1|<apply|thelabel><space|2spc><arg|name>><expand|secti\
  on*|<apply|thesection><apply|sectionsep><arg|name>>>>
                                                                              
                 
(I hope the mail user agents do not fiddle too much with the line endings!)

This looks like it assigns a meaning to the name "section", defining it
to be a macro with one argument, called "name".

Then I tried to re-indent (manually) the clauses, to see if I could
figure out the structure. It became about like this:

<assign|section|
        <macro|name|
                <assign|sectionnr|<plus|<apply|sectionnr>|1>>
                <apply|resetsection>
                <apply|header-secondary|<arg|name>|
                        <apply|thesection>|
                                <translate|Section|english|<value|language>>>
                <assign|thelabel|<apply|thesection>>
                <apply|toc-normal-1|
                        <apply|thelabel>
                        <space|2spc><arg|name>>
                <expand|section*|
                        <apply|thesection>
                        <apply|sectionsep>
                        <arg|name>>>>

I do not know what is the difference between <apply|resetsection> and
plain <resetsection>, perhaps the difference is that we do not want the
macro resetsection expanded at the point in time when the code above is
being read by TeXmacs.

Also I had no idea what is the difference between <apply|xxx> and
<expand|xxx>. After a lot of reading it comes to me that this could be
related to the difference between "macro" and "function", essentially
differeing in whether or not the arguments are sent through some eval
function before actually being substituted for the formal parameters in
the macro/function body. (Correct me, please!)

Anyhow, I guess the final three lines are the code that actually
produces the section number and the section title text. These are sent
through the "section*" macro which determines the font and style of
text.

I guess that if <arg|name> had been wrapped in <with|color|red|...>
instead of the change to the section* macro, then only the section title
text had been set in red, not the section number.

> Probably the 3 things I miss more of TeXmacs are:
> 
> 1. A user guide.
> 2. Good export to pdf (and, sometimes but not frequently, to html)
> 3. A MS Windows port (I don't use Windows much but my students do)
> 
> 
> Here it's my suggestion of Table of contents of a minimal user guide:

The current documentation is largely out-dated. More often than not,
references to menu entries have changed location. The organization of
the current manual is questionable. At least, I had no idea what I would
find under Help->Manual->Editing Tools. Nevertheless, much of what you
want is there somewhere.

> 1. Introduction
>       Reasons to use TeXmacs
>       ?Emacs + LaTex = TeXmacs?

Help->Welcome

> 2. Setup
>       Linux: RPM
>       Mac OS X: Fink
>       Other tools: Ghostscript, Maxima, Octave, Xfig,...

Not covered today, as fas as I know. Perhaps Help->Configuration->*
should be considered to belong here

> 3. First 30 minutes with TeXmacs
>       Description of the interface
>       ?TeXmacs is WYSIWYG or WYSIWYM (What You See Is What You Mean)?
>       Sections and enviroments.
>       Save a document
>       Printing and exporting

Help->Manual->Getting Started
Help->Manual->Typing simple texts
Help->Manual->Editing Tools

> 4. A more complex document
>       Header and footer
>       Special characters
>       Fonts and paragraphs

Help-Manual->Advanced features is vaguely related. The Special
Characters section is one that I have been looking for quite often.

> 5. Equations
>       Edition of equations
>       Numering equations and cross references

Help->Manual->Mathematical Formulas
Help->Manual->Automatically generated contents (cross references)

I cannot remember having seen any documentation of how to get 
numbered equations. I just had to experiment with styles. IIRC,
I got numbered equations by using one of 
Document->Style->Mathematics->*.

> 6. Tables
>       How create a table?
>       Edition

Help->Manual->Tabular Material

> 7. Graphics
>       Insertion and viculation of graphics
>       Load image dialog

Help-Manual->Advanced features

> 8. TeXmacs as an interface
>       Maxima
>       Octave
>       Gnuplot

Help->Interfacing->*
I have not tried to read this, it looks quite volumnious.

> 9. Advanced TeXmacs
>       Master document
>       Folds and switches
>       Personal style files
>       Macros, Scheme

Not well covered that I can see.

> This is just the outline of the book I'd like to read about TeXmacs. 
> Obviously 
> it's biased to my needs. I don't know if there is any plan to write this 
> kind 
> of documentation. Of course, there is a lot of information in the help 
> files 
> but sometimes is quite cryptic. 

I think one should do things in smaller steps. 

If we could find out something about what a few of the most important
<xxx|...> commands are and describe them, post it to the list and send a
.tm file to Joris.. (I cannot speak for him, I just guess that he would
appreciate such a contribution.)

Actually a good number of commands are documented in Help->Document
Format->Primitive TeXmacs Constructs, but it appears that a lot has
changed since that was written. 

Somebody please correct me: It looks like the internal format has changed
from (function arg1 arg2) to <function|arg1|arg2>, which allows arg_n to
contain spaces without the need to enclose the args in quotation marks.

I have not yet found any documentation of a file with similar
capabilities as ".emacs", although there appears to be some references
to such a capability. (Can't remember where, could be a false
impression.)

> I try to add interesting comments to this list but I have two big barriers: 
> 1) 
> My knowledge of TeXmacs is quite limited and 2) my mastery of English is 
> ridiculous :-(  

There are others here that can help fixing the details. If they don't
bother to do so, they deserve manuals with ridiculous language...  

Regards, Enrique