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

316 lines
6.8 KiB
Org Mode
Raw Normal View History

2011-07-26 03:04:17 +02:00
#+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.org/=.
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)