Many hyperlinks are disabled.
Use anonymous login
to enable hyperlinks.
Overview
Comment: | Change the special $SELF substitution used by Markdown and HTML embedded documentation into $CURRENT. See the forum discussion for details. |
---|---|
Downloads: | Tarball | ZIP archive |
Timelines: | family | ancestors | descendants | both | trunk |
Files: | files | file ages | folders |
SHA3-256: |
45427ae1c9312bd81f272dfe8c080a0b |
User & Date: | drh 2020-02-12 16:35:45.635 |
Context
2020-02-12
| ||
17:03 | Provide a scary warning about the use of TH1 docs on the Security Audit page. ... (check-in: 5c0bb964 user: drh tags: trunk) | |
16:35 | Change the special $SELF substitution used by Markdown and HTML embedded documentation into $CURRENT. See the forum discussion for details. ... (check-in: 45427ae1 user: drh tags: trunk) | |
14:44 | Updates to the change log. ... (check-in: 0c9339bf user: drh tags: trunk) | |
Changes
Changes to src/doc.c.
︙ | ︙ | |||
683 684 685 686 687 688 689 | /* ** Transfer content to the output. During the transfer, when text of ** the following form is seen: ** ** href="$ROOT/..." ** action="$ROOT/..." | | | | 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 | /* ** Transfer content to the output. During the transfer, when text of ** the following form is seen: ** ** href="$ROOT/..." ** action="$ROOT/..." ** href=".../doc/$CURRENT/..." ** ** Convert $ROOT to the root URI of the repository, and $CURRENT to the ** version number of the /doc/ document currently being displayed (if any). ** Allow ' in place of " and any case for href or action. ** ** Efforts are made to limit this translation to cases where the text is ** fully contained with an HTML markup element. */ void convert_href_and_output(Blob *pIn){ |
︙ | ︙ | |||
710 711 712 713 714 715 716 | && isWithinHtmlMarkup(z, i-6) ){ blob_append(cgi_output_blob(), &z[base], i-base); blob_appendf(cgi_output_blob(), "%R"); base = i+5; }else if( z[i]=='$' | | | | | 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 | && isWithinHtmlMarkup(z, i-6) ){ blob_append(cgi_output_blob(), &z[base], i-base); blob_appendf(cgi_output_blob(), "%R"); base = i+5; }else if( z[i]=='$' && strncmp(&z[i-5],"/doc/$CURRENT/", 11)==0 && isWithinHref(z,i-5) && isWithinHtmlMarkup(z, i-5) && strncmp(g.zPath, "doc/",4)==0 ){ int j; for(j=7; g.zPath[j] && g.zPath[j]!='/'; j++){} blob_append(cgi_output_blob(), &z[base], i-base); blob_appendf(cgi_output_blob(), "%.*s", j-4, g.zPath+4); base = i+8; } } blob_append(cgi_output_blob(), &z[base], i-base); } /* ** Render a document as the reply to the HTTP request. The body |
︙ | ︙ |
Changes to www/changes.wiki.
1 2 3 4 5 6 7 8 9 10 11 | <title>Change Log</title> <a name='v2_11'></a> <h2>Changes for Version 2.11 (pending)</h2> * Support Markdown in the default ticket configuration. * Rework the "[/help?cmd=grep|fossil grep]" command to be more useful. * Expose the [/help?cmd=redirect-to-https|redirect-to-https] setting to the [/help?cmd=settings|settings] command. * Improve support for CGI on IIS web servers. * The [/help?cmd=/ext|/ext page] can now render index files, | | > | < > > > | | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 | <title>Change Log</title> <a name='v2_11'></a> <h2>Changes for Version 2.11 (pending)</h2> * Support Markdown in the default ticket configuration. * Rework the "[/help?cmd=grep|fossil grep]" command to be more useful. * Expose the [/help?cmd=redirect-to-https|redirect-to-https] setting to the [/help?cmd=settings|settings] command. * Improve support for CGI on IIS web servers. * The [/help?cmd=/ext|/ext page] can now render index files, in the same way as the embedded docs. * Most commands now support the Unix-conventional "<tt>--</tt>" flag to treat all following arguments as filenames instead of flags. * Added the [/help?cmd=mimetypes|mimetypes config setting] (versionable) to enable mimetype overrides and custom definitions. * Add an option on the /Admin/Timeline setup page to set a default timeline style other than "Modern". * In [./embeddeddoc.wiki|embedded documentation], hyperlink URLs of the form "/doc/$CURRENT/..." the "$CURRENT" text is translated into the check-in hash for the document currently being viewed. * Proactive security: Fossil now assumes that the schema of every database it opens has been tampered with by an adversary and takes extra precautions to ensure that such tampering is harmless. * Bug fix: the "fossil git export" command is now working on Windows * Bug fix: display Technote items on the timeline correctly * Bug fix: fix the capability summary matrix of the Security Audit page so that it does not add "anonymous" capabilities to the "nobody" user. * Many documentation enhancements. * Several minor enhancements to existing features. <a name='v2_10'></a> |
︙ | ︙ |
Changes to www/embeddeddoc.wiki.
︙ | ︙ | |||
22 23 24 25 26 27 28 | 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". | | | 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 | 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: <blockquote> <i><baseurl></i><big><b>/doc/</b></big><i><version></i><big><b>/</b></big><i><filename></i> |
︙ | ︙ | |||
77 78 79 80 81 82 83 84 85 86 87 88 89 90 | 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. <a name="html"></a>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> | > > | 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 | 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>1.1 HTML Rendering With Fossil Headers And Footers</h2> <a name="html"></a>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> |
︙ | ︙ | |||
102 103 104 105 106 107 108 | 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]. | | | > | < < | > > | > | | > > > | > > > > | > | > > > > > > > > > > > > > > | > > > > > > > > | | 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 | 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: <nowiki><pre> [Markdown formatting rules]($ROOT/wiki_rules) </pre></nowiki> Depending on how the how the Fossil server is configured, that hyperlink might be renderer like one of the following: <nowiki><pre> <a href="/wiki_rules">Wiki formatting rules</a> <a href="/cgi-bin/fossil/wiki_rules">Wiki formatting rules</a> </pre></nowiki> 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: <nowiki><pre> [Other Document]($ROOT/doc/$CURRENT/www/otherdoc.md) </pre></nowiki> 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> Fossil will substitute the value of [./th1.md | TH1 expressions] within <tt>{</tt> curly braces <tt>}</tt> into the output HTML if you have configured it with the <tt>--with-th1-docs</tt> option, which is disabled by default. Since TH1 is a full scripting language, this feature essential grants the ability to execute code on the server to any 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: |
︙ | ︙ |
Changes to www/mdtest/test1.md.
︙ | ︙ | |||
33 34 35 36 37 38 39 | * Timeline: [](/timeline) * Help: [](/help?cmd=help) * Site-map: [](/sitemap) | | | | | | | | | 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 | * Timeline: [](/timeline) * Help: [](/help?cmd=help) * Site-map: [](/sitemap) ## The Magic $CURRENT Document Version Translation In URI text of the form `.../doc/$CURRENT/...` the $CURRENT value is converted to the version number of the document currently being displayed. This conversion happens after translation into HTML and only occurs on href='...' attributes so it does not occur for plain text. * Document index: [](/doc/$CURRENT/www/index.wiki) Both the $ROOT and the $CURRENT conversions can occur on the same link. * Document index: []($ROOT/doc/$CURRENT/www/index.wiki) The translations must be contained within HTML markup in order to work. They do not work for ordinary text that appears to be an href= attribute. * `x href='$ROOT/timeline'` * `x action="$ROOT/whatever"` * `x href="https://some-other-site.com/doc/$CURRENT/tail"` |