
[[title
                      The Awiki Markup Language
]]

[[authors
                      Tom Lord (<lord@seyza.com>)
]]

[[abstract

                               Abstract
                                 ---

        /Awiki/ is a markup language and data structure definition for
        structured documents with multimedia content.  In that sense,
        awiki is comparable to both: (1) the machine-only usually-XML
        document formats used by some word processors;  (2) the 
        human-friendly document formats such as Texinfo or Docbook
        or your favorite wiki.   As the name suggests, the design of
        Awiki borrows heavily from examples observed in the wiki 
        world.

        This document briefly introduces Awiki syntax, in the context
        of explaining it's standard translation to HTML.
]]

  \\/\Awiki\/\\ is a plain-text markup language, similar to many Wiki
  languages.  It comes with it's own Manifesto of Design Principles,
  shown here.  (See {should}.)

  If you would prefer or are curious, you can read the <"source form
  of this document" -- ./intro.txt>, which is itself an example of
  /Awiki/ syntax.



* The Awiki Design Principles Manifesto

  \1. Make Document Source Beautiful and Accessible --\ The native
  format of a multi-media document system -- the contents of the
  document files, on disk -- should be a mostly plain-text format
  which is pleasing to read and easy for even non-programmer user's to
  type directly.  


  \2. Make a Complete (General Purpose) Language --\  The XML-family
  of languages are able to denote a very general space of *trees*.
  Every tree node has a *type label* and a *set of attributes* and both 
  textual and tree-node *sub-nodes*.   A multi-media document format 
  should define at least as open-ended a model for tree-structured
  data, and preferably one that is similar in structure.


  \3. Make a Line-oriented, Gracefully Failing Format --\
  Line-oriented Tools like 'grep', 'sed', 'diff', and 'patch'
  should be useful in natural ways on multi-media document files.
  If a line-oriented tool mildly corrupts a multi-media document,
  document processors should be able to recover gracefully -- treating
  the entire document source as just a block of plain-text in the 
  worst case.  The document format should be simple and easy enough
  that even non-programmer users feel comfortable editting a document
  source file, as plain text, in order to correct a minor corruption.

  \4. Make it Easy to Implement Well --\ I don't know about you, but
  it makes me nervous when I have to use a document format that is
  only managable with the help of a complicated library, which I have
  to get from only one of a few places, yet the format is also too
  complicated to consider implementing a new such library from
  scratch.

  \5. Make it Easy to Generate and Approximately Parse --\ Report
  generation programs should have an easy time generating correct
  and human-readable Awiki without having to rely on large or
  complicated helper libraries.   Programs and people improvising
  with shell commands should have an easy time parsing (at least
  approximately) awiki input without having to rely on awiki-specific
  tools for that purpose.





* A Simplified Introduction to Awiki

  This section documents enough of Awiki to get started writing Awiki
  documents that are translated to HTML.   The "deeper issues" of
  Awiki (e.g., what it is besides just a text to HTML translator)
  are ignored and the syntax has obscure exceptions and extensions
  not described here.    This is just enough to get started:


** Simple Paragraphs

  Paragraphs are separated by blank lines.   Paragraphs are
  ordinarilly filled.   For example:

  [[tty
        This is the
        first paragraph.

        This is
        the
        second paragraph.
  ]]

  is translated to:

  [[cartouche

        This is the
        first paragraph.

        This is
        the
        second paragraph.
  ]]


** Text Styles

  Here is a little sampler of text effects:

  [[tty
        Emphasize text /this way/ or \that way\.

        Stress text *that way* or ^that^.

        Programmer's will like being able to put `tty-like text'
        in their paragraphs.

        Literal hyperlinks to <http://www.gnu.org> are easy enough.
        So too are titled links to <"The GNU project home page" --
        http://www.gnu.org>.   If a link looks like an email address,
        it probably is: <lord@emf.net>.
  ]]


  gives:

  [[cartouche
        Emphasize text /this way/ or \that way\.

        Stress text *that way* or ^this^.

        Programmer's will like being able to put `tty-like text'
        in their paragraphs.

        Literal hyperlinks to <http://www.gnu.org> are easy enough.
        So too are titled links to <"The GNU project home page" --
        http://www.gnu.org>.   If a link looks like an email address,
        it probably is: <lord@emf.net>.
  ]]


** Internal Cross References

  You can place linkable anchors in a document and refer to them:

  [[tty

        A cross reference to {some-note} looks like that.


        {*some-note} can be defined as in this example.
  ]]


  gives

  [[cartouche

        A cross reference to {some-note} looks like that.


        {*some-note} can be defined as in this example.
  ]]


** Displays

  A *display* is a nested component of an essay: something usually
  introduced bewteen two paragraphs.   There many kinds of display
  and different Awiki applications can add new display types.

  The examples in this paper are constructed using `tty' and
  `cartouch' displays:

  [[tty
    The markup:

    [[tty
      You can /emphasize/ text.
    ]]

    yields

    [[cartouche
      You can /emphasize/ text.
    ]]
  ]]

  yields

  [[cartouche
    The markup:

    [[tty
      You can /emphasize/ text.
    ]]

    yields

    [[cartouche
      You can /emphasize/ text.
    ]]
  ]]


** Abstracts

  Another type of display is an /abstract/:

  [[tty
        [[abstract
                My Abstract

          This is the idea which is mine.  It is my idea,
          which to say ... yadda yadda yadda.
        ]]

  ]]  

  gives:

  [[cartouche

        [[abstract
                My Abstract
                   ---

          This is the idea which is mine.  It is my idea,
          which to say ... yadda yadda yadda.
        ]]

  ]]  



** Outline Structure

  A document can begin with just an ordinary list of paragraphs
  but it can also continue with contents divided into titled sections
  and subsections.

  Sections are marked in "outline style" using the `*' character to 
  indicate nesting depth.   Overall, *this* document looks like:

  [[tty

    Awiki is a plain-text markup language ....

    * A Simplified Introduction to Awiki

      This section documents ....

    ** Simple Paragraphs

      ...

    ** Text Styles

      ...

    etc.
  ]]



* A Detailed Specification of Wiki

  *Not yet.*   Sorry.


* The Awiki Tree Type

  *Not yet.*   Sorry.


* The Awiki C library.

  *Not yet.*   Sorry.


* Notes

 /{*should}/ The reason to state the Awiki design guidelines as a
 manifesto is so they can talk about what a document format *"should"*
 be like without ever bothering to justify that imperative.   The
 design guidelines are really just what I decided to do and I decided
 to follow those guidelines because the end result seems generally
 nifty and useful for many things I'm working on.


[[null
  ; arch-tag: Tom Lord Wed Oct 20 11:28:04 2004 (awiki/manual.txt)
]]

