Bing Tan Resume News Calendar Publications Research Group Courses Links Pictures

jemdoc – cheatsheet

Basic formatting

Blocks

Code block syntax
~~~
{Optionally empty title}{Optionally empty highlight mode}
Code block with monospaced text.
~~~
Information block

Omit the second pair of braces in the first line of the block (or omit the whole first line altogether if you don't want a title) and you will get an information block. All the usual conventions apply in here.

Headings and lists

Headings are defined by starting a line with =.

Lists are defined with - for bulleted lists, . for numbered lists and : for lists of definitions. Here is some code and the resulting list:

- Bullet level one
    -- Bullet level two

. Number level one
    .. Number level two
    .. Number level two (again)

: {jemdoc} light markup
: {asciidoc} a great alternative, but more complicated

  • Bullet level one

    • Bullet level two

  1. Number level one

    1. Number level two

    2. Number level two (again)

jemdoc

light markup

asciidoc

a great alternative, but more complicated

Preventing matches

Other stuff

These are some extended syntax options that may come in useful.

Left aligned image blocks

As seen here, for example, left-aligned image blocks place an image and allow ordinary jemdoc marked-up text to flow around the right-hand side.

Left-aligned image block syntax
~~~
{}{img_left}{FILENAME.IMG}{alt text}{WIDTHpx}{HEIGHTpx}{IMGLINKTARGET}
Ordinary jemdoc markup goes here.
~~~

All arguments may be left blank, though you should specify an image filename, and alt text should be descriptive for reasons like those given by Wikipedia.

Raw blocks

When placing large amounts of raw html, you should use a raw block instead of {{inline html escaping}}. As well as cleaner syntax, raw blocks will avoid having <p> tags in the wrong places.

Raw block syntax
~~~
{}{raw}
Any text here will be copied straight to the output file without processing.
~~~

Other character sets

Here's a quick example of how to include text in a language with a different character set.

To include Korean (한국말), use something like this:

{{<span lang="ko" xml:lang="ko">}}한국말{{</span>}}

(Let me know if you need better support for your language.)

Including other files

The line

#include{otherfile.jemdoc}

will include the contents of otherfile.jemdoc as if the contents were actually in the ordinary input file (that is, with full jemdoc substitutions). The line

#includeraw{otherfile.html}

will copy the contents of otherfile.html verbatim to the current position in the output file (that is, without any jemdoc substitutions).

jemdoc – html changes

jemdoc has a built-in default configuration. This configuration includes the particular html tags used when producing html. If you wish to adjust the html that jemdoc produces, you can provide a configuration file to override the built-in defaults.

Example html change

Suppose you wanted to add Google Analytics tracking to your website. That requires adding a short section of html before the </body> tag.

First, find out which block needs to be changed by using

jemdoc --show-config

This prints the default html configuration. From this, the relevant configuration block (the one which includes the </body> tag) has a title [bodyend], and looks like

[bodyend]
</body>
</html>

Create a new file mysite.conf, say, and put a new [bodyend] block inside it. The new file looks like this:

[bodyend]
<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
</script>
<script type="text/javascript">
_uacct = "UA-0000000-0";
urchinTracker();
</script>
</body>
</html>

Include your new configuration file, with the -c option (more details here):

jemdoc -c mysite.conf index.jemdoc

This will pull in the new [bodyend] block from mysite.conf, but otherwise work as before.

jemdoc – latex equations

jemdoc includes support for LaTeX equations. LaTeX source embedded in jemdoc files is processed by calling latex and dvipng (which must both be available for this feature). Resulting PNG images are then placed on the web page. Equations are typeset using pure LaTeX.

jemdoc equation support relies on several pieces, any of which may break. No guarantees! Support may be limited.

Inline equations

The conjugate function \(f^\star(y) = \sup_{x \in X}(y^Tx - f(x))\) appears here inline, and is in the variable \(y\). Dollar signs ($) surround the LaTeX equation in the jemdoc source.

Syntax
The sample function $f^\star(y) = \sup_{x \in X}(y^Tx - f(x))$
appears here inline, and is in the variable $y$.

Equations on separate lines

To render an equation on its own line, use backslash-escaped round brackets (\( and \)). For example, the identity

\[ (I + XY)^{-1} = I - X(I + YX)^{-1}Y \]

is typeset on its own line. Yes, round brackets instead of square brackets — this is to avoid a conflict with ordinary square brackets that are escaped to avoid being a link. Sorry.

Syntax
The identity
\(
    (I \+ XY)^{-1} = I - X(I \+ YX)^{-1}Y
\)
is typeset on its own line.

Here, the line breaks (and other whitespace) are ignored. As always, the exact formatting details can be adjusted using CSS.

Notes

\[ f(x) = \left\{ \begin{array}{ll} 3, & x \leq 0 \\ 5, & x > 0. \\ \end{array}\right. \]

Link Example

You can control the behavior of a link: by default the link opens in a new web broswer tab, but by putting a slash (/) character at the beginning of the link address you can make it open in the current web broswer tab.

For example, [mathjax.html] opens in a new web broswer tab, but [/mathjax.html] opens in the current web browser tab. The link opening in a new tab is useful for linking an external website (like http://www.google.com), whereas the link opening in the current tab is useful for liking your jemdoc page (such as the page linked as a jemdoc menu item on the left panel).

Unlike the link in the main text, a jemdoc menu item link on the left panel opens in the current tab by default, because you want to stay in the same tab while navigating menu items. However, you can override this default behavior and make it open in a new tab by putting a backslash (\) character in the beginning of the link of the menu item. This is useful when putting an external website as a menu item. See this usage in “Open in New Tab” menu item on the left panel, which is defined in MENU file.

MathJax Example

In this modified version of jemdoc, a LaTeX equation block can be typed in as

\[ \nabla \cdot \mathbf{D} = \rho_f\\ \nabla \cdot \mathbf{B} = 0,\\ \nabla \times \mathbf{E} = -\frac{\partial\mathbf{B}}{\partial t}\\ \nabla \times \mathbf{H} = \mathbf{J}_f - \frac{\partial\mathbf{D}}{\partial t}. \]

You can also align equations using LaTeX's aligned block:

\[ \begin{aligned} \nabla \cdot \mathbf{D} &= \rho_f\\ \nabla \cdot \mathbf{B} &= 0\\ \nabla \times \mathbf{E} &= -\frac{\partial\mathbf{B}}{\partial t}\\ \nabla \times \mathbf{H} &= \mathbf{J}_f - \frac{\partial\mathbf{D}}{\partial t}. \end{aligned} \]

To number the equation block, wrap the equations with LaTeX's equation block:

\[ \begin{equation} \begin{aligned} \nabla \cdot \mathbf{D} &= \rho_f\\ \nabla \cdot \mathbf{B} &= 0\\ \nabla \times \mathbf{E} &= -\frac{\partial\mathbf{B}}{\partial t}\\ \nabla \times \mathbf{H} &= \mathbf{J}_f - \frac{\partial\mathbf{D}}{\partial t}. \end{aligned} \end{equation} \]

Instead, you can use LaTeX's align (not aligned) block to number the individual equations:

\[ \begin{align} \nabla \cdot \mathbf{D} &= \rho_f\label{eq:D}\\ \nabla \cdot \mathbf{B} &= 0\label{eq:B}\\ \nabla \times \mathbf{E} &= -\frac{\partial\mathbf{B}}{\partial t}\label{eq:E}\\ \nabla \times \mathbf{H} &= \mathbf{J}_f - \frac{\partial\mathbf{D}}{\partial t}\label{eq:H} \end{align} \]

You can also type inline equations as \(A x = b\). Referencing equations is done as Eqs. \(\eqref{eq:E}\) and \(\eqref{eq:H}\).

jemdoc – add a menu

jemdoc provides an easy way to add a ‘menu’ like the one you see at the left of this page. You should create a file called MENU, for example, in the current directory. This website's MENU looks something like this:

jemdoc
    home                [index.html]
    download            [download.html]
    revision history    [revision.html]
    contact             [contact.html]

user's guide
    cheat sheet         [cheatsheet.html]
    using               [using.html]

goodies
    add a menu          [menu.html]
    other stuff         [stuff.html]

To use the menu, start the first line of each source file with a special comment like this one:

# jemdoc: menu{MENU}{index.html}

(Replace index.html with the name of the relevant html page.) This will add a menu from the file called MENU, and underline and darken the menu entry corresponding to index.html.

Relative paths

Optionally, include a prefix which instructs jemdoc where the root of the menu is located relative to a particular page.

# jemdoc: menu{MENU}{pageinsubdir.html}{prefix}

A note on menu widths

jemdoc will create menu entries that do not wrap. If you have a particularly long title, or menu item, insert manual linebreaks using \n in your MENU file. Multi-line menu items will (by default) have their second and subsequent lines slightly indented.

jemdoc – modelines

jemdoc includes a mechanism for specifying options inside a source file. It is called a modeline, after the same concept in vim. To use a modeline, start your jemdoc source file (on the first line) with the exact string # jemdoc:. Follow this string with one or more modeline options, separated with commas (and any amount of white space).

Multiple modelines can be included if they are all at the beginning of the file, and start with the same string. The modeline can be omitted altogether.

Modeline options

General

Extras

Footers

Equations

Examples

This page
# jemdoc: menu{MENU}{modelines.html}, showsource
Use a different stylesheet altogether
# jemdoc: nodefaultcss, addcss{custom.css}
Combine various options
# jemdoc: nodefaultcss, addcss{custom.css}{another.css}
# jemdoc: showsource, addcss{yetanother.css}

jemdoc – tables

jemdoc includes preliminary support for tables.

Table syntax
~~~
{}{table}{TABLENAME}
first entry  | another entry ||
as many rows | as you like   ||
bottom row   | last entry
~~~

TABLENAME should either be replaced with a name — which becomes the table's css id — or be omitted.

Notes

Example

country population people per square km
Canada 33 million 3.2
中华人民共和国
 1300 million 140
Kingdom of Denmark 5.5 million 130
New Zealand 4.3 million 15
United States of America 300 million 31

Underscore Example

Like bold and italic, underscore can be used for emphasis in this modified version of jemdoc. Useful for highlighting different parts of a bibliography item as:

1. First Author, Second Author, and Corresponding Author, “Amazing Paper,” High-impact Journal, vol. 1, pp. 1–10 (2014).

jemdoc – running jemdoc

Make sure Python is installed, put jemdoc in your path somewhere, type in your file, and run

jemdoc index.jemdoc

This will use a default configuration for the html elements, and create an index.html.

Even simpler, you can omit the extension, and jemdoc will still process the index.jemdoc file, as in

jemdoc index

CSS

You will need to provide a CSS file on your server. By default it should be called jemdoc.css. Here is an example jemdoc.css file: download it and place it in the same directory as your html files. (Or customize it, or start from scratch!)

Change the configuration

To choose a different output file, use -o:

jemdoc -o html/index.html index

You can specify a different output directory with -o:

jemdoc -o html/ index

This will instead output to html/index.html.

To change the html configuration (details here), use -c:

jemdoc -c mysite.conf index

Command line options may be combined. For example, the following command will use mysite.conf, reading syntax from index.jemdoc and outputting to html/index.html:

jemdoc -c mysite.conf -o html/ index

Other command line options

To check which version of jemdoc you are using, run the command

jemdoc --version

To get simple command-line help, you can run jemdoc without arguments, or

jemdoc --help

To show the html configuration (details here), run

jemdoc --show-config

Visitor Stats.