mailing-list for TeXmacs Users

[address@hidden]

I just finished a major project (thesis) using TeXmacs, and I wanted to 
share some experiences. The project has about 200 pages and 40 floats. I 
have been using TeXmacs for several years now, and until now regularly used 
TeXmacs for the "draft" phase of various documents (for which it really 
shines), and used LaTeX for the final typesetting. However, this time I 
chose to use TeXmacs from the beginning to the end. I found myself 
developing so many workaround that I thought I'd share them, in case anyone 
wants to take a similar path, and so that maybe Joris (or someone else who 
knows the sources) can fix some of the bugs.

Don't get me wrong, I like TeXmacs, and it works very well for small 
documents. However, I think TeXmacs can only compete with LaTeX if it 
provides a solid stable foundation that users and publishers can depend on. 
While LaTeX needs a huge amount of work in order to get an acceptable 
workflow, when correctly set up it is rock solid. TeXmacs is easy to get 
used to, but extremely crashy when trying to do non-basic operations. With 
hindsight, I have to say that had I known all the problems I have 
encountered, I had probably chosen LaTeX, from which I know that it is hard 
to get used to, but it is stable. It is very frustrating having to deal with 
mysterious crashes and figuring out workarounds close to the deadline.

Currently it seems that new features are added all the time, such as the 
vector graphics editor. In my opinion TeXmacs has more than enough 
innovative features and flexibility by now to beat any other scientific 
editor, but long-term usability is just bad. With respect to the list below, 
I think that the upmost priority should be to get the existing code as 
stable and fast as possible (in particular for large documents), and to get 
the stylesheet language as solid and as well-documented as possible. 
Otherwise TeXmacs will never get a substantial user base.

That said, this is the list. It is organized in three parts: dangerous 
things than can ruin the output by silently introducing errors, annoying 
things that are just counter-intuitive or take a lot of time getting used 
to, and performance issues that are relevant when editing large documents. I 
loosely ordered the items in order of descending importance.

1) Dangerous things
-------------------

1a) Deleted references: TeXmacs indefinitely remembers references it has 
once seen. If I create a <label>, reference it using <reference> and then 
delete the <label>, the reference is unchanged (even after Document > Update 
> All, multiple times), while it should display "?" instead. This can 
create very hard-to-spot errors in your document. As a workaround, I 
manually opened the .tm file and deleted everything in the <\references> and 
<\auxiliary> sections, which forces TeXmacs to regenerate everything, and 
searched for "?" in the PDF to check if there are any undefined reference. 
However, this should never happen in the first place. Moreover, there should 
be an indicator/warning if there are any undefined references or "cite"s in 
the document.

1b) .tm~ Files: By default, the "File > Load" (BTW, why not "Open"?) dialog 
shows all file types (in fact there is no option to restrict it to TeXmacs 
files, e.g. .tm + .ts). In particular, it shows the .tm files side by side 
with their .tm~ files. It is very easy to mis-click the .tm~ file, which in 
an unfortunate setting may mean that you lose all of your work. TeXmacs 
should either not allow to open .tm~ files at all, hide them by default, or 
at least issue a warning when the user tries to open one.

1c) Page Setup: There are two places where the page size can be set: Under 
File > Page Setup and under Document > Page > Size. At the least, the menu 
should be called "Print setup". Such things sound like minor issues, but 
anyone will FIRST find the prominent "Page setup" menu, change the size 
there, and assume that it did the trick, when all that is changed is the 
print setup. This issue alone cost me 15 hours of re-breaking the whole 
document close to the deadline.

1d) Document > Magnification: This is a similarly dangerous item, which 
should at least issue a warning that it changes the FONT SIZE, i.e. the 
amount of text that fits on a page. This is very easy to confuse with View > 
Shrinking factor. If you are required to submit an 11pt document and 
accidentally mess with the "Magnification" you are in trouble, since TeXmacs 
will display 11pt font size, but it won't be 11pt in print.

1e) Consistency: I do not know how exactly, but I managed to get two 
installations of TeXmacs 1.0.7.10 that work exactly the same, except that in 
one copy the *bold* fonts (and only those) are a tiny bit wider. Therefore 
headings (and figures for captions) wrap differently. I have no idea if the 
font was changed recently or if the issue is caused by the setup, but in 
order to be exchangeable TeXmacs should make absolutely sure that documents 
look 100% the same when compiled on different systems (maybe use a checksum 
on the font files?). This one took me one day to figure out.

1f) Sums & Integrals: There seems to have been a semantic change with 
respect to sums and integrals, which are now considered as "functions" (i.e. 
they have an argument), rather than just a symbol. This introduced a nasty 
behavior: If one creates an integral (say 
<big-around|<int>|<rsub|0><rsub|1>xyz>), puts the cursor at the end and 
presses "backspace" in order to delete the x, the <int> sign at the front is 
deleted instead! This is actually very easy to miss if you press "backspace" 
multiple times, e.g. in order to delete multiple characters, and corrupts 
the formulas. Instead, the last character should be deleted.

1g) PDF Export: Embedded raster images (especially black & white) look ugly 
in the exported PDF. They seem to be compressed as very low-quality JPG, 
with clearly visible JPEG artifacts especially in purely black/purely white 
regions. The only workaround is to export as PS and convert to PDF manually 
using Ghostscript:

gswin32c -sPAPERSIZE=a4 -sDEVICE=pdfwrite -q -dBATCH -dNOPAUSE -dSAFER 
-dPDFX -dPDFSETTINGS=/prepress -dAutoFilterColorImages=false 
-dColorImageFilter=/FlateEncode -dAutoFilterGrayImages=false 
-dGrayImageFilter=/FlateEncode -sOutputFile=thesis.pdf -c save pop -f thesis.ps

There should be a menu item to change the "PS to PDF" command, and a better 
preset.

1h) Document > Update: One of the things that annoy me most when using LaTeX 
is that it doesn't automatically
 perform another run if it is required in order to get all the references 
right. However, LaTeX at least issues a warning. Using TeXmacs there is no 
warning, but the same annoying process of Document * click * Update * click 
* all * wait * Document * click * Update * click * etc. about 5 times in a 
row to be sure that all references are up-to-date. In my opinion, TeXmacs 
should automatically perform as many runs as required so that the labels do 
not change anymore.

1i) Breaking of inline math: Inline formulas that are wrapped around a line 
ending are just plain ugly. For this reason LaTeX does not wrap them by 
default, and issues an "overfull hbox" warning instead. TeXmacs wraps them 
quietly, which requires to manually check every single line if it contains a 
silently wrapped inline formula.

1k) Style files: I use a custom macro package for shortcuts, pretty 
formatting of algorithms, etc. All documents are in a Subversion repository, 
so it regularly happens (by an "svn update") that a style file changes 
without TeXmacs noticing (TeXmacs is not running during the "svn update"). I 
regularly found TeXmacs marking "undefined macros" in the main document, 
when they were cleary defined in the package file. It took me about 2 months 
to figure out that the styles need to be refreshed using "Tools > Update > 
Styles", and that restarting TeXmacs does NOT help. Why this doesn't happen 
automatically when TeXmacs is restarted is completely counter-intuitive. 
However, it may mess up your whole document, or make it use old macros, 
which both is very dangerous.


2) Annoying things
------------------

2a) Stylesheet Language: I had to implement some extensions using the 
stylesheet language. If one goes one step beyond the standard functionality, 
TeXmacs crashes at the blink of an eye. I found myself spending about 20% of 
the time figuring out a solution for a problem, and then spending 80% of the 
time trying 4 other solutions until I find one that doesn't crash TeXmacs. 
While LaTeX can also be incredibly tiresome to work with, it is solid as a 
rock. I think if TeXmacs aims at production quality and use in professional 
environment, these issues -- which mostly concern power-users -- desperately 
need to get fixed. Also, there needs to be a clear documentation of the 
evaluation order of the document tree. I spent several hours trying to 
figure out the exact semantics of the various "quote" tags, and eventually 
gave up.

2b) Images: I found that the only image type that can be reliably used in 
Texmcas is EPS written by Ghostscript. PNG tends to crash TeXmacs with a 
memory overflow when exporting to PS, I found myself finally converting all 
raster images to EPS in order to get it to work. EPS files written by other 
applications (e.g. Illustrator) often result in zero-byte .PS files, or .PS 
files that are truncated at the page that contains the EPS. The workaround 
is to run Ghostscript's "eps2eps" on all .EPS files, which creates .EPS 
files that TeXmacs doesn't crash on.

2c) Menu Layout: Generally, I found that TeXmacs menus are laid out in the 
way TeXmacs thinks about the document, not in the way that is most intuitive 
for the user. For example, inserting a float is done via "Format > Page > 
Insertion > Floating Object". I think the "Format" menu is the last place 
that anyone would look, in particular when there is a top-level "Insert" 
menu. Other examples: Tools > Update menu and Document > Update menu with 
similar functions but at different places, the same holds for Edit > 
Preferences > Keyboard and Edit > Preferences > Mathematics > Keyboard.

2d) Bugs when using parts: There is an ugly bug when working with parts that 
causes TeXmacs to reproducibly crash at harmless actions such as selecting 
text across a chapter boundary (see my previous posts on this list).

2e) Yes/No Dialog: Is there any reason for the cumbersome "yes/no" prompt? 
Having to backspace away the "no" and type "yes" is very VERY annoying. Even 
a simple "y"/"n" choice with one keypress would have been more usable. 
Similarly for the strange Qt "yes/no" dialog with the combobox. This should 
just use the default yes/no dialog that is provided by all OS and by Qt.

2f) Extensible brackets: With the automatic extensible brackets there was 
apparantly introduced a bug: When extensible brackets are turned off (Edit > 
Preferences > Keyboard > Mathematics > Use extensible brackets), I am unable 
to insert extensible brackets anymore, even using the toolbox icon ("Insert 
large delimiter"). On the other hand, if I turn extensible brackets on, I 
cannot type left angles anymore ("<" + 5x TAB), it just displays as 
"<left-<langle>-0>". I ended up copy & pasting either the large brackets or 
the angles each time I needed them.

2g) Editing large documents: TeXmacs should be able to view separate parts 
of a document in different windows. Currently this is not possible, which 
makes creating references in large documents very slow: Switch to other part 
* wait * look up label * Switch back to current part * wait * insert label. 
The same holds for copy & pasting. Editing the whole document in one window 
is too slow.

2h) Search: The search function needs a window, which should be non-modal. A 
very common task is to search for all occurrences of a text and change 
something close to that text which cannot be automated (for example search 
for all "TODO" and remove them, fix them, or ignore them). The problem is 
that after typing something, the (apparently undocumented) "Search next" 
shortcut (F3) does not work anymore, and one has to type Ctrl+F + the whole 
search phrase again, every single time. The layout for the "Search" dialog 
box is be quite standard by now (at least on Windows systems): "Match Case", 
"Up/Down", "Find Next", "Cancel". The same holds for the "Search & Replace" 
function.

2i) Windows Version: I couldn't get the Windows version to compile, I ended 
up installing TeXmacs under Ubuntu in a VirtualBox VM, and using a shared 
folder to access the .tm files on the Windows drive.

2k) Redraw errors: When I show the whole document (Part > Show all parts), I 
frequently get redraw errors, where text from the current page and text from 
a completely different section at the end of the document are draw on top of 
each other, resulting in garbage text. The workaround is to force a redraw 
e.g. using "page down" + "page up".

2l) Zooming: Zooming in and out should be seamless e.g. using Ctrl+scroll 
wheel, as is standard in most applications, instead of the "View > Shrinking 
factor" workaround.

2m) TeXmacs frequently loses its configuration and displays the "Welcome to 
your new TeXmacs system" screen.


3) Performance
--------------

3a) Editing anything above about 15 pages in "Paper" mode is just too slow 
to be usable. A part of the problem is that TeXmacs updates the whole 
document at every keypress. Since this cannot always be avoided, e.g. when 
re-wording some sentences in order to get a prettier line wrap, I ended up 
typing text fragments in an external editor, and copy & pasting them into 
TeXmacs as a block in order to avoid the update at every keypress. If views 
the whole document ("Parts > All") and accidentally types a complete word 
(with, say 10 characters), it is faster to kill TeXmacs, restart it and 
reload the document than having to wait for the updates.

3b) Editing paragraphs that contain floats or captions of figures that 
contain images is incredibly slow, even in very small documents.

3c) The same holds for the "Papyrus" mode when some floats are present. The 
unsatisfying workaround is to insert only figures while working with the 
text, and converting them to floats just before creating the final PDF.

Jan