From 4f49b16079b27d7ce633619e4cddfdf2bffbc952 Mon Sep 17 00:00:00 2001 From: cashmere Date: Fri, 4 Sep 2026 09:05:24 +0200 Subject: initial commit --- www/embeddeddoc.wiki | 268 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 268 insertions(+) create mode 100644 www/embeddeddoc.wiki (limited to 'www/embeddeddoc.wiki') 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 @@ +Project Documentation + +Fossil provides a built-in wiki +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". + +

1.0 Fossil Support For Embedded Documentation

+ +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: + +
+<baseurl>/doc/<version>/<filename>
+
+ +The <baseurl> is the main URL used to access the fossil web server. +For example, the <baseurl> 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 <baseurl> is usually +http://localhost:8080/. + +The <version> 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 <version> can +also be the special identifier "ckout". +The "ckout" keywords means to +pull the documentation file from the local source tree on disk, not +from the any check-in. The "ckout" 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 Fossil 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 <filename> 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. + +

1.1 HTML Rendering With Fossil Headers And Footers

+ +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: + + <div class='fossil-doc' data-title='Title Text'> + +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 www/permutedindex.html] + * [/doc/trunk/www/permutedindex.html|www/permutedindex.html 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 <script> 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]. + + +

2.0 Server-Side Text Substitution

+ +Fossil can do a few types of substitution of server-side information +into the embedded document. + +

2.1 "$ROOT" In HTML and Markdown Hyperlinks

+ +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: + + +[Markdown formatting rules]($ROOT/wiki_rules) + + +Depending on how the how the Fossil server is configured, that hyperlink +might be renderer like one of the following: + + +Wiki formatting rule +Wiki formatting rules + + +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. + +

2.2 "$CURRENT" In "/doc/" Hyperlinks

+ +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: + + +[Other Document]($ROOT/doc/$CURRENT/www/otherdoc.md) + + +As with "$ROOT", this substitution only works for Markdown and HTML +documents. For Wiki documents, you would need to use a relative URL. + +

2.3 TH1 Documents

+ +Enabling TH1 document support requires the following: + + * Configure the build with the --with-th1-docs flag. + * Enable the th1-docs setting, which is only available + after building with --with-th1-docs. + * Affected files must have a .th1 file extension. + * The code to run must be embedded in blocks of + <th1>...</th1>. + +Fossil will substitute the value of [./th1.md | TH1 expressions] +within the <th1>...</th1> 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. + + +

3.0 Examples

+ +This file that you are currently reading is an example of +embedded documentation. The name of this file in the fossil +source tree is "www/embeddeddoc.wiki". +You are perhaps looking at this +file using the URL: + +
[https://fossil-scm.org/home/doc/trunk/www/embeddeddoc.wiki]
+ +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: + +
+#!/usr/bin/fossil
+repository: /fossil/fossil.fossil
+
+ +This is one of the many ways to set up a +Fossil server. + +The "/trunk/" 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 "/trunk/". +For example, to see the version of this document associated with +check-in [9be1b00392], simply replace the "/trunk/" with +"/9be1b00392/". You can also substitute the symbolic name +for a particular version or branch. For example, you might +replace "/trunk/" with "/experimental/" 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:

+ + + +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: + +
https://fossil-scm.org/home/doc/2010-01-01/www/index.wiki
+
+ +The file that encodes this document is stored in the fossil source tree under +the name "www/embeddeddoc.wiki" 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 "fossil ui" command line and viewing +http://localhost:8080/doc/ckout/www/embeddeddoc.wiki in +Firefox. I am doing this even though I have not yet checked in +the "www/embeddeddoc.wiki" file for the first time. Using +the special "ckout" version identifier on the "/doc" page +it is easy to make multiple changes to multiple files and see how they all +look together before committing anything to the repository. -- cgit v1.3.1