initial commitHEADmaster

1 files changed, 268 insertions, 0 deletions

diff --git a/www/embeddeddoc.wiki b/www/embeddeddoc.wiki
new file mode 100644
index 0000000..6a6643d
--- /dev/null
+++ b/www/embeddeddoc.wiki
@@ -0,0 +1,268 @@
+<title>Project Documentation</title>
+
+Fossil provides a built-in <a href="wikitheory.wiki">wiki</a>
+that can be used to store the
+documentation for a project.  This is sufficient for many projects.
+If your project is well-served by wiki documentation, then you
+need read no further.
+
+But fossil also supports embedding project documentation as
+files in the source tree.  There are several potential advantages
+to this approach:
+
+  1.  The documentation files are versioned together with the
+      source code files so it is always clear what version of
+      the documentation goes with a particular release.
+
+  2.  The documentation files can be edited using your favorite
+      text editor instead of having to use the web-based wiki
+      editor.
+
+  3.  Only people with check-in privileges can modify the documentation.
+      (This might be either an advantage or disadvantage, depending
+      on the nature of your project.)
+
+We will call documentation that is included as files in the source tree
+"embedded documentation".
+
+<h1>1.0 Fossil Support For Embedded Documentation</h1>
+
+The fossil web interface supports embedded documentation using
+the "/doc" page.  To access embedded documentation, one points
+a web browser to a fossil URL of the following form:
+
+<pre>
+<i>&lt;baseurl&gt;</i><big><b>/doc/</b></big><i>&lt;version&gt;</i><big><b>/</b></big><i>&lt;filename&gt;</i>
+</pre>
+
+The <i>&lt;baseurl&gt;</i> is the main URL used to access the fossil web server.
+For example, the <i>&lt;baseurl&gt;</i> for the fossil project itself is
+[https://fossil-scm.org/home].
+If you launch the web server using the "[/help/ui|fossil ui]" command line,
+then the <i>&lt;baseurl&gt;</i> is usually
+<b>http://localhost:8080/</b>.
+
+The <i>&lt;version&gt;</i> is the
+[./checkin_names.wiki|name of a check-in]
+that contains the embedded document.  This might be a hash prefix for
+the check-in, or it might be the name of a branch or tag, or it might
+be a timestamp.  See the prior link
+for more possibilities and examples.
+
+The <i id="ckout">&lt;version&gt;</i> can
+also be the special identifier "<b>ckout</b>".
+The "<b>ckout</b>" keywords means to
+pull the documentation file from the local source tree on disk, not
+from the any check-in.  The "<b>ckout</b>" keyword
+only works when you start your server using the 
+"[/help/server|fossil server]" or "[/help?cmd=ui|fossil ui]"
+commands.  The "/doc/ckout" URL is intended to show a preview of
+the documentation you are currently editing but have not yet checked in.
+
+The original designed purpose of the "ckout" feature is to allow the
+user to preview local changes to documentation before committing the
+change.  This is an important facility, since unlike other document
+languages like HTML, there is still a lot of variation among rendering
+engines for Fossil's markup languages, Markdown and Fossil Wiki.  Your
+changes may look fine in your whizzy GUI Markdown editor, but what
+actually matters is how <i>Fossil</i> will interpret your Markdown text.
+Therefore, you should always preview your edits before committing them.
+
+To help make "ckout" easier to use, the "[/help?cmd=ui|fossil ui]"
+command has the "--ckout-alias NAME" option that makes NAME an
+alias for "ckout".  If you are editing a collection of documents
+that have hardcoded links to one another in the form of
+"/doc/trunk/...", for example, you can test your changes by
+running "fossil ui --ckout-alias trunk" and all of the links will
+point to your uncommitted edits rather than to the latest trunk
+check-in.
+
+Finally, the <i>&lt;filename&gt;</i> element of the URL is the
+pathname of the documentation file relative to the root of the source
+tree.
+
+The mimetype (and thus the rendering) of documentation files is
+determined by the file suffix.  Fossil currently understands
+[/mimetype_list|many different file suffixes],
+including all the popular ones such as ".css", ".gif", ".htm",
+".html", ".jpg", ".jpeg", ".png", and ".txt".
+
+Documentation files whose names end in ".wiki" use the
+[/wiki_rules | fossil wiki markup] -
+a safe subset of HTML together with some wiki rules for paragraph
+breaks, lists, and hyperlinks.
+Documentation files ending in ".md" or ".markdown" use the
+[/md_rules  | Markdown markup language].
+Documentation files ending in ".txt" are plain text.
+Wiki, markdown, and plain text documentation files
+are rendered with the standard fossil header and footer added.
+Most other mimetypes are delivered directly to the requesting
+web browser without interpretation, additions, or changes.
+
+<h2 id="html">1.1 HTML Rendering With Fossil Headers And Footers</h2>
+
+Files with the mimetype "text/html" (the .html or .htm suffix) are
+usually rendered directly to the browser without interpretation.
+However, if the file begins with a &lt;div&gt; element like this:
+
+    <b>&lt;div class='fossil-doc' data-title='<i>Title Text</i>'&gt;</b>
+
+Then the standard Fossil header and footer are added to the document
+prior to being displayed.  The "class='fossil-doc'" attribute is
+required for this to occur.  The "data-title='...'" attribute is
+optional, but if it is present the text will become the title displayed
+in the Fossil header.  An example of this can be seen in Fossil
+Documentation Index www/permutedindex.html:
+
+  *  [/file/www/permutedindex.html?txt|source text for <b>www/permutedindex.html</b>]
+  *  [/doc/trunk/www/permutedindex.html|<b>www/permutedindex.html</b> rendered as HTML]
+
+Beware that such HTML files render in the same browser security context
+as all other embedded documentation served from Fossil; they are not
+fully-independent web pages. One practical consequence of this is that
+embedded <tt>&lt;script&gt;</tt> tags will cause a
+[https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP | Content
+Security Policy] error in your browser with the default CSP as served by
+Fossil. See the documentation on [./customskin.md#headfoot | Header and
+Footer Processing] and [./defcsp.md | The Default CSP].
+
+
+<h1>2.0 Server-Side Text Substitution</h1>
+
+Fossil can do a few types of substitution of server-side information
+into the embedded document.
+
+<h2>2.1 "$ROOT" In HTML and Markdown Hyperlinks</h2>
+
+Hyperlinks in Markdown and HTML embedded documents can reference 
+the root of the Fossil repository using the special text "$ROOT"
+at the beginning of a URL. For example, a Markdown hyperlink to
+the Markdown formatting rules might be
+written in the embedded document like this:
+
+<verbatim>
+[Markdown formatting rules]($ROOT/wiki_rules)
+</verbatim>
+
+Depending on how the how the Fossil server is configured, that hyperlink
+might be renderer like one of the following:
+
+<verbatim>
+<a href="/wiki_rules">Wiki formatting rule</a>
+<a href="/cgi-bin/fossil/wiki_rules">Wiki formatting rules</a>
+</verbatim>
+
+So, in other words, the "$ROOT" text is converted into whatever
+the "&lt;baseurl&gt;" is for the document.
+
+This substitution works for HTML and Markdown documents.
+It does not work for Wiki embedded documents, since with
+Wiki you can just begin a URL with "/" and it automatically knows
+to prepend the $ROOT.
+
+<h2>2.2 "$CURRENT" In "/doc/" Hyperlinks</h2>
+
+Similarly, URLs of the form "/doc/$CURRENT/..." have the check-in
+hash of the check-in currently being viewed substituted in place of
+the "$CURRENT" text.  This feature, in combination with the "$ROOT"
+substitution above, allows an absolute path to be used for hyperlinks.
+
+For example, if an embedded document documented wanted to reference
+some other document in a separate file named "www/otherdoc.md",
+it could use a URL like this:
+
+<verbatim>
+[Other Document]($ROOT/doc/$CURRENT/www/otherdoc.md)
+</verbatim>
+
+As with "$ROOT", this substitution only works for Markdown and HTML
+documents.  For Wiki documents, you would need to use a relative URL.
+
+<h2 id="th1">2.3 TH1 Documents</h2>
+
+Enabling TH1 document support requires the following:
+
+   *  Configure the build with the <code>--with-th1-docs</code> flag.
+   *  Enable the <code>th1-docs</code> setting, which is only available
+      after building with <code>--with-th1-docs</code>.
+   *  Affected files must have a <code>.th1</code> file extension.
+   *  The code to run must be embedded in blocks of
+      <code>&lt;th1>...&lt;/th1></code>.
+
+Fossil will substitute the value of [./th1.md | TH1 expressions]
+within the <code>&lt;th1>...&lt;/th1></code> blocks into
+the output HTML.
+
+Since TH1 is a full scripting language, this feature essential grants
+the ability to execute code on the server to anyone with check-in
+privilege for the project.
+This is a security risk that needs to be carefully managed.
+The feature is off by default.
+Administrators should understand and carefully assess the risks
+before enabling the use of TH1 within embedded documentation.
+
+
+<h1>3.0 Examples</h1>
+
+This file that you are currently reading is an example of
+embedded documentation.  The name of this file in the fossil
+source tree is "<b>www/embeddeddoc.wiki</b>".
+You are perhaps looking at this
+file using the URL:
+
+<pre>[https://fossil-scm.org/home/doc/trunk/www/embeddeddoc.wiki]</pre>
+
+The first part of this path, the "[https://fossil-scm.org/home]",
+is the base URL.  You might have originally typed:
+[https://fossil-scm.org/].  The web server at the fossil-scm.org
+site automatically redirects such links by appending "home".  The
+"home" file on fossil-scm.org is really a [./server/any/cgi.md|CGI script]
+which runs the fossil web service in CGI mode.
+The "home" CGI script looks like this:
+
+<pre>
+#!/usr/bin/fossil
+repository: /fossil/fossil.fossil
+</pre>
+
+This is one of the many ways to set up a
+<a href="./server/">Fossil server</a>.
+
+The "<b>/trunk/</b>" part of the URL tells fossil to use
+the documentation files from the most recent trunk check-in.
+If you wanted to see an historical version of this document,
+you could substitute the name of a check-in for "<b>/trunk/</b>".
+For example, to see the version of this document associated with
+check-in [9be1b00392], simply replace the "<b>/trunk/</b>" with
+"<b>/9be1b00392/</b>".  You can also substitute the symbolic name
+for a particular version or branch.  For example, you might
+replace "<b>/trunk/</b>" with "<b>/experimental/</b>" to get the latest
+version of this document in the "experimental" branch.  The symbolic name
+can also be a date and time string in any of the following formats:</p>
+
+<ul>
+<li> <i>YYYY-MM-DD</i>
+<li> <i>YYYY-MM-DD<b>T</b>HH:MM</i>
+<li> <i>YYYY-MM-DD<b>T</b>HH:MM:SS</i>
+</ul>
+
+When the symbolic name is a date and time, fossil shows the version
+of the document that was most recently checked in as of the date
+and time specified.  So, for example, to see what the fossil website
+looked like at the beginning of 2010, enter:
+
+<pre><a href="https://fossil-scm.org/home/doc/2010-01-01/www/index.wiki">https://fossil-scm.org/home/doc/<b>2010-01-01</b>/www/index.wiki
+</a></pre>
+
+The file that encodes this document is stored in the fossil source tree under
+the name "<b>www/embeddeddoc.wiki</b>" and so that name forms the
+last part of the URL for this document.
+
+As I sit writing this documentation file, I am testing my work by
+running the "<b>fossil ui</b>" command line and viewing
+<b>http://localhost:8080/doc/ckout/www/embeddeddoc.wiki</b> in
+Firefox.  I am doing this even though I have not yet checked in
+the "<b>www/embeddeddoc.wiki</b>" file for the first time.  Using
+the special "<b>ckout</b>" version identifier on the "<b>/doc</b>" page
+it is easy to make multiple changes to multiple files and see how they all
+look together before committing anything to the repository.