1.Use TeXmacs

One of the best ways to contribute to GNU TeXmacs is by using it a lot, talk about it to friends and collegues, and to report me about bugs or other unnatural behaviour. Please mention the fact that you wrote articles using TeXmacs when submitting them. You can do this by putting the made-by-TeXmacs tag somewhere inside your title using Text→Title→TeXmacs notice.

Besides these general (but very important) ways to contribute, your help on the more specific subjects below would be appreciated. Don't hesitate to contact us if you want to contribute to these or any other issues. In the Help menu you can find documentation about the source code of TeXmacs, its document format, how to write interfaces with other formats, and so on.

2.Making donations to the TeXmacs project

Making donations to TeXmacs through the SPI organization

One very important way to support TeXmacs is by donating money to the project. TeXmacs is currently one of the projets of SPI (Software in the Public Interest; see http://www.spi-inc.org). You may make donations of money to TeXmacs via this organization, by noting on your check or e-mail for wire transfers that your money should go to the TeXmacs project. You may also make donations of equipment or services or donations through vendors. See the SPI website for more information. The list of donators is maintained at our website.

Details on how to donate money

To make a donation, write a check or money order to:

and mail it to the following address:

To make an electronic transfer (this will work for non-US too), you need to give your bank the routing number and account number as follows:

Don't forget to note on your check or e-mail for wire transfers that the money should be spent on the TeXmacs projet. In addition you may specify a more specific purpose on which you would like us to spend the money. You may also contact us for a more detailed discussion on this issue.

Important notes

Let the SPI Treasurer (treasurer@spi-inc.org) know if you have problems. When you have completed the electronic wire, please send a copy of the receipt to the above address so there is a copy of your donation. The copy you send to the treasurer is important. You may also want to contact the TeXmacs team in order to make sure that the money arrived on the TeXmacs account.

Note: The SPI address and account numbers may change from time to time. Please do not copy the address and account numbers, but rather point to the page http://www.spi-inc.org/donations to ensure that donors will always see the most current information.

Donations in Europe can be done through our partner in Germany, ffis e.V. If you are interested in using their bank account (to save international money transfer costs), please check the instructions on http://www.ffis.de/Verein/spi-en.html.

3.Contribute to the GNU TeXmacs documentation

There is a high need for good documentation on TeXmacs as well as people who are willing to translate the existing documentation into other languages. The aim of this site is to provide high quality documentation. Therefore, you should carefully read the guide-lines on how to write such documentation.

3.1.Introduction on how to contribute

High quality documentation is both a matter of content and structure. The content itself has to be as pedagogic as possible for the targeted group of readers. In order to achieve this, you should not hesitate to provide enough examples and illustrative screen shots whenever adequate. Although the documentation is not necessarily meant to be complete, we do aim at providing relatively stable documentation. In particular, you should have checked your text against spelling errors. The more experimental documentation should be put in the incoming directory or on the TeXmacs Wiki.

It is also important that you give your documentation as much structure as possible, using special markup from the tmdoc style file. This structure can be used in order to automatically compile printable books from your documentation, to make it suitable for different ways of viewing, or to make it possible to efficiently search a certain type of information in the documentation. In particular, you should always provide copyright and license information, as well as indications on how to traverse your documentation, if it contains many files.

Warning 1. Don't forget to select Document→Language→Your language for each translated file. This will cause some content to be translated automatically, like the menus or some names of keys. Also, we recommend to run the TeXmacs spell checker on each translated document; this also requires the prior selection of the right document language.

3.2.Using cvs

The present TeXmacs documentation is currently maintained on texmacs.org using cvs (Concurrent Version System). In order to contribute, you should first create an account as explained on

    http://www.texmacs.org/tmweb/download/cvs.en.html

In fact, the cvs system is not ideal for our documentation purpose, because it is not very dynamic. In the future, we plan to create a dedicated publication website, which will allow you to save documents directly to the web. It should also allow the automatic conversion of the documentation to other formats, the compilation of books, etc.

3.3.Conventions for the names of files

Most documentation should be organized as a function of the topic in a directory tree. The subdirectories of the top directory are the following:

devel

Documentation for developers.

examples

Examples of TeXmacs documents.

incoming

Incoming documentation, which is still a bit experimental.

main

The main documentation.

meta

How to write documentation and the compilation of documentation.

Please try to keep the number of entries per directory reasonably small.

File names in the main directory should be of the form type-name.language.tm. In the other directories, they are of the form name.language.tm. Here type is a major indication for the type of documentation; it should be one of the following:

adv

Documentation for advanced users.

man

For inclusion in the TeXmacs manual.

tut

For inclusion in the TeXmacs tutorial.

You should try to keep the documentation on the same topic together, regardless of the type. Indeed, this allows you to find more easily all existing documentation on a particular topic. Also, it may happen that you want to include some documentation which was initially meant for the tutorial in the manual. The language in which is the documentation has been written should be a two letter code like en, fr, etc. The main name of your file should be the same for the translations in other languages. For instance, man-keyboard.en.tm should not be translated as man-clavier.fr.tm.

3.4.Copyright information & the Free Documentation License

All documentation on the texmacs-doc site falls under the GNU Free Documentation License. If you write documentation for TeXmacs on this site, then you have to agree that it will be distributed under this license too. The copyright notice

should be specified at the end of each file. This should be done inside the tmdoc-license macro, in a similar way as at the end of the present document. When automatically generating a printed book from several documentation files, this will enable us to include the license only once.

You keep (part of) the copyright of all documentation that you will write for TeXmacs on the official texmacs-doc site. When you or others make additions to (or modifications in, or translations of) the document, then you should add your own name (at an appropriate place, usually at the end) to the existing copyright information. The copyright notice should be specified using the tmdoc-copyright function just before the license information at the end of the document. The first argument of this function contains a year or a period. Each remaining argument indicates one of the copyright holders. When combining (pieces of) several documents into another one, you should merge the copyright holders. For cover information (on a printed book for instance), you are allowed to list only the principal authors, but a complete list should be given at a clearly indicated place.

3.5.Traversing the TeXmacs documentation

As a general rule, you should avoid the use of sectioning commands inside the TeXmacs documentation and try to write small help pages on well identified topics. At a second stage, you should write recursive “meta help files” which indicate how to traverse the documentation in an automatic way. This allows the reuse of a help page for different purposes (a printed manual, a web-oriented tutorial, etc.).

The tmdoc style provides three markup macros for indicating how to traverse documentation. The traverse macro is used to encapsulate regions with traversal information. The branch macro indicates a help page which should be considered as a subsection and the continue macro indicates a follow-up page. Both the branch and the continue macro take two arguments. The first argument describes the link and the second argument gives the physical relative address of the linked file.

Typically, at the end of a meta help file you will find several branch or continue macros, inside one traverse macro. At the top of the document, you should also specify a title for your document using the tmdoc-title macro. When generating a printed manual from the documentation, a chapter-section-subsection structure will automatically be generated from this information and the document titles. Alternatively, one might automatically generate additional buttons for navigating inside the documentation using a browser.

3.6.Using the tmdoc style

Besides the copyright information macros and traversal macros, which have been documented before, the tmdoc style comes with a certain number of other macros and functions, which you should use whenever appropriate:

key

This macro is used to indicate keyboard input like C-x C-s. The specialized macros kbd-gen, kbd-text, kbd-math, kbd-symb, kbd-big, kbd-large, kbd-ia, kbd-exec and kbd-table are used for keyboard input corresponding to a specific type of action or mode. For instance, kbd-math corresponds to keyboard shortcuts for mathematical operations, such as A-f, which starts a fraction.

menu

This function with an arbitrary number of arguments indicates a menu like File or Document→Language. Menu entries are automatically translated by this function.

markup

This macro is used in order to indicate a macro or a function like section.

tmstyle

This macro indicates the name of a TeXmacs style file or package like article.

tmpackage

This macro indicates the name of a TeXmacs package like std-markup.

tmdtd

This macro indicates the name of a TeXmacs d.t.d. like number-env.

Notice that the contents of none of the above tags should be translated into foreign languages. Indeed, for menu tags, the translations are done automatically, so as to keep the translations synchronized with the translations of the actual TeXmacs menus. In the cases of markup, styles, packages and d.t.d.s, it is important to keep the original name, because it often corresponds to a file name.

The following macros and functions are used for linking and indexing purposes, although they should be improved in the future:

simple-link

This macro takes an URL x as argument and is a hyperlink with name and destination x.

hyper-link

This macro is a usual hyperlink.

concept-link

This macro takes a concept as argument. Later on an appropriate hyperlink might be created automatically from this and the other documentation.

only-index

Index a simple string.

def-index

Definition of a new concept; the text is printed in italic and indexed.

re-index

Reappearance of an already defined concept; the text is printed in roman and put in the index.

The following tags are also frequently used:

icon

Link to an icon in a central directory like $TEXMACS_PATH/doc/images/pixmaps.

screenshot

Link to a screenshot. The actual screenshots are stored in a central directory like $TEXMACS_PATH/doc/images/screenshots.

scheme

The Scheme language.

cpp

The C++ language.

framed-fragment

For displaying a piece of code in a nice frame.

scheme-fragment

For multi-paragraph Scheme code.

cpp-fragment

For multi-paragraph C++ code.

tm-fragment

For a piece of TeXmacs markup code in Scheme format.

scheme-code

For a short piece of Scheme code.

cpp-code

For a short piece of C++ code.

descriptive-table

For descriptive tables; such tables can be used to document lists of keyboard shortcuts, different types of markup, etc.

The tmdoc style inherits from the generic style and you should use macros like em, verbatim, itemize, etc. from this style whenever appropriate.

4.Internationalization

The support of a maximal number of foreign languages is another major challenge in which your help would be appreciated. Making the translations to support a new language usually requires several days of work. We therefore recommend you to find some friends or collegues who are willing to help you.

The procedure for adding a new language is as follows

• You copy the file english-new.scm to english-yourlanguage.dic in langs/natural/dic and fill out the corresponding translations. You may want to use Andrey Grozin's dictionary tool at

      http://www.texmacs.org/Data/dictool.py.gz

  In order to use it, may sure that Python is installed on your system, download the file, gunzip it, make it executable and run it.

• You tell me about any special typographical rules in your language and handy keystrokes for producing special characters.
• I take care of the hyphenation and typographical issues, but you test them.
• If you have enough time, you may also consider the translation of (part of) the existing documentation.

Of course, the support for languages get out of date each time that new features are added to TeXmacs. For this reason, we also maintain a file miss-english-yourlanguage.dic with all missing translation for your language, once that it has been added. Please do not hesitate to send inclomplete versions of english-yourlanguage.dic or miss-english-yourlanguage.dic; someone else may be willing to complete them.

5.Writing data converters

If you are familiar with TeX, LaTeX, Html, Xml, Sgml, Mathml, Pdf, Rtf, or any other frequently used data format, please consider contributing to writing good converters for one or more of these formats. In Help→Source code→Data format you will find details about the TeXmacs data format and in Help→Source code→Data conversion we give some suggestions which might be helpful for these projects.

6.Porting TeXmacs to other platforms

Currently, TeXmacs is supported on most major Unix/X-Window platforms and a Windows port should be ready soon. Nevertheless, your help is appreciated in order to keep the existing ports working. Some remaining challenges for porting TeXmacs are:

• A native port for MacOS-X.

• Ports to PDAs, first of all those which run Linux. It should be noticed that, with the current support for Freetype, TeXmacs no longer depends on TeX/LaTeX for its fonts. We expect it to be possible to obtain a reasonable ports for TeXmacs on PDAs with 32Mb and at least 100MHz clock-speed. Of course, one also needs to customize the menus and/or icon bars, but this should not be hard.

  TeXmacs ports to PDAs would be particularly interesting in combination with the available plug-ins for doing scientific computations.

7.Interfacing TeXmacs with other systems

It is quite easy to write interfaces between TeXmacs and computer algebra systems or other scientific programs with structured output. Please consider writing interfaces between TeXmacs and your favorite system(s). TeXmacs has already been interfaced with several other free systems, like Giac, Macaulay 2, Maxima, GNU Octave, Pari, Qcl, gTybalt, Yacas. Detailed documentation on how to add new interfaces is available in the Help→Interfacing menu.

8.TeXmacs over the network and over the web

With the current technology of mutator tags, it should be quite easy to write a plug-in for TeXmacs for doing instant messenging or live-conferencing. We are very interested in people who would like to help with this. The same techniques might be used for collaborative authoring and educational purposes.

Besides live conferencing, we are also interested by people who are willing to program better integration of TeXmacs with the web. As a first step, this would require an internal C++ plug-in based on Wget or Curl for accessing web-pages, which supports cookies, security, etc. At a second stage, these features should be exploited by the Html converters. At the last stage, one might develop more general web-based services.

9.Become a TeXmacs developer

Apart from the kind of contributions which have been described in more detail above, there are many more issues where your help would be appreciated. Please take a look at our plans for the future for more details. Of course, you should feel free to come up with your own ideas and share them with us on the texmacs-dev@gnu.org mailing list!