initial commitHEADmaster

1 files changed, 90 insertions, 0 deletions

diff --git a/www/wikitheory.wiki b/www/wikitheory.wiki
new file mode 100644
index 0000000..7273db2
--- /dev/null
+++ b/www/wikitheory.wiki
@@ -0,0 +1,90 @@
+<title>Wiki In Fossil</title>
+<h2>Introduction</h2>
+
+Fossil uses [/wiki_rules | Fossil wiki markup] and/or
+[/md_rules | Markdown markup] for many things:
+
+   *  Stand-alone wiki pages.
+   *  Description and comments in [./bugtheory.wiki | bug reports].
+   *  Check-in comments.  (For historical reasons, these must
+      currently be in fossil-wiki text format.)
+   *  [./embeddeddoc.wiki | Embedded documentation] files whose
+      name ends in ".wiki" or ".md" or ".markdown".
+   *  [./event.wiki | Technical notes].
+   *  [./forum.wiki | Forum messages].
+   *  Auxiliary notes on check-ins and branches.
+
+The [/wiki_rules | formatting rules for fossil wiki]
+are designed to be simple and intuitive.  The idea is that wiki provides
+paragraph breaks, numbered and bulleted lists, and hyperlinking for
+simple documents together with a safe subset of HTML for more complex
+formatting tasks.
+
+The [/md_rules | Markdown formatting rules] are more complex, but
+are also more widely known, and are thus provided as an alternative.
+
+<h2>Stand-alone Wiki Pages</h2>
+
+Each wiki page has its own revision history which is independent of
+the sequence of check-ins.  Wiki pages can branch and merge
+just like check-ins, though as of this writing (2008-07-29) there is
+no mechanism in the user interface to support branching and merging.
+The current implementation of the wiki shows the version of the wiki
+page that has the most recent time stamp.
+
+In other words, if two users make unrelated changes to the same wiki
+page on separate repositories and those repositories are synced,
+the wiki page will fork.  The web interface will display whichever edit
+was checked in last.  The other edit can be found in the history.  The
+file format will support merging the branches back together, but there
+is no mechanism in the user interface (yet) to perform the merge.
+
+Every change to a wiki page is a separate
+[./fileformat.wiki | control artifact]
+of type [./fileformat.wiki#wikichng | "Wiki Page"].
+
+<h2>Embedded Documentation</h2>
+
+Files in the source tree that use the ".wiki", ".md", or ".markdown" suffixes
+can be accessed and displayed using special URLs to the fossil server.
+This allows
+project documentation to be stored in the source tree and accessed
+online.  (Details are described [./embeddeddoc.wiki | separately].)
+
+Some projects prefer to store their documentation in wiki.  There is nothing
+wrong with that.  But other projects prefer to keep documentation as part
+of the source tree, so that it is versioned along with the source tree and
+so that only developers with check-in privileges can change it.
+Embedded documentation serves this latter purpose.  Both forms of documentation
+use the exact same markup.  Some projects may choose to
+use both forms of documentation at the same time.  Because the same
+format is used, it is trivial to move a file from wiki to embedded documentation
+or back again as the project evolves.
+
+<h2>Bug-reports and check-in comments and Forum messages</h2>
+
+The comments on check-ins, forum posts, and the text in the
+descriptions of bug reports both use wiki formatting.  Exactly the
+same set of formatting rules apply.  There is never a need to learn
+one formatting language for documentation and a different markup for
+bugs or for check-in comments.
+
+Minor caveat: check-in messages are currently limited to the
+fossil-wiki format.
+
+<h2 id="assocwiki">Auxiliary notes attached to check-ins or branches</h2>
+
+Stand-alone wiki pages with special names "branch/<i>BRANCHNAME</i>"
+or "checkin/<i>HASH</i>" are associated with the corresponding
+branch or check-in.  The wiki text appears in an "About" section of
+timelines and info screens.  Examples:
+
+   *  [/timeline?r=graph-test-branch] shows the text of the
+      [/wiki?name=branch/graph-test-branch&p|branch/graph-test-branch]
+      wiki page at the top of the timeline
+   *  [/info/19c60b7fc9e2] shows the text of the
+      [/wiki?name=checkin/19c60b7fc9e2400e56a6f938bbad0e34ca746ca2eabdecac10945539f1f5e8c6&p|checkin/19c60b7fc9e2...]
+      wiki page in the "About" section.
+
+These special wiki pages are very useful for recording historical
+notes.