metanohi/site/projects/mege/docs/index.org

#+title: mege documentation
#&summary
Documentation for the metanohi generator
#&
#+license: bysa

#&+classes=warning
Ooops. It appears this document is not quite finished yet.
#&

* Quick overview

+ headers
+ paragraphs
+ inline modifiers
  + strong, *bold*
  + em, /italic/
  + _underline_
  + combinations
  + xhtml1.1-based
    + acronym
    + abbreviation
    + cite
    + code
    + samp
    + kbd
    + var
    + dfn
    + sub
    + sup
    + del
    + ins
    + q
+ images
+ tables
  + head
  + body
  + foot
  + rows
  + cells
+ lists
  + not numbered
  + numbered
  + definition lists
+ links
  + with name
  + without name
+ footnotes
+ source code highlighting
+ LaTeX to PNG
+ xhtml1.1-based block elements
  + video/audio
  + address
  + blockquote
  + pre
  + hr
+ forms

* Detailed overview

** Headings

\*{1,6}\s*(INLINE)\n?

** Paragraphs

INLINE

** Escaped characters

Syntax: =\c= where c&var is a character.

** Modifiers

In the case of =#&something;args=, default args (defargs) = =[,
width=width][,height=height][,float=left|right][,align=left|right|center][,classes=class1
class2...][,caption=caption]=.

** Inline modifiers

*** Strong/bold

Signal *importance*. Syntax: =*INLINE*=

HTML equivalent:
#+BEGIN_SRC html
<strong>INLINE</strong>
#+END_SRC

*** Emphasize/italic

/Emphasize/ something. Syntax: =/INLINE/=

HTML equivalent:
#+BEGIN_SRC html
<em>INLINE</em>
#+END_SRC

*** Underline

_Underline_ something. Syntax: =_INLINE_=

HTML equivalent:
#+BEGIN_SRC html
<span class='underline'>INLINE</span>
#+END_SRC

*** Generic modifiers and groups

Text with spaces can be put in ={= and =}= brackets to function as a group. The
ampersand (&) character is commonly used after something, as in =&var= or
=&color=red=, which can also be combined to things like =&var,color=red=. A
two-part modifier like the =~= in =*bold*= must be preceded by nothing or a
space character, and it must be followed by another space character, a period,
a comma, an exclamation mark, a question mark, a semicolon, a colon, or
something similar. If this is not enough, further abstractions are possible
with the =#&code= + newline + text + newline + =#&= construct.

The *text is strongly emphasized* and in one paragraph.

The 
#&-strong
text is strongly emphasized
#&
but it's still just in one paragraph even though the =*...*= modifier wasn't
used. Inline modifiers cannot be nested, but block modifiers can.

This construct must be used in cases where the data is not inline.

*** Acronym, abbreviation, variable, definition

Describe an acronym, an abbreviation, a variable, or a definition. Syntax:
=text&(abbr|acro)(=meaning)?= or =text&(var|dfn)=.

Example 1: =mege&abbr\='metanohi generator'= equals mege&abbr='metanohi
generator'.

Example 2: ={A. B.}&acro=AlBook= equals {A. B.}&acro=AlBook.

HTML equivalents: =<acronym title\='meaning'>acronym[INLINE]</acronym>=&html,
=<abbr title\='meaning'>abbreviation[INLINE]</abbr>=&html,
=<var>variable[INLINE]</var>=&html, and =<dfn>definition[INLINE]</dfn>=&html.

*** Quouting and citing

Quote without citing: =a^2+b^2=c^2&quote=.

Cite without quoting: =http://en.wikipedia.org/&cite=.

Quote and cite: ={metanohi exists}&cite=http://metanohi.name/=.

HTML equivalent:
#+BEGIN_SRC html
<q cite='cited'>quote[INLINE]</q>
#+END_SRC

*** Code

Syntax: ==code== or ={=code\=}&lang=. Example: ==print('hi')==,
==print('hi')\=&py3=. If you do not specify a language, the code will not be
highlighted.

Sample output from a program, with the syntax =~sample~= uses the same
logic.

*** Keyboard

Describe keyboard shortcuts (mainly). Syntax: -shortcut-.

Examples: -C-f-, -C-u C-u M-x C-q s-y s-f M-C-n M-C-S-k- (I don't have this
keybinding), -Ctrl+Alt+U-, etc.

HTML:
#+BEGIN_SRC html
<kbd>shortcut</kbd>
#+END_SRC

*** Subscript and superscript

To achieve something like CH_{3}CO_{2}^{3-} or x_{new} = 2^{50} without
resorting to math mode, use the =^= character for superscripts and the =_=
character for subscripts. Bracket groups must be used. Note that this is
different from LaTeX.


*** del, ins

=text&del=, =text&ins= = text&del, text&ins.

*** Other modifiers

Sizes: tiny, small, medium (normal), large, huge. Syntax: =text&size=,
eg. =text&large=.

Color: =text&color=color=.

More than one modifier: =&dfn&color=green=.


*** Combinations

..are allowed. However, a certain logic applies. It will not be explained
here. It is not yet well-defined.


** Video/audio

Syntax: =#&video|audio;url='...'[, autoplay][defargs]=

** Images

Syntax for images in blocks: =#&img;url='...',alt='...'[defargs]=.

** Blockquote, address, preformatted text

Indent a blockquote or specify an address or show text without
post-formatting. Syntax:

#+BEGIN_SRC
#&block[;cite='url']
paragraphs
#&
#+END_SRC

#+BEGIN_SRC
#&address
address
#&
#+END_SRC

#+BEGIN_SRC
#&pre
This is 
  pre-formatted *text*, though not entirely
#&
#+END_SRC

Note: The effect achieved by =#&pre= can also be achieved in another way.

** Block container (div)

#+BEGIN_SRC
#&+[args]
blah
#&
#+END_SRC

** Line (hr)

Syntax: =#&line=

** Links

Syntax: =[[url]]= or =[[url][name]]=. 

** Footnotes

Syntax: =This is a footnote[fn:serup2011].=, and:

=[fn:serup2011] It's true!=

** Lists

Same as Org-Mode.

** Tables

Same as Org-Mode.

** Python execution and evaluation

Inline, it's =<&eval ... &>=, =<&exec ... &>=, =<&deval ... &>=, and =<&dexec
... &>=. For blocks, see below.

** Source code

Begin with =#+BEGIN_SRC[ language]= and end with =#+END_SRC=. If nothing or
=#++high= comes before =#+BEGIN_SRC=, highlight the source code. If =#++show=
comes before, just show it (useful for HTML, JavaScript and CSS code). to show
inline HTML code, use the =<@html CODE@>= construct. If =#++pre=, show it, but
only use inline formatting. If =#++exec=, evaluate it as Python code. If
=#++dexec=, do the same thing, but do it whenever the site is reloaded
("dynamic exec"). =#++eval= and =#++deval= can also be used.

** Math

Inline math: =$LaTeX$=, example: $\frac{32}{x} = 8 \Rightarrow x \neq \infty$.

Block math: =#&math\nLaTeX\n#&=.

** Forms

Only accesible via the dynamic execution constructs (at some point --- not
implemented yet).

* Special features

+ The =#+...= construct works for single lines only
+ The =#&...= construct along with =#&= to end it can last over several lines
+ The =#++...= construct can add instructions to a =#+...= construct if the
 =#++= is placed just above the =#+=.

* Special variables

Formatting is not accepted in the following variables.

+ Title if =#+title:TITLE= is specified
+ Summary if =#+summary:SUMMARY= or =#&summary\n...\n#&= is specified
+ Table of contents if =#&toc= is specified
+ Levels in a table of contents defaults to 3, different if =#+toclvl:lvl= is
  specified
+ Full page if =#&fullpage= is specified
+ License added if =#+license:LICENSEID[, covering what]= is specified (several
  licenses can be specified)