Chronological Thread 

< Chronological >      < Thread >

---

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:
> &#8594; for ->
> &#8721; for \Sum
> &#177; for \pm
> &#945; 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 --
>
>

---

• Many comments on the TeXmacs tutorial, David Allouche, 08/07/2001
  • Re: Many comments on the TeXmacs tutorial, Joris van der Hoeven, 08/10/2001

---

Archive powered by MHonArc 2.6.19.