HomeHieroglyphic typesettingHieroglyphic databasesOther hieroglyphic applications
Typesetting Arabic and CopticOther useful Egyptological applications

How to use HieroTex on Mac OS X

If you’ve not yet installed HieroTex on your Mac, please read the installation guide first…

Typesetting hieroglyphs, just a matter of practice!

Congratulations! You’ve managed to install HieroTex on your Mac! Now you’ve already learned how to type some simple hieroglyphs, but of course there is more to explore! Longer texts or advanced features (column writing, shading signs, etc.) are a bit harder to typeset. Just read the HieroTex documentation carefully and you’ll be able to typeset some beautifully Ancient Egyptian texts… It is actually also a good idea to compare the .tex-file of the documentation with the pdf-file of it (both come with the installation files). The documentation itself also uses a lot of advanced typesetting so it can be very instructive to look at the Tex-code.

Unfortunately, typesetting hieroglyphs is not that easy, because you have to type specific codes for each hieroglyph (named after their phonetic value or their Gardiner Code). But you‘ll learn them soon enough after some hours of hieroglyph typesetting. Just look at the following three screenshots I made after some hours of work: screenshot 8 is the Latex-file I've typed and screenshots 9 and 10 are the two first pages of the resulting pdf. Nice, isn‘t it? (For the curious people: it‘s a document with hieroglyphic transcriptions of fragment of some hieratic texts like Papyrus Prisse (‘The Teaching of Ptahhotep’) and Papyrus Ebers (a medical text).

My hieroglyphic typesetting set-up

As you’ve probably already noticed from the above explanation, you’re not just working in one application and one window when typesetting hieroglyphs. The way I work (but here may be other and better ways of course), is the following (screenshot 11). I use 3 windows:

  1. A text file (in TextEdit) with the document I’m editing (here: moller_transcr.htx)
  2. A terminal window to execute the sesh, latex (and dvipdf) commands
  3. The resulting dvi-file in xdvi (when I'm still checking the document on errors or when it’s not yet finished) or the resulting pdf-file in Preview (for the final version of the document)

Indeed, you’ll make adjustments more than you would think. You will soon enough find out that you won’t be able to edit the Latex files without any errors (at least when you’re just starting to learn it). First of all, you can make an error in your hieroglyphic code (e.g. you typed ‘hpr’ instead of ‘xpr’), sesh will abort with an error message which gives you the exact error and the line where it occurred. And when Latex encounters even only one little error (e.g. you forgot to type a closing ‘}’ after a command), it won’t output a dvi-file and you won’t be able to generate the pdf-file (screenshot 12). In such cases, Sesh or Latex will always warn you that there are some errors and they’ll usually tell you exactly what is wrong (e.g. Sesh can give a message like ‘texte non reconnu: hpr, pres de hpr ligne 7’). If needed, abort the running program with ctrl+d, then look what the error was and correct it in your source file, after which you can again run the set of three commands (sesh, latex, dvipdf) to try if your document is now completely ‘bug-free’. Sometimes this can be a long and frustrating process…

Running sesh and latex using a shell script – htx2tex

Using the above method for running sesh, latex and dvipdf is not very useful: typing a couple of commands or copy and paste it every time is certainly not the fastest way to get your hieroglyphs on screen. I’ve only worked this way the first couple of weeks I used HieroTex, because I soon enough found there is a faster and easier way… Therefore, you can use the shell script htx2tex, which combines the different steps in just one command. If you haven’t installed it yet, please return to the installation instructions and install it first.

Now, forget about all those sesh and latex commands, here’s how you have to use the script and how you will be typesetting hieroglyphs from now on (this is the help-page from the script, which can be opened at any time by just typing htx2tex --help in a Terminal window):

This script processes htx-files through sesh, latex (and dvipdf). htx2tex is (c) 2004 Filip Vervloesem (filip.vervloesem@student.kuleuven.ac.be). More information about how to use this script can be found at:


This script is written and tested on Mac OS X 10.3.4 using bash. The following applications need to be installed in order to function: sesh, latex, dvipdf, perl and some common utilities such as grep, sed and awk. It may or may not function on older versions of Mac OS X, in different shells or on other UNIX-based operating systems.

Usage: htx2tex [filename] [output-format] [clean-option]
filename: enter a valid filename ending in .htx
output-format: enter either dvi or pdf
clean-option: enter either clean or noclean

e.g. "htx2tex ct80.htx pdf clean" generates a pdf-file and removes all temporary files used by Latex (e.g. aux-, log-, and tocfiles to name a few).

Note that only the first argument is required. Without a valid filename ending in .htx, the script won't run and prompt a usage reminder. If you do not enter any of the two valid options for the second and third argument, htx2tex will use the default ones, being dvi and noclean.

e.g. "htx2tex ct80.htx" generates a dvi-file and doesn't remove any temporary files, which is the same as "htx2tex ct80.hts dvi noclean".

  1. Now, to get started using this script, navigate in a terminal window to the folder where your .htx-file is located and type htx2tex file.htx. This will run sesh and latex, which gives you a dvi-file as output. This can be opened using xdvi (xdvi file.dvi), if xdvi is installed (it comes as part of Latex usually. If not, you can easily install it with Fink Commander). Xdvi is the fastest way to view your documents because you don’t have to convert them to pdf, which can take a while, especially if you use many images in your document. It also has a ‘Reread’-button, which reloads the dvi-file. This is very convenient after you’ve made some changes: you don’t have to open and close the window every time, just hit the button or type R in xdvi.
  2. Note that you if you do convert the dvi-file to a pdf-file with dvipdf and if you use Preview to view it, you ’ll have to close the pdf-file each time you run htx2tex for a second time (after you have made some changes), otherwise Preview won’t display the changes you’ve made. This is also the reason why viewing the dvi-file in xdvi is easier than the pdf-file in Preview. Please note that you do need Apple’s X11 to be able to run xdvi (which comes as part of tetex I think; if not, you can probably install it with Fink).
  3. The script has the following two options: output-format and clean-options (see description above). If you don’t like all those files created by Latex (e.g. .tex, .aux, etc.), using the clean option will delete them if they’ve become obsolete (i.e. after running latex), and will only leave two files: the original htx-file and the resulting dvi- or pdf-file. noclean will leave the temporary files as they are. For more about these temporary files, see under 4.
    Output-format should be rather straightforward: use dvi if you want to output a dvi-file and pdf if you want a pdf-file. I prefer dvi-files for all editing when the document is not finished yet, because of the easy ‘Reread’-function of xdvi. Also, not deleting the temporary files can speed up the process, because if they are deleted, Latex may need to be run twice every time to get such things as references, indexes etc. right. But when my htx-file is completely finished, I run the script once again using the pdf and clean options, which gives me a pdf-file I can easily share with other people and removes all temporary files, which are now unnecessary (screenshot 13).
  4. The clean option removes all temporary files created by latex, as already said before. Now, when do you have to use it and when not? This option can be used for very simple documents (e.g. only hieroglyphic texts), because you won’t need all the extra files Latex creates. But if you’re using advanced Latex-features such as longtable, references, a table of contents, lists of figures and tables, etc. you’d better not use this option since it will cause latex to generate a lot of errors. Then Latex will need to run a second time (the htx2tex-script detects this automatically and does this for you). This will, of course, slow down the process of creating a dvi/pdf file from your htx-file…
  5. htx2tex also helps you with all sesh-errors: it gives the sign which was not recognised by sesh and the line of the file where it occurs (as sesh does standard), but it will also display that complete line, so you can locate the error more easily in your htx-file. The sign not recognised by sesh is highlighted by two words <ERROR>, so you’ll immediately see it (screenshot 14). The standard sesh-error ‘line number xxx’ on the contrary won’t help you much, because TextEdit doesn’t show line numbers. If you do want to search for a certain line in a htx-file, type view file.htx in a Terminal window and then hit the line number you’d like to see followed by G, e.g. 35G for line 35. This will move the cursor to that line. Type :q if you want to quit view and return to the bash prompt.

I hope the htx2tex script is useful for you, and will save you a lot of time compared with manually entering all the necessary commands… It took me a lot of hours to write and test it, together with a lot of time for learning shell scripting basics. If you have any questions, comments or suggestions concerning htx2tex, don’t hesitate to contact me.

I’m currently further improving htx2tex for making hieroglyphic editing even more straightforward, but the most recent version of the script is not very reliable yet so it’s not yet available for download. (It is version 1.52, the one available here is not yet numbered but it should be something like 0.9 I suppose.) Some features that might be included in the next version available here are:

  • automatic suggestions for unknown signs (e.g. if you typed rmn in your htx-file, sesh will quit with an error, but htx2tex will propose you to use sign D41, which is indeed the Gardinercode of the ideogram rmn).
  • the option to ignore unknown signs (their code will just be printed in Latin alphabet). This is usefull for texts written with WinGlyph, which do sometimes include many signs of the so-called ’extended library’ (i.e. hieroglyphs not in Gardiners signlist and not supported by HieroTex).
  • the option to (partially) correct unknown signs (cfr. previous feature): signs such as G17A (a variant of G17) will be changed into G17 instead of the Latin text G17A.
  • as you might have noticed above: I would like to be able to use WinGlyph-generated files in HieroTex too, but that’s not as easy as thought it was. Although HieroTex and WinGlyph both use the MdC-standard, their implementation is not exaclty the same, so importing a WinGlyph-generated file in HieroTex is likely to result in a lot of errors. So I’m working on a conversion script for Winglyph, MacScribe, TKSesh and other files to HieroTex, but don’t expect to see that soon…
  • another little script that can be used to view any MdC-file: if it’s not in HieroTex’s format, it will be converted first, and then (if it’s an HieroTex-file or converted to one), all Latex headers will be added. So if you just want to type MdC-codes, you don’t have to worry about Latex anymore, because all necessary headers are included: a plain htx-file with only MdC-code will work fine :-)

If you have any other suggestions to improve htx2tex, I’d likie to hear them and I can include them too (if it’s not too difficult of course: e.g. a wysiwyg-interface for HieroTex is something I wouldn’t even know how to make…)

Where to go from here

Now, if you actually want something like the examples in screenshots 9 and 10 (i.e. more than just pages with only hieroglyphs on it), you’ll also have to learn Latex. This is not as easy as today’s word processors (like MS Word or OpenOffice Writer), but it’s definitely worth the effort! You can take a look at the Tex User Group website for some tutorials to start. As an excellent introduction to Tex’s capabilities and its basic functionality's, I can recommend you ‘The not so Short Introduction to LaTeX2e’, which can be downloaded in several languages as pdf-, PostScript- or Tex source file (download the document here). By the way, there are also packages for writing Coptic or Arabic in Latex, which can be also very useful for the Egyptologist. But that’s a whole other story…

Many thanks to…

Finally I want to thank some persons who have tried (and succeeded!) to tackle the compiling/installation problem for me: J. Sabbe, J. Leys and K. Vervloesem. The previous shell script htx2pdf is made by K. Vervloesem, which was a helpful example for me when writing the more advanced htx2tex script. A great help was also the MacAtKul-forum, which was nice place to look for some more experienced people…

©2005 F. Vervloesem.
The author of this page claims no rights on the HieroTex-package, which is © S. Rosmorduc.
Please go to his website for any further information on HieroTex.