Overview
| SHA1 Hash: | 7083eb1a1c7a32206a0960e354899d2c2058554c |
|---|---|
| Date: | 2008-11-20 03:14:22 |
| User: | drh |
| Comment: | Change the markup in the index.wiki page from HTML to wiki. Extend the wikitheory.wiki page. Other documentation tweaks. |
| Timelines: | ancestors | descendants | both | trunk |
| Other Links: | files | ZIP archive | manifest |
Tags And Properties
- branch=trunk inherited from [a28c83647d]
- sym-trunk inherited from [a28c83647d]
Changes
[hide diffs]Modified www/bugtheory.wiki from [5344c6eedf] to [5f6ed2b26b].
@@ -7,11 +7,11 @@
the source tree and thereby leverage the syncing and merging capabilities
of the versioning system to sync and merge tickets. This approach is
rejected in fossil for three reasons:
1. Check-ins (a.k.a. "baselines") in fossil are immutable. So if
- tickets were part of the check-in, then there would no way to add
+ tickets were part of the check-in, then there would be no way to add
new tickets to a check-in as new bugs are discovered.
2. Any project of reasonable size and complexity will generate thousands
and thousands of tickets, and we do not want all those ticket files
cluttering the source tree.
Modified www/index.wiki from [7528157689] to [635e17dfd6].
@@ -1,103 +1,92 @@
<h1>Fossil: Distributed Revision Control, Wiki, and Bug-Tracking</h1>
-<p>
Fossil is a
-<a href="http://en.wikipedia.org/wiki/Revision_control">
-distributed software revision control system</a> that includes an integrated
-<a href="wikitheory.wiki">wiki</a> and an integrated
-<a href="bugtheory.wiki">bug-tracking system</a> all in a single,
+[http://en.wikipedia.org/wiki/Revision_control | distributed software version control system]
+that includes an integrated
+[./wikitheory.wiki | distributed wiki] and an integrated
+[./bugtheory.wiki | distributed bug-tracking system] all in a single,
easy-to-use, stand-alone executable.
-Fossil is
-<a href="http://www.fossil-scm.org/">self-hosting</a>
+Fossil is [http://www.fossil-scm.org/ | self-hosting]
since 2007-07-21 on
-<a href="http://www.hwaci.com/cgi-bin/fossil">two separate servers</a>.
-You can download the <a href="../../../timeline">latest sources</a> and
-<a href="build.wiki">compile it yourself</a>.
+[http://www.hwaci.com/cgi-bin/fossil | two separate servers].
+You can download the [/timeline?y=ci | latest sources] and
+[./build.wiki | compile it yourself].
Or you can grab
-<a href="http://www.fossil-scm.org/download.html">pre-compiled binaries</a>.
-</p>
+[http://www.fossil-scm.org/download.html | pre-compiled binaries].
+
-<p>Feature Summary:</p>
+Feature Summary:
-<ul>
-<li>Flexible workflow:<ul>
+ * Flexible workflow:<ul>
<li>Disconnected, distributed development like
<a href="http://kerneltrap.org/node/4982">git</a>,
<a href="http://www.monotone.ca/">monotone</a>,
<a href="http://www.selenic.com/mercurial/wiki/index.cgi">mercurial</a>,
and <a href="http://www.bitkeeper.com/">bitkeeper</a>
<li>Or, client/server operation like
<a href="http://www.nongnu.org/cvs/">CVS</a> and
<a href="http://subversion.tigris.org/">subversion</a>,
<li>Or, operations on local repositories,
- <li>Or, all of the above at the same time</ul></li>
-<li>Integrated, distributed <a href="bugtheory.wiki">bug tracking</a> and
-<a href="wikitheory.wiki">wiki</a>.</li>
-<li>Built-in web interface that supports deep archaeological digs through
-the project history.</li>
-<li>All network communication via
-<a href="http://en.wikipedia.org/wiki/HTTP">HTTP</a> with
-<a href="quickstart.wiki#proxy">proxy support</a>
-so that everything works from behind restrictive firewalls.</li>
-<li>Everything (client, server, and utilities) is included in a
-single self-contained executable - trivial to install</li>
-<li>Server runs as <a href="quickstart.wiki#cgiserver">CGI</a>, using
-<a href="quickstart.wiki#inetdserver">inetd/xinetd</a>
-or using its own
-<a href="quickstart.wiki#serversetup">built-in, stand alone web server</a>.</li>
-<li>An entire project contained in single disk file
-(an <a href="http://www.sqlite.org/">SQLite</a> database.)</li>
-<li>Uses an <a href="fileformat.wiki">enduring file format</a> that is
-designed to be readable, searchable, and extensible by people not yet born.</li>
-<li>Automatic <a href="selfcheck.wiki">self-check</a>
-on repository changes makes it exceedingly
-unlikely that data will ever be lost because of a software bug.</li>
-<li>Ridiculously easy to
-<a href="build.wiki">install</a> and
-<a href="quickstart.wiki">operate</a>.</li>
-</ul>
+ <li>Or, all of the above at the same time</ul>
+ * Integrated, [./bugtheory.wiki | distributed bug tracking] and
+ [./wikitheory.wiki | distributed wiki].
+ * Built-in web interface that supports deep archaeological digs through
+ the project history.
+ * All network communication via
+ [http://en.wikipedia.org/wiki/HTTP | HTTP] with
+ [./quickstart.wiki#proxy | proxy support]
+ so that everything works from behind restrictive firewalls.
+ * Everything (client, server, and utilities) is included in a
+ single self-contained executable - trivial to install
+ * Server runs as [./quickstart.wiki#cgiserver | CGI], using
+ [./quickstart.wiki#inetdserver | inetd/xinetd]
+ or using its own
+ [./quickstart.wiki#serversetup | built-in, stand alone web server].
+ * An entire project contained in single disk file
+ (an [http://www.sqlite.org/ | SQLite] database.)
+ * Uses an [./fileformat.wiki | enduring file format] that is
+ designed to be readable, searchable, and extensible by people
+ not yet born.
+ * Automatic [./selfcheck.wiki | self-check]
+ on repository changes makes it exceedingly
+ unlikely that data will ever be lost because of a software bug.
+ * Ridiculously easy to [./build.wiki | install] and
+ [./quickstart.wiki | operate].
+
+User Links:
+
+ * The [./concepts.wiki | concepts] behind fossil
+ * [./build.wiki | Building And Installing]
+ * [./quickstart.wiki | Quick Start] guide to using fossil
+ * Fossil supports [./embeddeddoc.wiki | embedded documentation]
+ that is versioned along with project source code.
+ * The [./selfcheck.wiki | automatic self-check] mechanism
+ helps insure project integrity.
+ * Fossil contains a [./wikitheory.wiki | built-in wiki].
+ * There is a
+ [http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users | mailing list]
+ available for discussing fossil issues.
+ * [./qandc.wiki | Questions & Criticisms] directed at fossil.
+ * Some (unfinished but expanding) extended
+ [./reference.wiki | reference documentation] for the fossil command line.
+
+Developer Links:
+
+ * [./pop.wiki | Principles Of Operation]
+ * The [./fileformat.wiki | file format] used by every content
+ file stored in the repository.
+ * The [./delta_format.wiki | format of deltas] used to
+ efficiently store changes between file revisions.
+ * The [./delta_encoder_algorithm.wiki | encoder algorithm] used to
+ efficiently generate deltas.
+ * The [./sync.wiki | synchronization protocol].
-<p>User Links:</p>
-
-<ul>
-<li>The <a href="concepts.wiki">concepts</b> behind fossil</li>
-<li><a href="build.wiki">Building And Installing</a></li>
-<li><a href="quickstart.wiki">Quick Start</a> guide to using fossil
-<li>Fossil supports <a href="embeddeddoc.wiki">embedded documentation</a>
- that is versioned along with project source code.</li>
-<li>The <a href="selfcheck.wiki">automatic self-check</a> mechanism
-helps insure project integrity.</li>
-<li>Fossil contains a <a href="wikitheory.wiki">built-in wiki</a>.</li>
-<li>There is a
- <a href="http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users">
- mailing list</a> available for discussing fossil issues.</li>
-<li><a href="qandc.wiki">Questions & Criticisms</a> directed at fossil.</li>
-<li>Some (unfinished but expanding) extended
- <a href="reference.wiki">reference documentation</a> for the fossil command line.
-</ul>
+Competing Projects:
-<p>Developer Links: </p>
-
-<ul>
-<li><a href="pop.wiki">Principles Of Operation</a></li>
-<li>The <a href="fileformat.wiki">file format</a> used by every content
-file stored in the repository.</li>
-<li>The <a href="delta_format.wiki">format of deltas</a> used to
-efficiently store changes between file revisions.</li>
-<li>The <a href="delta_encoder_algorithm.wiki">encoder algorithm</a> used to
-efficiently generate deltas.</li>
-<li>The <a href="sync.wiki">synchronization protocol</a>.</li>
-</ul>
-
-<p>Competing Projects:</p>
-
-<ul>
-<li><a href="http://www.ditrack.org/">DITrace</a>
- - A Distributed Issue Tracker</li>
-<li><a href="http://www.distract.wellquite.org/">DisTract</a>
+ * [http://www.ditrack.org/ | DITrace] - A Distributed Issue Tracker
+ * [http://www.distract.wellquite.org/ | DisTract]
- Another distributed issue tracker based on
- <a href="http://www.monotone.ca/">monotone</a>.</li>
-<li><a href="http://www.monotone.ca/">Monotone</a> - distributed
+ [http://www.monotone.ca/ | monotone].
+ * [http://www.monotone.ca/ | Monotone] - distributed
SCM in a single-file executable with a single-file SQLite
- database repository.</li>
-</ul>
+ database repository.
Modified www/qandc.wiki from [11bd9cb67a] to [61ff0d8364].
@@ -18,11 +18,12 @@
<ol>
<li> Integrated <a href="wikitheory.wiki">wiki</a>. </li>
<li> Integrated <a href="bugtheory.wiki">bug tracking</a> </li>
<li> Immutable artifacts </li>
- <li> Self-contained, stand-alone executable </li>
+ <li> Self-contained, stand-alone executable that can be run in
+ a <a href="http://en.wikipedia.org/wiki/Chroot">chroot jail</a> </li>
<li> Simple, well-defined,
<a href="fileformat.wiki">enduring file format</a> </li>
</ol>
</blockquote>
@@ -78,12 +79,34 @@
<b>It would be useful to have a separate application that
keeps the bug-tracking database in a versioned file. That file can
then be pushed and pulled along with the rest repository.</b>
<blockquote>
-<p>This is addressed in the opening paragraphs of
-the <a href="bugtheory.wiki">Bug-Tracking In Fossil</a> document.
+<p>Fossil already <u>does</u> push and pull bugs along with the files
+in your repository.
+But fossil does <u>not</u> track bugs as files in the source tree.
+That approach to bug tracking was rejected for three reasons:</p>
+
+<ol>
+<li> Check-ins in fossil are immutable. So if
+ tickets were part of the check-in, then there would be no way to add
+ new tickets to a check-in as new bugs are discovered.
+
+<li> Any project of reasonable size and complexity will generate thousands
+ and thousands of tickets, and we do not want all those ticket files
+ cluttering the source tree.
+
+<li> We want tickets to be managed from the web interface and to have a
+ permission system that is distinct from check-in permissions.
+ In other words, we do not want to restrict the creation and editing
+ of tickets to developers with check-in privileges and an installed
+ copy of the fossil executable. Casual passers-by on the internet should
+ be permitted to create tickets.
+</ol>
+
+<p>These points are reiterated in the opening paragraphs of
+the <a href="bugtheory.wiki">Bug-Tracking In Fossil</a> document.</p>
</blockquote>
<b>Fossil is already the name of a plan9 versioned
append-only filesystem.</b>
Modified www/wikitheory.wiki from [9523b0d860] to [fa58861fa7].
@@ -1,21 +1,38 @@
-<h1>Wiki In <a href="index.wiki">Fossil</a></h1>
-
-Fossil uses <a href="../../../wiki_rules">wiki markup</a> for many
-things:
+<h1>Wiki In [./index.wiki | Fossil]</h1>
+
+Fossil uses [/wiki_rules | wiki markup] for many things:
* Stand-alone wiki pages.
- * Description and comments in <a href="bugtheory.wiki">bug reports</a>.
+ * Description and comments in [./bugtheory.wiki | bug reports].
* Check-in comments.
- * <a href="embeddeddoc.wiki">Embedded documentation</a> files whose
+ * [./embeddeddoc.wiki | Embedded documentation] files whose
name ends in "wiki".
-The <a href="../../../wiki_rules">formatting rules</a> for fossil wiki
+The [/wiki_rules | formatting rules] for fossil wiki
are designed to be simple and intuitive. The idea is that wiki provides
paragaph breaks, numbered and bulletted lists, and hyperlinking for
simple documents together with a safe subset of HTML for more complex
formatting tasks.
+
+Some commentators feel that the use of HTML is a mistake and that
+fossil should use the markup language of the
+<i>fill-in-your-favorite</i> wiki engine instead. That approach
+was considered but was rejected for the following reasons:
+
+ 1. There is no standard wiki markup language. Every wiki engine does
+ it a little differently.
+
+ 2. The wiki markup used by fossil, though limited, is common to most
+ other wiki engines, is intuitive, and is sufficient for 90% of
+ all formatting tasks.
+
+ 3. Where the fossil wiki markup language is insufficient, HTML is
+ used. HTML is a standard language familiar to most programmers so
+ there is nothing new to learn. And, though cumbersome, the HTML
+ does not need to be used very often so need not be a burden.
+
<h2>Stand-alone Wiki Pages</h2>
Each wiki page has its own revision history which is independent of
the sequence of baselines (check-ins). Wiki pages can branch and merge
@@ -30,9 +47,29 @@
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
-<a href="fileformat.wiki">control artifact</a>
-of type <a href="fileformat.wiki#wikichng">"Wiki Page"</a>.
+[./fileformat.wiki | control artifact]
+of type [./fileformat.wiki#wikichng | "Wiki Page"].
+
+<h2>Embedded Documentation</h2>
+
+Files in the source tree that use the ".wiki" suffix 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 descripted [./embeddeddoc.wiki | separately].)
+
+Some project 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 wiki markup language. Some projects may choose to
+use both forms of documentation at the same time.
+
+<h2>Bug-reports and check-in comments</h2>
-<i>To be continued...</i>
+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.