<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 (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 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.

<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.

This special wiki pages are very useful for recording historical
notes.
