[sc-dev] [rfc] alternative documentation format, scwiki

[stefan kersten <steve@xxxxxxxxxx>]

i'd really like to get the Document stuff including the
recent scwiki idea going on linux; emacs is too limited with
the current asynchronous approach. i've implemented the
beginnings of a gtk editor that displays RTF files decently
(well, much better than emacs), but writing an actual RTF
editing component would be quite a lot of work that could be
spent elsewhere.

this has been discussed a few times before, and i think the
issue could be summarized like so:

* ASCII is aesthetically inferior
* HTML is a no no
* XML is overkill
* LaTeX too
* remains RTF

so how about using a simple markup format similar to the
ones used in existing wikis for documentation? i've been
looking at instiki [1] which uses textile [2, 3] as its
markup by default. some examples:

* code can be enclosed in

  <code>
      Pbind(\e, pi);
  </code>

  the editor would know how to process a code chunk and
  can do syntactical hightlighting automatically

* wiki/documentation links:

  See also [[Baking-Bread]], [[Cutting-Cookies]].

* use of tables in Help.help.rtf:

  h1. SuperCollider Help
  ...
  | +Essential Topics+         | +Language+                | +Tutorials+ |
  | *[[More-On-Getting-Help]]* | [[Intro-to-Objects]]      | HTUTI       |
  | [[Server-Architecture]]    |                           |             |
  | [[Literals]]               | [[Introductory_tutorial]] |             |
  ...

* external links

  "my homepage":http://www.sk.co.kr

the editor would support switching between view and edit
mode: while in view mode, code blocks could still be edited
(e.g. to adapt code examples), but edits would not be
persistent (well, edits to code blocks _could_ be made
persistent), while modifications to other parts of the
document are prohibited. the markup would be converted on
the fly into a suitable format for display, e.g. RTF or HTML
or directly rendered into the view. edit mode is just a
plain UTF-8 text editor.

the data store backend could be file-based/hierarchy-less
for starters, or entail something more sophisticated like
versioning, document attributes, etc.

it would be even possible to write most of the logic,
i.e. data storage, display conversion, etc. in SC. documents
could be stored as SC archives, such that a documentation
page is nothing more than an SC object on disk.

imo it would be really benefitial to use something more
structured than RTF because structural information could be
used in a lot of places, like searching the documentation,
building indexes etc.

comments?

<sk>

[1] http://www.instiki.org
[2] http://www.textism.com/tools/textile/
[3] http://hobix.com/textile/