mailing-list for TeXmacs Users

[David Allouche <address@hidden>]

Some comments. Most are only detail, so I do not pretend it's more than my
two cents.

-- General issues --

I think that "previous" and "next" buttons at the top and the bottom of the
pages would make navigation easier.

Cross reference text do not match title of pages. For example, on the page
entitled "Writing a simple text", the cross reference "chapter I.4" points
to a page whose title reads "Chapter 4" while the reference "chapter II.1"
points to a page whose title reads "Chapter 1". Actually this "Chapter 1"
is in part II, but this belonging to part II instead of part I is not
explicited on the page.

Maybe emacs-like shortcuts (like C-x C-s) should be more advertised in the
tutorial.

Since HTML-4.0 there are entities for many useful mathematic symbols:
→ for ->
∑ for \Sum
± for \pm
α for \alpha

You can find a useful table of these at:
http://ansible.xlii.org/quarante-deux/chars.html

Key chords could be boxed using the CSS styles "border-style:solid" and
"border-width:thin". That would make sequences of key chords more readable
and would increase consistency with TeXmacs online documentation.

This is a simple example of boxed text:
<span style="border-style:solid;border-width:thin">Boxed</span>

You can find an excellent online CSS reference at:
http://www.indexdotcss.com

I think that shorthands like "resp." and "w.r.t." should not be used, and
that the complete English expansion should be used instead.

--- Part I ---

-- Chapter 1 --

- Staring TeXmacs -

>You may start TeXmacs by typing
>
>texmacs &

The '&' seems superfluous. Beginners that do not know about starting
processes in the background may get confused by it, and more experienced
users do not need it.

- Understanding TeXmacs window -

I do not think that explaning window manager features like window
decorations belongs in a TeXmacs tutorial. Once again, beginners may get
confused if the screenshot/explanation do not match their window manager
and to experienced users it just lowers the signal/noise ratio.

-- Chapter 2 --

Seems correct to me.


-- Chapter 3 --

I think side-by-side pictures on this page should not be forced using a
table, but instead the flowing should be managed by the browser. When one
uses a narrow window (eg, for quick-reading) all the right picture will be
out of the visible area of the page.

I found a typo, a missing apostroph:

> This means in particular that the editors primitives are dependent on the
> document style                    ^^^^^^^

-- Chapter 4 --

Fine one, no comment.

--- Part II ---

-- Chapter 1 --

A typo, should be "typeset" instead of "typesetted":

> Inside a chapter, there may be other special pieces of text, like
> citations, definitions, theorems, etc. which are typesetted in a
> different way from the main text.                ^^^^^^^^^^

Another typo, although I'm not absolutely positive about this one. I think
it should be "selecting" instead of "select".

> After giving a name to your document, the next thing you usually should
> do is select a document style in [style icon] or Document->style.
        ^^^^^^

A missing markup, "\em" should be in typewriter font.

> The first image indicates the state of the editor after typing \em.

Overall, I think that discussion of structured typography could be made
easier by not using long phrases like "When you finished to type your
section title, you have to move the cursor to the right in order to
indicate that you are finished (and return to the normal text)", but
instead by using a more intuitive phrasing like "When you have typed the
section title, move the cursor to the right to get out of the 'title'
structure". As an added bonus this should help giving the user an intuitive
feeling of the tree-like nature of TeXmacs documents.

-- Chapter 2 --

This one is not really a typo, but it is not really English either.

> The * is used to obtain variants and / in order to obtain negations.

-- Chapter 3 and 4 --

Not yet audited.

--- Seemingly improper TeXmacs behaviour ---

While reading the tutorial I tried some things and noticed that
sometimes TeXmacs did not behave well. These are not related to the
tutorial, instead these are TeXmacs misfeatures.

If one creates a new document, types in some text, then C-x C-s to save the
unamed document, it will saved as "no name" in the directory where TeXmacs
was started. If one then creates another document, types some different
text
and saves it without giving a name, the new document will be saved in "no
name" and overwrite the previous document. Even more, the contents of the
first buffer will be replaced by the contents of the new buffer... So the
first document is completely lost!!! I think TeXmacs should not allow one
to save a document without first giving it a real file name (through the
use the put file dialog).

The Help->About->About document should display the current TeXmacs version.

Maybe <section> and like elements should automatically insert a new line.
That would be really in the spirit of structured typesetting. For example,
think of theorem environments in LaTeX. In US typography, the theorem title
is on the same line as the beginning of the theorem text, while in French
typography, a line break (and thin vertical space) is inserted between the
theorem title and text (as far as I remember, I might be wrong).

--- Left out comments ---

A lot of stylistic corrections. I though I had already made too much detail
remark to not add these. Moreover, since English is not my native language,
I did not feel like making authoritative, and possibly controversial,
phrasing corrections.

--- Conclusion ---

Phew, I'm quite tired of all this careful reading. I'll check the last two
chapters another day.

Do not hesitate to flame me if you think I am doing to much or I am
focusing on insignificant details (given there is such a thing as an
insignificant detail)...

--
                              -- David --