diff options
Diffstat (limited to 'www/embeddeddoc.wiki')
| -rw-r--r-- | www/embeddeddoc.wiki | 268 |
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><baseurl></i><big><b>/doc/</b></big><i><version></i><big><b>/</b></big><i><filename></i> +</pre> + +The <i><baseurl></i> is the main URL used to access the fossil web server. +For example, the <i><baseurl></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><baseurl></i> is usually +<b>http://localhost:8080/</b>. + +The <i><version></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"><version></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><filename></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 <div> element like this: + + <b><div class='fossil-doc' data-title='<i>Title Text</i>'></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><script></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 "<baseurl>" 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><th1>...</th1></code>. + +Fossil will substitute the value of [./th1.md | TH1 expressions] +within the <code><th1>...</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. |