Fossil

Check-in [45427ae1]
Login

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 | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: 45427ae1c9312bd81f272dfe8c080a0bc42e1fa30c9b660a1088020f0daba84b
User & Date: drh 2020-02-12 16:35:45
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
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to src/doc.c.

683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
...
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733

/*
** Transfer content to the output.  During the transfer, when text of
** the following form is seen:
**
**       href="$ROOT/..."
**       action="$ROOT/..."
**       href=".../doc/$SELF/..."
**
** Convert $ROOT to the root URI of the repository, and $SELF 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){
................................................................................
     && 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/$SELF/", 11)==0
     && isWithinHref(z,i-5)
     && isWithinHtmlMarkup(z, i-5)
     && strncmp(g.zPath, "doc/",4)==0
    ){
      int j;
      for(j=4; 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+5;
    }
  }
  blob_append(cgi_output_blob(), &z[base], i-base);
}

/*
** Render a document as the reply to the HTTP request.  The body







|

|







 







|





|


|







683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
...
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733

/*
** 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){
................................................................................
     && 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.

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

  *  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,
     analog to how the embedded docs do.
  *  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 the ability to set a default timeline style other than
     "Modern".



  *  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 of 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>







|





>
|
<
>
>
>




|







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

  *  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
29
30
31
32
33
34
35
36
..
77
78
79
80
81
82
83


84
85
86
87
88
89
90
...
102
103
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
  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".

<h2>Fossil Support For Embedded Documentation</h2>

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>&lt;baseurl&gt;</i><big><b>/doc/</b></big><i>&lt;version&gt;</i><big><b>/</b></big><i>&lt;filename&gt;</i>
................................................................................
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 &lt;div&gt; element like this:

    <b>&lt;div class='fossil-doc' data-title='<i>Title Text</i>'&gt;</b>

................................................................................
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].


<h2>Server-Side Text Substitution</h2>

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

<h3>1. $ROOT</h3>

To allow for repositories [./server/ | served deeper than the root of the
URL hierarchy], Fossil can substitute the repository's root in the URL
scheme into HTML <tt>href</tt> and <tt>action</tt> attributes. For
example:


<nowiki><pre>
        [$ROOT/doc.wiki | doc at project root]

</pre></nowiki>

might become this in the rendered HTML:



<nowiki><pre>
        &lt;a href="/project/root/doc.wiki"&gt;doc at project root&lt;/a&gt;


</pre></nowiki>

As you can see, this happens for all source document types that end up
rendering as HTML, not just source documents in the HTML
<tt>fossil-doc</tt> format described at the end of the prior section.


























<h3 id="th1">2. TH1 Documents</h3>

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.










<h2>Examples</h2>

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:








|







 







>
>







 







|




|

|
|
|
|
>


<
>


<
>
>


<
>
>


<
<
<
>
>

>
>
>
>

>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|






>
>
>
>
>
>
>

>
|







22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
..
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
...
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
  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>&lt;baseurl&gt;</i><big><b>/doc/</b></big><i>&lt;version&gt;</i><big><b>/</b></big><i>&lt;filename&gt;</i>
................................................................................
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 &lt;div&gt; element like this:

    <b>&lt;div class='fossil-doc' data-title='<i>Title Text</i>'&gt;</b>

................................................................................
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:

<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>

        &lt;a href="/wiki_rules"&gt;Wiki formatting rules&lt;/a&gt;
        &lt;a href="/cgi-bin/fossil/wiki_rules"&gt;Wiki formatting rules&lt;/a&gt;
</pre></nowiki>




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:

<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
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 $SELF Document Version Translation

In URI text of the form `.../doc/$SELF/...` the
$SELF 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/$SELF/www/index.wiki)

Both the $ROOT and the $SELF conversions can occur on the same link.

  *   Document index:  []($ROOT/doc/$SELF/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/$SELF/tail"`







|

|
|




|

|

|






|
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"`