Contributing to the LaTeX reference manual

The LaTeX2e Unofficial Reference Manual aims to provide a reference for the user-level commands of LaTeX. For more information, see the home page.

You can help

We welcome bug reports or suggestions. Please email to latexrefman@tug.org (subscribe, archive).

If you would like to contribute more systematically, that's great. Here are some things a person could tackle, following the guidelines below for writing entries.

• Reading through the document will turn up plenty of places where you can make an improvement. For example, you can search in the (sole) source file latex2e.texi for comments prefixed with "xx". That is how we note areas that need more work.
• Work through the LaTeX3 newsletters to find changes that apply.
• Look through keeptrack.csv. It lists all of the commands in the LaTeX source. Each has a status: done for commands already mentioned, todo for ones that we will do, notdoing for ones that we will not do (usually because they are not user-level commands), and other for uncharacterized commands. Grab a todo command and have a whack.

Write an entry

Each entry is different but over time we have worked out some general guidelines. A good example is the one for \footnote.

• Begin with a synopsis. It gives the syntax. Here is \footnote's.

  Synopsis, one of:
    \footnote{text}
    \footnote[number]{text}

  Note that it lists separately the command version with and without the optional number. It does not use square brackets to indicate options because that would be using the brackets both as characters that appear in the LaTeX input, and as metacharacters.
• Follow with a one or two sentence description. The \footnote command description starts with "Place a footnote text at the bottom of the current page."
• Next is an example. Give a common use, ideally one that helps explain why a person would use this command. It should be copy-and-pasteable because that is what people do with reference material.
• Then give a full explanation. Say all you can reasonably say, including any gotcha's (footnote discusses what happens inside a minipage). A reference is not a tutorial so you don't need to start from first principles; if something uses LR mode or involves some tricky stuff with glue then just say that. You might search the web for questions that people have asked about this command, to see if there are fine points that the entry should cover (good sources are the TeX-LaTeX Stack Exchange, texhax, and comp.text.tex). If convenient, furnish any parameter values that are in the standard classes. For instance, \footnote has \footnoterule and \footnotesep. Consider giving the values of any magic numbers in the standard packages.
• Some entries end with more examples. Following the full explanation, you may want to give examples of any fine points, particularly ones that often give authors trouble or that are often asked-for applications.
• Some entries give full descriptions of arguments. For most commands the arguments are simple, but for some they merit more complete coverage.
• Define index entries, with @cindex for the general index and @findex for macro and other code names. Start general index entries with a lowercase letter (“font”, unless the word would normally be capitalized (“Knuth”). Code entries should be spelled exactly like the identifier, in all cases (do not capitalize at the beginning of a sentence). It's best to put index entries just after the sectioning command, or at the beginning of the relevant paragraph for more specific references.

Examples are particularly important since they are what most people look for. Here are a few guidelines: (1) Test all examples, no matter how small. (2) Use best practices, both coding and typographic practices, such as including the \, space in $\int x\, dx$. (3) There is such a thing as too many examples. Perhaps two or at most three is enough. (4) Keep them brief. (5) Make them interesting, or at least sensible. If you are illustrating an aspect of formula writing then use an actual formula. For text, use an example from an actual document if reasonable but in any event try to minimize "foo" and "bar." And, "baz" is right out.

Finally, of course we must follow the source license with respect to quoting and attribution.

Send it in

The easiest way to start is to put your suggestion in plain text (or Texinfo is even better, if you wrote it that way; but Texinfo is not required) and email the list. We will mark it up for insertion in the document source.

Making a ready-to-insert entry is more involved and we should have a conversation when you want to do that, but here is an overview. First get the files (see also the directions on our project page): (i) install Subversion, (ii) create a convenient directory; here we illustrate with /home/jim/src/latexrefman/, and (iii) in that directory run

 svn checkout https://svn.gnu.org.ua/sources/latexrefman/trunk
  

The document source is the single file trunk/latex2e.texi. It is marked up in Texinfo. Decide where to put your new entry. The simplest way to actually enter it is to then copy another entry and edit to suit. (The Texinfo manual has all the information but we try to stay away from any advanced stuff.) Besides inserting the entry, you must also put a pointer to that entry into a menu. Again here, find a similar entry and copy and edit. Finally, compile to output by running make in the trunk directory. Once you have gotten used to marking up entries, if you want write access to the repository then let us know on the mailing list. We'll see about an account.

Coding conventions

Here are a few conventions for working inside the texi file.

• Tags Use @code{..} for code, @file{..} for file names, @code{..} for package names, @samp{..} for examples. Don't forget that curly braces inside examples need to be escaped with at-signs: @code{\macro@{arg@}.
• ChangeLog Update this file before committing to the repository when you make larger changes, such as opening a new node.
• Input formatting Put two lines before a new node. When you are all done writing, use Ctrl-Q to format blocks of text to a uniform width.
• Index Use @PkgIndex{..} to add a package name to the index.
• StructureSee next section

Document structure

Here are a few points concerning how to change the document structure, if need be.

• ConservativenessDon't change the document structure without prior discussion on the mailing list. Changing the structure is a wider change that just modifying an existing entry or adding a new one.
• Backward compatibilityPlease keep in mind that the document is exposed in a split HTML with one page per node here: Unofficial LaTeX2e reference manual. So every time you rename a node, you change the URL of the corresponding page and may break some link done by other people to that page. To ensure backward compatibility, every time you do that create an @anchor{…} to the old name.
• Elementary restructuringPlease keep in mind that the document is translated in several languages. Do not make changes where both the node order is changed and the node content is changed. If you do this, it becomes more difficult for the translators to track down what content change has happened. Do this sort of evolution as two separate changes. If you don't have SVN access to the latexrefman repo, you can create a local SVN or GIT repo, make the sequence of changes there, and then send the corresponding patch files. Or otherwise make the changes as two separate contribution, and wait for the repo update between both.
• Check referencesLast, but not least, whenever you move some material from one node to another, please check whether any reference to the former node has, or not, to be changed to a reference to the latter.