Contributing to the documentation

1.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.

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.

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.

When selecting the tmdoc document style, the top level Manual menu will appear automatically, together with some additional icons. The most important tags for documentation purposes can be found in this menu.

Warning 1. Don't forget to select DocumentLanguageYour 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.

2.Using SVN

The present TeXmacs documentation is currently maintained on texmacs.org using SVN. In order to contribute, you should first create an account as explained on

    https://www.texmacs.org/tmweb/download/svn.en.html

In fact, SVN 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.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:

about

Various information about the TeXmacs system (authors, changes, etc.).

devel

Documentation for developers.

main

The main 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:

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.

4.Specifying meta information for documentation files

Appropriate meta data for TeXmacs documentation can be entered from the ManualMeta data menu. In particular, you should specify a title for each documentation file using ManualMeta dataTitle, or by directly clicking on the Title button on the focus bar after creating a new document with the tmdoc style.

All TeXmacs documentation falls under the GNU Free Documentation License. If you want your documentation to be included in TeXmacs, then you have to agree that it will be distributed under this license too. The license information

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".

should be specified at the end of each file. This can be done by clicking on ManualMeta dataGNU FDL.

In a similar manner, you may add a copyright notice by clicking on ManualMeta dataCopyright. You keep (part of) the copyright of any documentation that you will write for TeXmacs. 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 first argument of the tmdoc-copyright macro contains a year or a period of years. 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.

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. It can be inserted using the Traverse entry in the ManualTraversal or menu. The branch and extra-branch macros indicate help pages which should be considered as a subsection and an appendix respectively, whereas the continue macro indicates a follow-up page. Each of these macros should be used inside a traverse environment and each of these macros takes 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, as described before. 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.

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.

Notice that the tmdoc style inherits from the generic style, so you should use macros like em, verbatim, itemize, etc. from this style whenever appropriate. In particular, when documenting program code, you should use InsertProgramInline code and InsertProgramBlock of code in order to mark such pieces of code.

6.1.Explanations of macros, environment variables, and so on

The main environment which is used for explanations of macros, environment variables, Scheme functions, etc. is inserted using the Explanatory item entry of the ManualExplain and menus. The environment comes with two arguments: the first argument consists of the concept or concepts to be explained, and the second one contains the actual explanation. A typical example would be the following:

<demo-tag|body>

<demo-tag|extras|body>
(short and long versions of a demo tag)

The demo-tag is used for demonstration purposes and decorates the body argument. An optional argument extras can be given with details on the way to decorate the body.

In this example, we used ManualExplainTeXmacs macros twice in order to insert the macros to be described. We also used ManualExplainSynopsis in order to give a short description of the tags (in grey). In a similar way, one may use ManualExplainEnvironment variable in order to describe an environment variable. Another example is:

(foo-bar K x)

The function foo-bar computes the foo-bar transform of the operator K and applies it to x.

In this example, we notice that all Scheme code was encapsulated into scm tags (see InsertProgramInline codeScheme) and arguments were tagged using scm-arg.

6.2.Graphical user interface related markup

The following markup elements can be used in order to describe various graphical user interface elements, such as keyboard shortcuts, menus or icons.

shortcut

This macro is used to indicate a keyboard shortcut for a Scheme command. For instance, the shortcut for (new-buffer) is ?.

key

This unary macro is used for explicit keyboard input. For instance, when giving A C-b return as argument, the result is Shift+ACtrl+BReturn.

menu

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

submenu

Consider the following sentence:

“You may use the Load and Save entries of the File menu in order to load and save files.”

In this example, the menu entries Load and Save were marked using the submenu tag, which takes the implicit File menu as its first invisible argument. This invisible argument is still taken into account when building the index (for instance). In a similar way, we provide subsubmenu and subsubsubmenu tags.

icon

Can be used in order to specify one of the TeXmacs icons, such as and . The macro takes one argument with the file name of the icon (the full path is not needed).

screenshot

Similar to the icon tag, but for screenshots.

cursor

This macro can be used to indicate a cursor position, as in .

small-focus, small-envbox

This macro can be used for indicating the visual aids around the current focus and the further outer context (e.g. ), in the case of inline elements.

big-focus, big-envbox

Block versions of small-focus and small-envbox.

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.

6.3.Common annotations

The ManualAnnotate and menus contain the following useful macros for common annotations. You should use them whenever appropriate.

markup

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

src-arg

This macro should be used in order to indicate macro arguments such as body.

src-var

This macro is used for the indication of environment variables such as font-size.

src-length

This macro is used in order to indicate a length such as 12em.

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.

6.4.Miscellaneous markup

Some other potentially useful macros are the following:

tm-fragment

For indicating some TeXmacs document fragment. This macro is especially useful for TeXmacs source code, as in

<assign|red-text|<macro|body|<with|color|red|body>>>

In this example, we used the keyboard shortcut Meta+- in order to deactivate the source code inside an active outer document.

descriptive-table

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