= Guiding Principles of JML =

1. It should be easy to write
2. It should be easy to read
3. It shouldn't try to do anything that's complicated enough to make 1
   or 2 hard

= Headings =

{{{
= Heading =
== Sub Heading ==
=== Sub-sub-heading ===
}}}

= Grouping of Words =

When you would like to use multiple words and there would be some
abiguity, use curly braces to group the words together. In the section
on [#{Superscript and Subscript}] you could put more text into the
parenthetical with {Curly Braces}

= Text =

*bold*
\italics\
_underline_
-strikethrough-
`monospace`

{{{
multiline monospace
text
}}}

> block quotes
> look just like email, like is natural for writing email
> > and you can have nested block quotes, too!


== Superscript and Subscript ==

^superscript
_subscript


= Lists =

* one thing
* another thing
* a third thing

1. one thing
2. another thing
   a. a sub-item

* a list with more than one paragraph

  Note that you have to be careful with indentation.  You're doing
  something hard and JML is designed to make easy things be easy and
  if you want to get fancier you might have to work.  Note that emacs
  will nicely indent things for you.

* the second item in this list

Lists may start on the line beginning or not.  Definition lists
contain a colon delimeter

* foo: this is the definition of foo
* bar: and this is the definition of bar

- you can also use dashes for unordered lists
- like this one


= Links =

[/foo] -> <a href="/foo">/foo</a>
[The example website http://example.com]
[link to the Heading section #Heading]
[link to the Sub Heading section #{Sub Heading}]

Use of links by themselves or accompanied only by "see" in ()s are
used to markup the previous word:

 I have been using `webob_view` (http://k0s.org/hg/webob_view)

 I like wikipedia (see http://wikipedia.org)

Results in: 

 I have been using <a href="http://k0s.org/hg/webob_view"><tt>webob_view</tt></a>

Putting links in the text without brackets will result in them being
marked up as well:

I work for http://www.google.com -> 
I work for <a href="http://www.google.com">http://www.google.com</a>


= Quotes = 

Quotes should be marked up in HTML, e.g.:

He said, "I am tired."

results in

He said, &lquot;I am tired&rquot;


= Symbols =

-- becomes an m-dash (except on a line by itself, when it becomes an <hr/>)

-> becomes a right arrow (similar for left arrow)

= Tables =

I've decided that doing pretty tables in a markdown language is either
ugly or hard.  Tables will be CSV, maybe with some magic delimeter
(like ==) to denote table beginning and end.  If you want better
tables, use HTML or a markdown language that supports fancy tables and
a damn good editor.


= Misc =

Two or more dashes on a line by themselves are an <hr/>

Footnotes are denoted by [1], [2].  Then at the end of the document,
these can be annoted.

The footnotes themselves must be separated by a `--` or be in a
section by themselves.

--

[1] a footnote
[2] another footnote

Often footnotes are like

"""
blah blah blah<sup><a href="#footnote-1">1</a></sup>
<...>
<hr/>
<ol id="footnotes>
  <li>"blah blah blah" is just some nonsense phrase here</li>
</ol>
"""

BUT....you should be able to backline from the foo to the location the
footnote is inserted.

==

Errata:

Conversion from various forms of markdown:
* http://code.google.com/p/gwtwiki/wiki/HTML2Mediawiki

What to do with [sic] italics? (...and strikethrough?)
The form as of this writing lists italics as \italics\. However,
consider https://en.wikipedia.org/wiki/Italic_type#Substitutes
. Forward (v back) slashes are in common use, and jml is supposed to
be legible text.  Italics and underlines have some overlap:  should _
just be used and italic v underline come from context?  However,
consider book titles. I have also seen '-', e.g. -this is italic-
(definitively single dashes, not double/em- dashes).  This, however
gets in the way of strikethrough...but do we need it?  It is a good
tag to have for e.g. jml. My current inclination is to use /italics/
vs \italics\.  Just switch to the indicated set of slashes.  I can't
think of a reason (for what I contend canon) where this wouldn't work
except for computer usages that should be in `` anyway.

--

Text conversion:

* pandoc: general markup converter
  Pandoc is a Haskell library for converting from one markup format to
  another, and a command-line tool that uses this library.

* yodl: Your Own Document Language (Yodl) is a pre-document language
  http://www.w3.org/Tools/YODL.html

* http://www.snake.net/software/troffcvt/ :
  troff-to-XXX Conversion Software

* https://pypi.python.org/pypi/pyth :
  Python text markup and conversion

* SiSU SiSU information Structuring Universe
  http://www.jus.uio.no/sisu/

* aft: "free form" document preparation system
  http://www.maplefish.com/todd/aft.html

* txt2tags: conversion tool to generating several file formats
  txt2tags is a document generator written in Python that
  generates HTML, XHTML, SGML, LaTeX, Lout, man page, Wikipedia,
  Google Code Wiki, DokuWiki, MoinMoin, Magic Point and PageMaker
  documents from a plain text file with little marks.

* sdf: Simple Document Parser
  SDF (Simple Document Format) is a freely available document
  development
  system which generates high quality outputs in a variety of formats
  from a single source. The output formats supported include
  PostScript(tm), PDF, HTML, plain text, POD, man pages, LaTeX,
  MIF, SGML, Windows(tm) help, RTF, MIMS F6 help and MIMS HTX help.
  If the idea of specifying documents in a logical manner via a
  simple markup language sounds appealing, SDF may be useful to you.

* xmlto: XML-to-any converter 

See also:

* http://en.wikipedia.org/wiki/Creole_%28markup%29