Fossil SCM

The www/customskin.md document hadn't been updated since we removed the explicit <html><head> stuff from the default skins and moved that into the C code so we could insert the CSP and such automatically. Updated it to show the inner <div> tags that you actually get by default now, and talked about how the HTML document wrapper is added automatically. Also fixed some spelling and grammar errors.

wyoung 2019-08-19 01:17 trunk

Commit 9044fd2dbe7a8ac02ae2d976b50f40fd4a75357bd3cb2be73df83c371cc55b14

Parent 3d6a4fd95ce9572…

1 file changed +61 -54

~ www/customskin.md

M www/customskin.md

+61 -54

		--- www/customskin.md
		+++ www/customskin.md
		@@ -9,40 +9,56 @@
9	9	Fossil-Generated Content</td></tr>
10	10	<tr><td style='background-color:lightblue;text-align:center;'>Footer</td></tr>
11	11	<tr><td style='background-color:lightyellow;text-align:center;'>Javascript (optional)</td></tr>
12	12	</tbody></table></blockquote>
13	13
14		-The header and footer control the "look" of Fossil pages. Those
15		-two sections can be customized separately for each repository to
16		-develop a new theme.
17		-
18		-The header will normally look something like this:
19		-
20		- <html>
21		- <head> ... </head>
22		- <body>
23		- ... top banner and menu bar ...
24		- <div class='content'>
25		-
26		-And the footer will look something like this:
27		-
	14	+The default header looks something like this:
	15	+
	16	+ <div class="header">
	17	+ <div class="title"><h1>$<project_name></h1>$<title></div>
	18	+ ... top banner and menu bar ...
	19	+
	20	+The Fossil-generated content section looks like this:
	21	+
	22	+ <div class="content">
	23	+ ... generated content here ...
	24	+ </div>
	25	+
	26	+And the footer looks like this:
	27	+
	28	+ <div class="footer">
	29	+ ... skin-specific stuff here ...
28	30	</div>
29		- ... bottom material ...
30		- </body>
31		- </html>
32		-
33		-The <head> element in the header will normally reference the
34		-/style.css CSS file that Fossil stores internally. (The $stylesheet_url
35		-TH1 variable, described below, is useful for accomplishing this.)
36		-
37		-The middle "content" section comprised the bulk of most pages and
	31	+ <script nonce="$nonce">
	32	+ <th1>styleScript</th1>
	33	+ </script>
	34	+
	35	+Notice that there are no `<html>` or `<head>` elements in the header,
	36	+nor is there an `</html>` closing tag in the footer. Fossil generates
	37	+this material automatically unless it sees that you have provided your
	38	+own HTML document header within the skin’s Header section.
	39	+
	40	+This design lets most users get the benefit of Fossil’s automatic HTML
	41	+document header, which takes care of quite a few different things for
	42	+you, while still allowing you to override if at need. For example, you
	43	+might not agree with Fossil’s default [Content Security Policy][csp]
	44	+which gets set in a `<meta>` tag within this default document header, so
	45	+you could provide your own, which would suppress that code.
	46	+
	47	+When overriding the default document header, you might want to use some
	48	+of the TH1 variables documented below such as `$stylesheet_url`
	49	+to avoid hand-writing code that Fossil can generate for you.
	50	+
	51	+The middle "content" section comprises the bulk of most pages and
38	52	contains the actual Fossil-generated data
39	53	that the user is interested in seeing. The text of this content
40	54	section is not normally configurable. The content text can be styled
41		-using CSS, but it otherwise fixed. Hence it is the header and footer
	55	+using CSS, but it is otherwise fixed. Hence it is the header, the footer,
42	56	and the CSS that determine the look of a repository.
43	57	We call the bundle of built-in CSS, header, and footer a "skin".
	58	+
	59	+[csp]: https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP
44	60
45	61	Built-in Skins
46	62	--------------
47	63
48	64	Fossil comes with several built-in skins. The sources to these built-ins can
		@@ -88,55 +104,46 @@
88	104	necessary.
89	105
90	106	When cloning a repository, the skin of new repository is initialized to
91	107	the skin of the repository from which it was cloned.
92	108
93		-Header And Footer Processing
	109	+Header and Footer Processing
94	110	----------------------------
95	111
96		-The header.txt and footer.txt files of a skin are merely the HTML text
97		-of the header and footer. Except, before being prepended and appended to
98		-the content, the header and footer text are run through a
	112	+The `header.txt` and `footer.txt` files of a skin are merely the HTML text
	113	+of the header and footer, except that before being prepended and appended to
	114	+the content, their text content is run through a
99	115	[TH1 interpreter](./th1.md) that might adjust the text as follows:
100	116
101	117	* All text within <th1>...</th1> is elided from the
102	118	output and that text is instead run as a TH1 script. That TH1
103	119	script has the opportunity to insert new text in place of itself,
104	120	or to inhibit or enable the output of subsequent text.
105	121
106		- * Text for the form "$NAME" or "$<NAME>" is replace with
	122	+ * Text of the form "$NAME" or "$<NAME>" is replaced with
107	123	the value of the TH1 variable NAME.
108	124
109		-For example, the following is the first few lines of a typical
110		-header file:
111		-
112		- <html>
113		- <head>
114		- <base href="$baseurl/$current_page" />
115		- <title>$<project_name>: $<title></title>
116		- <link rel="alternate" type="application/rss+xml" title="RSS Feed"
117		- href="$home/timeline.rss" />
118		- <link rel="stylesheet" href="$stylesheet_url" type="text/css"
119		- media="screen" />
120		- </head>
121		-
122		-After variables are substituted by TH1, the final header text
123		-delivered to the web browser might look something like this:
124		-
125		- <html>
126		- <head>
127		- <base href="https://www.fossil-scm.org/skin2/timeline" />
128		- <title>Fossil: Timeline</title>
129		- <link rel="alternate" type="application/rss+xml" title="RSS Feed"
130		- href="/skin2/timeline.rss" />
131		- <link rel="stylesheet" href="/skin2/style.css?default" type="text/css"
132		- media="screen" />
133		- </head>
	125	+Above, we saw the first few lines of a typical header file:
	126	+
	127	+ <div class="header">
	128	+ <div class="title"><h1>$<project_name></h1>$<title>/div>
	129	+
	130	+After variables are substituted by TH1, that will look more like this:
	131	+
	132	+ <div class="header">
	133	+ <div class="title"><h1>Project Name</h1>Page Title</div>
	134	+
	135	+As you can see, two TH1 variable substitutions were done.
134	136
135	137	The same TH1 interpreter is used for both the header and the footer
136	138	and for all scripts contained within them both. Hence, any global
137	139	TH1 variables that are set by the header are available to the footer.
	140	+
	141	+As pointed out at the start of this document, Fossil provides the HTML
	142	+document container tags `<html>`, `<head>`, and their inner content when
	143	+your skin’s header and footer don’t include them.
	144	+
138	145
139	146	Customizing the ≡ Hamburger Menu
140	147	--------------------------------
141	148
142	149	The menu bar of the default skin has an entry to open a drop-down menu with
143	150

	--- www/customskin.md
	+++ www/customskin.md
	@@ -9,40 +9,56 @@
9	Fossil-Generated Content</td></tr>
10	<tr><td style='background-color:lightblue;text-align:center;'>Footer</td></tr>
11	<tr><td style='background-color:lightyellow;text-align:center;'>Javascript (optional)</td></tr>
12	</tbody></table></blockquote>
13
14	The header and footer control the "look" of Fossil pages. Those
15	two sections can be customized separately for each repository to
16	develop a new theme.
17
18	The header will normally look something like this:
19
20	<html>
21	<head> ... </head>
22	<body>
23	... top banner and menu bar ...
24	<div class='content'>
25
26	And the footer will look something like this:
27


28	</div>
29	... bottom material ...
30	</body>
31	</html>
32
33	The <head> element in the header will normally reference the
34	/style.css CSS file that Fossil stores internally. (The $stylesheet_url
35	TH1 variable, described below, is useful for accomplishing this.)
36
37	The middle "content" section comprised the bulk of most pages and












38	contains the actual Fossil-generated data
39	that the user is interested in seeing. The text of this content
40	section is not normally configurable. The content text can be styled
41	using CSS, but it otherwise fixed. Hence it is the header and footer
42	and the CSS that determine the look of a repository.
43	We call the bundle of built-in CSS, header, and footer a "skin".


44
45	Built-in Skins
46	--------------
47
48	Fossil comes with several built-in skins. The sources to these built-ins can
	@@ -88,55 +104,46 @@
88	necessary.
89
90	When cloning a repository, the skin of new repository is initialized to
91	the skin of the repository from which it was cloned.
92
93	Header And Footer Processing
94	----------------------------
95
96	The header.txt and footer.txt files of a skin are merely the HTML text
97	of the header and footer. Except, before being prepended and appended to
98	the content, the header and footer text are run through a
99	[TH1 interpreter](./th1.md) that might adjust the text as follows:
100
101	* All text within <th1>...</th1> is elided from the
102	output and that text is instead run as a TH1 script. That TH1
103	script has the opportunity to insert new text in place of itself,
104	or to inhibit or enable the output of subsequent text.
105
106	* Text for the form "$NAME" or "$<NAME>" is replace with
107	the value of the TH1 variable NAME.
108
109	For example, the following is the first few lines of a typical
110	header file:
111
112	<html>
113	<head>
114	<base href="$baseurl/$current_page" />
115	<title>$<project_name>: $<title></title>
116	<link rel="alternate" type="application/rss+xml" title="RSS Feed"
117	href="$home/timeline.rss" />
118	<link rel="stylesheet" href="$stylesheet_url" type="text/css"
119	media="screen" />
120	</head>
121
122	After variables are substituted by TH1, the final header text
123	delivered to the web browser might look something like this:
124
125	<html>
126	<head>
127	<base href="https://www.fossil-scm.org/skin2/timeline" />
128	<title>Fossil: Timeline</title>
129	<link rel="alternate" type="application/rss+xml" title="RSS Feed"
130	href="/skin2/timeline.rss" />
131	<link rel="stylesheet" href="/skin2/style.css?default" type="text/css"
132	media="screen" />
133	</head>
134
135	The same TH1 interpreter is used for both the header and the footer
136	and for all scripts contained within them both. Hence, any global
137	TH1 variables that are set by the header are available to the footer.





138
139	Customizing the ≡ Hamburger Menu
140	--------------------------------
141
142	The menu bar of the default skin has an entry to open a drop-down menu with
143

	--- www/customskin.md
	+++ www/customskin.md
	@@ -9,40 +9,56 @@
9	Fossil-Generated Content</td></tr>
10	<tr><td style='background-color:lightblue;text-align:center;'>Footer</td></tr>
11	<tr><td style='background-color:lightyellow;text-align:center;'>Javascript (optional)</td></tr>
12	</tbody></table></blockquote>
13
14	The default header looks something like this:
15
16	<div class="header">
17	<div class="title"><h1>$<project_name></h1>$<title></div>
18	... top banner and menu bar ...
19
20	The Fossil-generated content section looks like this:
21
22	<div class="content">
23	... generated content here ...
24	</div>
25
26	And the footer looks like this:
27
28	<div class="footer">
29	... skin-specific stuff here ...
30	</div>
31	<script nonce="$nonce">
32	<th1>styleScript</th1>
33	</script>
34
35	Notice that there are no `<html>` or `<head>` elements in the header,
36	nor is there an `</html>` closing tag in the footer. Fossil generates
37	this material automatically unless it sees that you have provided your
38	own HTML document header within the skin’s Header section.
39
40	This design lets most users get the benefit of Fossil’s automatic HTML
41	document header, which takes care of quite a few different things for
42	you, while still allowing you to override if at need. For example, you
43	might not agree with Fossil’s default [Content Security Policy][csp]
44	which gets set in a `<meta>` tag within this default document header, so
45	you could provide your own, which would suppress that code.
46
47	When overriding the default document header, you might want to use some
48	of the TH1 variables documented below such as `$stylesheet_url`
49	to avoid hand-writing code that Fossil can generate for you.
50
51	The middle "content" section comprises the bulk of most pages and
52	contains the actual Fossil-generated data
53	that the user is interested in seeing. The text of this content
54	section is not normally configurable. The content text can be styled
55	using CSS, but it is otherwise fixed. Hence it is the header, the footer,
56	and the CSS that determine the look of a repository.
57	We call the bundle of built-in CSS, header, and footer a "skin".
58
59	[csp]: https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP
60
61	Built-in Skins
62	--------------
63
64	Fossil comes with several built-in skins. The sources to these built-ins can
	@@ -88,55 +104,46 @@
104	necessary.
105
106	When cloning a repository, the skin of new repository is initialized to
107	the skin of the repository from which it was cloned.
108
109	Header and Footer Processing
110	----------------------------
111
112	The `header.txt` and `footer.txt` files of a skin are merely the HTML text
113	of the header and footer, except that before being prepended and appended to
114	the content, their text content is run through a
115	[TH1 interpreter](./th1.md) that might adjust the text as follows:
116
117	* All text within <th1>...</th1> is elided from the
118	output and that text is instead run as a TH1 script. That TH1
119	script has the opportunity to insert new text in place of itself,
120	or to inhibit or enable the output of subsequent text.
121
122	* Text of the form "$NAME" or "$<NAME>" is replaced with
123	the value of the TH1 variable NAME.
124
125	Above, we saw the first few lines of a typical header file:
126
127	<div class="header">
128	<div class="title"><h1>$<project_name></h1>$<title>/div>
129
130	After variables are substituted by TH1, that will look more like this:
131
132	<div class="header">
133	<div class="title"><h1>Project Name</h1>Page Title</div>
134
135	As you can see, two TH1 variable substitutions were done.














136
137	The same TH1 interpreter is used for both the header and the footer
138	and for all scripts contained within them both. Hence, any global
139	TH1 variables that are set by the header are available to the footer.
140
141	As pointed out at the start of this document, Fossil provides the HTML
142	document container tags `<html>`, `<head>`, and their inner content when
143	your skin’s header and footer don’t include them.
144
145
146	Customizing the ≡ Hamburger Menu
147	--------------------------------
148
149	The menu bar of the default skin has an entry to open a drop-down menu with
150

Fossil SCM

Keyboard Shortcuts