- From: Joris van der Hoeven <address@hidden>
- To: address@hidden
- Subject: Re: Many comments on the TeXmacs tutorial
- Date: Fri, 10 Aug 2001 22:47:58 +0200 (MET DST)
Thanks a lot for your comments.
As has been suggested, I just put a tarball for the tutorial on the
web-pages (
http://www.texmacs.org/Data/TeXmacs-tutorial.tar.gz).
Please send me patches in the case when you have many comments.
As to some issues raised by David:
1. I am reluctant towards using Html <high>.0 for having
the mathematical symbols. Some people may not have
the appropriate browsers. Actually, I already noticed
an old netscape not being able to recognize .png images :(
2. At the moment, I try to keep the tags for keywords and such
simple for the readability of the Html document.
Ultimately, the html tutorial will be generated from
TeXmacs files.
-----------------------------------------------------------
Joris van der Hoeven (address@hidden)
http://www.texmacs.org: GNU TeXmacs scientific text editor
http://www.math.u-psud.fr/~vdhoeven: personal homepage
-----------------------------------------------------------
On Tue, 7 Aug 2001, David Allouche wrote:
>
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 --
>
>
Archive powered by MHonArc 2.6.19.