Fossil SCM

Many improvements to the "Use of JavaScript in Fossil" document, www/javascript.md, inspired by the recent Ajaxifications and forum commentary on the topic.

wyoung 2020-08-20 04:18 trunk merge

Commit 977ba78fdd2901e5bf25fee4878175ad952d14f34dc9c7e1be5c4ab9926de13a

Parent 100b4868ddf0700…

1 file changed +351 -134

~ www/javascript.md

M www/javascript.md

+351 -134

		--- www/javascript.md
		+++ www/javascript.md
		@@ -1,28 +1,28 @@
1	1	# Use of JavaScript in Fossil
2	2
3		-## Philosophy
	3	+## Philosophy & Policy
4	4
5	5	The Fossil development project’s policy is to use JavaScript where it
6	6	helps make its web UI better, but to offer graceful fallbacks wherever
7		-practical. The intent is that the UI be usable with JavaScript entirely
8		-disabled. In every place where Fossil uses JavaScript, it is an
9		-enhancement to provided functionality, and there is always another way
10		-to accomplish a given end without using JavaScript.
	7	+practical. The intent is that the UI be usable with JavaScript
	8	+entirely disabled. In almost all places where Fossil uses JavaScript,
	9	+it is an enhancement to provided functionality, and there is always
	10	+another way to accomplish a given end without using JavaScript.
11	11
12	12	This is not to say that Fossil’s fall-backs for such cases are always as
13	13	elegant and functional as a no-JS purist might wish. That is simply
14		-because [the vast majority of web users run with JS enabled](#stats),
15		-and a minority of those run with some kind of conditional JavaScript
16		-blocking in place. Fossil’s active developers do not deviate from that
	14	+because [the vast majority of web users run with JavaScript enabled](#stats),
	15	+and a minority of those run with some kind of [conditional JavaScript
	16	+blocking](#block) in place. Fossil’s active developers do not deviate from that
17	17	norm enough that we have many no-JS purists among us, so the no-JS case
18	18	doesn’t get as much attention as some might want. We do [accept code
19	19	contributions][cg], and we are philosophically in favor of graceful
20	20	fall-backs, so you are welcome to appoint yourself the position of no-JS
21	21	czar for the Fossil project!
22	22
23		-Evil is in actions, not in nouns, so we do not believe JavaScript can
	23	+Evil is in actions, not in nouns: we do not believe JavaScript can
24	24	be evil. It is an active technology, but the actions that matter here
25	25	are those of writing the code and checking it into the Fossil project
26	26	repository. None of the JavaScript code in Fossil is evil, a fact we
27	27	enforce by being careful about who we give check-in rights on the
28	28	repository to and by policing what code does get contributed. The Fossil
		@@ -30,98 +30,265 @@
30	30
31	31	We think it’s better to ask not whether Fossil requires JavaScript but
32	32	whether Fossil uses JavaScript well, so that [you can decide](#block)
33	33	to block or allow Fossil’s use of JavaScript.
34	34
	35	+The Fossil developers want to see the project thrive, and we achieve
	36	+that best by making it usable and friendly to a wider audience than the
	37	+minority of static web app purists. Modern users generally expect a
	38	+smoother experience than was available with 1990s style HTTP
	39	+POST-and-response `<form>` based interaction. We also increase the set
	40	+of potential Fossil developers if we do not restrict them to such
	41	+antiquated methods.
	42	+
	43	+JavaScript is not perfect, but it's what we have, so we will use it
	44	+where we find it advantageous.
	45	+
35	46	[cg]: ./contribute.wiki
36	47
37	48
38		-## <a id="block"></a>Blocking JavaScript
39		-
40		-Rather than either block JavaScript wholesale or give up on blocking
41		-JavaScript entirely, we recommend that you use tools like [NoScript][ns]
42		-or [uBlock Origin][ub] to selectively block problematic uses of
43		-JavaScript so the rest of the web can use the technology productively,
44		-as it was intended. There are doubtless other useful tools of this sort;
45		-we recommend only these two due to our limited experience, not out of
46		-any wish to exclude other tools.
47		-
48		-The primary difference between these two for our purposes is that
49		-NoScript lets you select scripts to run on a page on a case-by-case
50		-basis, whereas uBlock Origin delegates those choices to a group of
51		-motivated volunteers who maintain whitelists and blacklists to control
52		-all of this; you can then override UBO’s stock rules as needed.
53		-
54		-[ns]: https://noscript.net/
55		-[ub]: https://github.com/gorhill/uBlock/
56		-
57		-
58		-## <a id="stats"></a>How Many Users Run with JavaScript Disabled Anyway?
59		-
60		-There are several studies that have directly measured the web audience
61		-to answer this question:
62		-
63		-* [What percentage of browsers with javascript disabled?][s1]
64		-* [How many people are missing out on JavaScript enhancement?][s2]
65		-* [Just how many web users really disable cookies or JavaScript?][s3]
66		-
67		-Our sense of this data is that only about 0.2% of web users had
68		-JavaScript disabled while participating in these studies.
69		-
70		-The Fossil user community is not typical of the wider web, but if we
71		-were able to comprehensively survey our users, we’d expect to find an
72		-interesting dichotomy. Because Fossil is targeted at software
73		-developers, who in turn are more likely to be power-users, we’d expect
74		-to find Fossil users to be more in favor of some amount of JavaScript
75		-blocking than the average web user. Yet, we’d also expect to find that
76		-our user base has a disproportionately high number who run [powerful
77		-conditional blocking plugins](#block) in their browsers, rather than
78		-block JS entirely. We suspect that between these two forces, the number
79		-of no-JS purists among Fossil’s user base is still a tiny minority.
80		-
81		-[s1]: https://blockmetry.com/blog/javascript-disabled
82		-[s2]: https://gds.blog.gov.uk/2013/10/21/how-many-people-are-missing-out-on-javascript-enhancement/
83		-[s3]: https://w3techs.com/technologies/overview/client_side_language/all
84		-
85		-
86		-## <a id="3pjs"></a>No Third-Party JavaScript in Fossil
87		-
88		-Fossil does not use any third-party JavaScript libraries, not even very
89		-common ones like jQuery. Every bit of JavaScript served by the stock
90		-version of Fossil was written specifically for the Fossil project and is
91		-stored [in its code repository](https://fossil-scm.org/fossil/file).
92		-
93		-Therefore, if you want to hack on the JavaScript code served by Fossil
94		-and mechanisms like [skin editing][cs] don’t suffice for your purposes,
95		-you can hack on the JavaScript in your local instance directly, just as
96		-you can hack on its C, SQL, and Tcl code. Fossil is free and open source
97		-software, under [a single license][2cbsd].
98		-
99		-[2cbsd]: https://fossil-scm.org/home/doc/trunk/COPYRIGHT-BSD2.txt
100		-[cs]: ./customskin.md
101		-
102		-
103		-## <a id="snoop"></a>Fossil Does Not Snoop On You
104		-
105		-There is no tracking or other snooping technology in Fossil other than
106		-that necessary for basic security, such as IP address logging on
107		-check-ins. (This is in part why we have no [comprehensive user
108		-statistics](#stats)!)
109		-
110		-Fossil attempts to set two cookies on all web clients: a login session
111		-cookie and a display preferences cookie. These cookies are restricted to
112		-the Fossil instance, so even this limited data cannot leak between
113		-Fossil instances or into other web sites.
114		-
115		-There is some server-side event logging, but that is done entirely
116		-without JavaScript, so it’s off-topic here.
117		-
	49	+## <a id="debate"></a>Arguments Against JavaScript & Our Rebuttals
	50	+
	51	+There many common arguments against the use of JavaScript. Rather than
	52	+rehash these same arguments on the [forum][ffor], we distill the common
	53	+ones we’ve heard before and give our stock answers to them here:
	54	+
	55	+1. “It increases the size of the page download.”
	56	+
	57	+ The heaviest such pages served by Fossil only have about 8 kB of
	58	+ compressed JavaScript. (You have to go out of your way to get Fossil
	59	+ to serve uncompressed pages.) This is negligible, even over very
	60	+ slow data connnections. If you are still somehow on a 56 kbit/sec
	61	+ analog telephone modem, this extra script code would download in
	62	+ about a second.
	63	+
	64	+ Most JavaScript-based Fossil pages use less code than that.
	65	+
	66	+ Atop that, Fossil 2.12 adds new script delivery methods with
	67	+ aggressive caching enabled so that typical page loads will skip
	68	+ re-loading this content on subsequent loads. These features are
	69	+ currently optional: you must either set the new [`fossil server
	70	+ --jsmode` option][fsrv] or the corresponding `jsmode` control line
	71	+ in your [`fossil cgi`][fcgi] script when setting up your
	72	+ [Fossil server][fshome]. That done, Fossil’s JavaScript files will
	73	+ load almost instantly from the browser’s cache after the initial
	74	+ page load, rather than be re-transferred over the network.
	75	+
	76	+ Between the improved caching and the fact that it’s quicker to
	77	+ transfer a partial Ajax page load than reload the entire page, the
	78	+ aggregate cost of such pages is typically lower than the older
	79	+ methods based on HTTP POST with a full server round-trip. You can
	80	+ expect to recover the cost of the initial page load in 1-2
	81	+ round-trips. If we were to double the amount of JavaScript code in
	82	+ Fossil, the payoff time would increase to 2-4 round-trips.
	83	+
	84	+2. “JavaScript is slow.”
	85	+
	86	+ It was, before September 2008. Google's introduction of [their V8
	87	+ JavaScript engine][v8] taught the world that JavaScript need not be
	88	+ slow. This competitive pressure caused the other common JavaScript
	89	+ interpreters to either improve or be replaced by one of the engines
	90	+ that did improve to approach V8’s speed.
	91	+
	92	+ Nowadays JavaScript is, as a rule, astoundingly fast. As the world
	93	+ continues to move more and more to web-based applications and
	94	+ services, JavaScript engine developers have ample motivation to keep
	95	+ their engines fast and competitive.
	96	+
	97	+ Once the scripts are cached, Ajax based page updates are faster than
	98	+ the alternative, a full HTTP POST round-trip.
	99	+
	100	+3. <a id="3pjs"></a>“Third-party JavaScript cannot be trusted.”
	101	+
	102	+ Fossil does not use any third-party JavaScript libraries, not even
	103	+ very common ones like jQuery. Every bit of JavaScript served by the
	104	+ stock version of Fossil was written specifically for the Fossil
	105	+ project and is stored [in its code repository][fsrc].
	106	+
	107	+ Therefore, if you want to hack on the JavaScript code served by
	108	+ Fossil and mechanisms like [skin editing][cskin] don’t suffice for your
	109	+ purposes, you can hack on the JavaScript in your local instance
	110	+ directly, just as you can hack on its C, SQL, and Tcl code. Fossil
	111	+ is free and open source software, under [a single license][2cbsd].
	112	+
	113	+4. <a id="snoop"></a>“JavaScript and cookies are used to snoop on web users.”
	114	+
	115	+ There is no tracking or other snooping technology in Fossil other than
	116	+ that necessary for basic security, such as IP address logging on
	117	+ check-ins. (This is in part why we have no [comprehensive user
	118	+ statistics](#stats)!)
	119	+
	120	+ Fossil attempts to set two cookies on all web clients: a login session
	121	+ cookie and a display preferences cookie. These cookies are restricted to
	122	+ the Fossil instance, so even this limited data cannot leak between
	123	+ Fossil instances or into other web sites.
	124	+
	125	+5. “JavaScript is fundamentally insecure.”
	126	+
	127	+ JavaScript is certainly sometimes used for nefarious ends, but if we
	128	+ wish to have more features in Fossil, the alternative is to add more
	129	+ code to the Fossil binary, [most likely in C][fslpl], a language
	130	+ implicated in [over 4× more security vulnerabilities][whmsl].
	131	+
	132	+ Therefore, does it not make sense to place approximately four times
	133	+ as much trust in Fossil’s JavaScript code as in its C code?
	134	+
	135	+ The question is not whether JavaScript is itself evil, it is whether
	136	+ its authors are evil. Every byte of JavaScript code used within
	137	+ the Fossil UI is:
	138	+
	139	+ * ...written by the Fossil developers, vetted by their peers.
	140	+
	141	+ * ...[open source][flic] and [available][fsrc] to be inspected,
	142	+ audited, and changed by its users.
	143	+
	144	+ * ...compiled directly into the `fossil` binary in a
	145	+ non-obfuscated form during the build process, so there are no
	146	+ third-party servers delivering mysterious, obfuscated JavaScript
	147	+ code blobs to the user.
	148	+
	149	+ Local administrators can [modify the repository’s skin][cskin] to
	150	+ inject additional JavaScript code into pages served by their Fossil
	151	+ server. A typical case is to add a syntax highlighter like
	152	+ [Prism.js][pjs] or [highlightjs][hljs] to the local repository. At
	153	+ that point, your trust concern is not with Fossil’s use of
	154	+ JavaScript, but with your trust in that repository’s administrator.
	155	+
	156	+ Fossil's [default content security policy][dcsp] (CSP)
	157	+ prohibits execution of JavaScript code which is delivered from
	158	+ anywhere but the Fossil server which delivers the page. A local
	159	+ administrator can change this CSP, but again this comes down to a
	160	+ matter of trust with the administrator, not with Fossil itself.
	161	+
	162	+6. “Cross-browser compatibility is poor.”
	163	+
	164	+ It most certainly was in the first decade or so of JavaScript’s
	165	+ lifetime, resulting in the creation of powerful libraries like
	166	+ jQuery to patch over the incompatibilities. Over time, the need for
	167	+ such libraries has dropped as browser vendors have fixed the
	168	+ incompatibilities. Cross-browser JavaScript compatibility issues
	169	+ which affect web developers are, by and large, a thing of the past.
	170	+
	171	+7. “Fossil UI works fine today without JavaScript. Why break it?”
	172	+
	173	+ While this is true today, and we have no philosophical objection to
	174	+ it remaining true, we do not intend to limit ourselves to only those
	175	+ features that can be created without JavaScript. The mere
	176	+ availability of alternatives is not a good justification for holding
	177	+ back on notable improvements when they're within easy reach.
	178	+
	179	+ The no-JS case is a [minority position](#stats), so those that want
	180	+ Fossil to have no-JS alternatives and graceful fallbacks will need
	181	+ to get involved with the development if they want this state of
	182	+ affairs to continue.
	183	+
	184	+8. <a id="stats"></a>“A large number of users run without JavaScript enabled.”
	185	+
	186	+ That’s not what web audience measurements say:
	187	+
	188	+ * [What percentage of browsers with javascript disabled?][s1]
	189	+ * [How many people are missing out on JavaScript enhancement?][s2]
	190	+ * [Just how many web users really disable cookies or JavaScript?][s3]
	191	+
	192	+ Our sense of this data is that only about 0.2% of web users had
	193	+ JavaScript disabled while participating in these studies.
	194	+
	195	+ The Fossil user community is not typical of the wider web, but if we
	196	+ were able to comprehensively survey our users, we’d expect to find
	197	+ an interesting dichotomy. Because Fossil is targeted at software
	198	+ developers, who in turn are more likely to be power-users, we’d
	199	+ expect to find Fossil users to be more in favor of some amount of
	200	+ JavaScript blocking than the average web user. Yet, we’d also expect
	201	+ to find that our user base has a disproportionately high number who
	202	+ run [powerful conditional blocking plugins](#block) in their
	203	+ browsers, rather than block JavaScript entirely. We suspect that
	204	+ between these two forces, the number of no-JS purists among Fossil’s
	205	+ user base is still a tiny minority.
	206	+
	207	+9. <a id="block"></a>“I block JavaScript entirely in my browser. That breaks Fossil.”
	208	+
	209	+ First, see our philosophy statements above. Briefly, we intend that
	210	+ there always be some other way to get any given result without using
	211	+ JavaScript, developer interest willing.
	212	+
	213	+ But second, it doesn’t have to be all-or-nothing. We recommend that
	214	+ those interested in blocking problematic uses of JavaScript use
	215	+ tools like [NoScript][ns] or [uBlock Origin][ubo] to selectively
	216	+ block JavaScript so the rest of the web can use the technology
	217	+ productively, as it was intended.
	218	+
	219	+ There are doubtless other useful tools of this sort. We recommend
	220	+ these two only from our limited experience, not out of any wish to
	221	+ exclude other tools.
	222	+
	223	+ The primary difference between these two for our purposes is that
	224	+ NoScript lets you select scripts to run on a page on a case-by-case
	225	+ basis, whereas uBlock Origin delegates those choices to a group of
	226	+ motivated volunteers who maintain allow/block lists to control all
	227	+ of this; you can then override UBO’s stock rules as needed.
	228	+
	229	+
	230	+10. “*My browser doesn’t even have* a JavaScript interpreter.**”
	231	+
	232	+ The Fossil open source project has no full-time developers, and only
	233	+ a few of these part-timers are responsible for the bulk of the code
	234	+ in Fossil. If you want Fossil to support such niche use cases, then
	235	+ you will have to [get involved with its development][cg]: it’s
	236	+ your uncommon itch.
	237	+
	238	+11. <a id="compat"></a>“Fossil’s JavaScript code isn’t compatible with my browser.”
	239	+
	240	+ The Fossil project’s developers aim to remain compatible with
	241	+ the largest portions of the client-side browser base. We use only
	242	+ standards-defined JavaScript features which are known to work in the
	243	+ overwhelmingly vast majority of browsers going back approximately 5
	244	+ years, at minimum, as documented by [Can I Use...?][ciu] We avoid use of
	245	+ features added to the language more recently or those which are still in
	246	+ flux in standards committees.
	247	+
	248	+ We set this threshold based on the amount of time it typically takes for
	249	+ new standards to propagate through the installed base.
	250	+
	251	+ As of this writing, this means we are only using features defined in
	252	+ [ECMAScript 2015][es2015], colloquially called “JavaScript 6.” That
	253	+ is a sufficiently rich standard that it more than suffices for our
	254	+ purposes, and it is [widely deployed][es6dep]. The biggest single
	255	+ outlier remaining is MSIE 11, and [even Microsoft is moving their
	256	+ own products off of it][ie11x].
	257	+
	258	+[2cbsd]: https://fossil-scm.org/home/doc/trunk/COPYRIGHT-BSD2.txt
	259	+[ciu]: https://caniuse.com/
	260	+[cskin]: ./customskin.md
	261	+[dcsp]: ./defcsp.md
	262	+[es2015]: https://ecma-international.org/ecma-262/6.0/
	263	+[es6dep]: https://caniuse.com/#feat=es6
	264	+[fcgi]: /help?cmd=cgi
	265	+[ffor]: https://fossil-scm.org/forum/
	266	+[flic]: /doc/trunk/COPYRIGHT-BSD2.txt
	267	+[fshome]: /doc/trunk/www/server/
	268	+[fslpl]: /doc/trunk/www/fossil-v-git.wiki#portable
	269	+[fsrc]: https://fossil-scm.org/home/file/src
	270	+[fsrv]: /help?cmd=server
	271	+[hljs]: https://fossil-scm.org/forum/forumpost/9150bc22ca
	272	+[ie11x]: https://techcommunity.microsoft.com/t5/microsoft-365-blog/microsoft-365-apps-say-farewell-to-internet-explorer-11-and/ba-p/1591666
	273	+[ns]: https://noscript.net/
	274	+[pjs]: https://fossil-scm.org/forum/forumpost/1198651c6d
	275	+[s1]: https://blockmetry.com/blog/javascript-disabled
	276	+[s2]: https://gds.blog.gov.uk/2013/10/21/how-many-people-are-missing-out-on-javascript-enhancement/
	277	+[s3]: https://w3techs.com/technologies/overview/client_side_language/all
	278	+[ubo]: https://github.com/gorhill/uBlock/
	279	+[v8]: https://en.wikipedia.org/wiki/V8_(JavaScript_engine)
	280	+[whmsl]: https://www.whitesourcesoftware.com/most-secure-programming-languages/
	281	+
	282	+
	283	+----
118	284
119	285	## <a id="uses"></a>Places Where Fossil’s Web UI Uses JavaScript
120	286
121		-The remainder of this document will explain how Fossil currently uses
122		-JavaScript and what it does when these uses are blocked.
	287	+This section documents the areas where Fossil currently uses JavaScript
	288	+and what it does when these uses are blocked. It also gives common
	289	+workarounds where necessary.
123	290
124	291
125	292	### <a id="timeline"></a>Timeline Graph
126	293
127	294	Fossil’s [web timeline][wt] uses JavaScript to render the graph
		@@ -140,22 +307,22 @@
140	307	command, by clicking around within the web UI, etc.
141	308
142	309	_Potential Workaround:_ The timeline could be enhanced with `<noscript>`
143	310	tags that replace the graph with a column of checkboxes that control
144	311	what a series of form submit buttons do when clicked, replicating the
145		-current JS-based features of the graph using client-server round-trips.
	312	+current JavaScript-based features of the graph using client-server round-trips.
146	313	For example, you could click two of those checkboxes and then a button
147	314	labeled “Diff Selected” to replicate the current “click two nodes to
148	315	diff them” feature.
149	316
150	317	[wt]: https://fossil-scm.org/fossil/timeline
151	318
152	319
153	320	### <a id="wedit"></a>The New Wiki Editor
154	321
155		-As of Fossil 2.12, the [Fossil wiki][fwt] document editor requires
156		-JavaScript, for a few unavoidable reasons.
	322	+The [new wiki editor][fwt] added in Fossil 2.12 has many new features, a
	323	+few of which are impossible to get without use of JavaScript.
157	324
158	325	First, it allows in-browser previews without losing client-side editor
159	326	state, such as where your cursor is. With the old editor, you had to
160	327	re-locate the place you were last editing on each preview, which would
161	328	reduce the incentive to use the preview function. In the new wiki
		@@ -174,14 +341,10 @@
174	341	that there is a way for the app to restore its prior state from
175	342	persistent media when it’s restarted, giving the illusion that it was
176	343	never shut down in the first place. This feature of Fossil’s new wiki
177	344	editor provides that.
178	345
179		-There are many other new features in the enhanced Fossil 2.12 wiki
180		-editor, but those are the ones that absolutely require JavaScript to
181		-work.
182		-
183	346	With this change, we lost the old WYSIWYG wiki editor, available since
184	347	Fossil version 1.24. It hadn’t been maintained for years, it was
185	348	disabled by default, and no one stepped up to defend its existence when
186	349	this new editor was created, replacing it. If someone rescues that
187	350	feature, merging it in with the new editor, it will doubtless require
		@@ -192,34 +355,36 @@
192	355
193	356	_Graceful Fallback:_ Unlike in the Fossil 2.11 and earlier days, there
194	357	is no longer a script-free wiki editor mode. This is not from lack of
195	358	desire, only because the person who wrote the new wiki editor didn’t
196	359	want to maintain three different editors. (New Ajaxy editor, old
197		-script-free HTML form based editor, and old WYSIWYG JS-based editor.) If
198		-someone wants to implement a `<noscript>` alternative to the new wiki
199		-editor, we will likely accept that [contribution][cg] as long as it
200		-doensn’t interfere with the new editor. (The same goes for adding a
201		-WYSIWYG mode to the new Ajaxy wiki editor.)
	360	+script-free HTML form based editor, and the old WYSIWYG JavaScript-based
	361	+editor.) If someone wants to implement a `<noscript>` alternative to the
	362	+new wiki editor, we will likely accept that [contribution][cg] as long
	363	+as it doesn’t interfere with the new editor. (The same goes for adding
	364	+a WYSIWYG mode to the new Ajaxy wiki editor.)
202	365
203	366	_Workaround:_ You don’t have to use the browser-based wiki editor to
204	367	maintain your repository’s wiki at all. Fossil’s [`wiki` command][fwc]
205	368	lets you manipulate wiki documents from the command line. For example,
206		-consider this `vi` based workflow:
	369	+consider this Vi based workflow:
207	370
208	371	```shell
209		- $ vi 'My Article.wiki' # write, write, write...
210		- :!fossil create 'My Article' '%' # current file (%) to new article
	372	+ $ vi 'My Article.wiki' # begin work on new article
	373	+ ...write, write, write...
	374	+ :w # save changes to disk copy
	375	+ :!fossil wiki create 'My Article' '%' # current file (%) to new article
211	376	...write, write, write some more...
212		- :w # save changes to disk copy
213		- :!fossil commit 'My Article' '%' # update article from disk
	377	+ :w # save again
	378	+ :!fossil wiki commit 'My Article' '%' # update article from disk
214	379	:q # done writing for today
215	380
216	381	....days later...
217	382	$ vi # work sans named file today
218		- :r !fossil wiki export 'My Article' - # article text into vi buffer
	383	+ :r !fossil wiki export 'My Article' - # pull article text into vi buffer
219	384	...write, write, write yet more...
220		- :w !fossil wiki commit - # update article with buffer
	385	+ :w !fossil wiki commit - # vi buffer updates article
221	386	```
222	387
223	388	Extending this concept to other text editors is an exercise left to the
224	389	reader.
225	390
		@@ -251,32 +416,35 @@
251	416	would have no local backup if something crashes, etc. Still, we are
252	417	likely to accept such a [contribution][cg] as long as it doesn’t
253	418	interfere with the new editor.
254	419
255	420	[edoc]: /doc/trunk/www/embeddeddoc.wiki
256		-[fedit]: /help?cmd=/fileedit
	421	+[fedit]: /doc/trunk/www/fileedit-page.md
257	422
258	423
259	424	### <a id="ln"></a>Line Numbering
260	425
261	426	When viewing source files, Fossil offers to show line numbers in some
262	427	cases. ([Example][mainc].) Toggling them on and off is currently handled
263	428	in JavaScript, rather than forcing a page-reload via a button click.
264	429
265		-_Workaround:_ Edit the URL to give the “`ln`” query parameter per [the
266		-`/file` docs](/help?cmd=/file). Alternately, someone sufficiently
267		-interested could [provide a patch][cg] to add a `<noscript>` wrapped
268		-HTML button that would reload the page with this parameter
269		-included/excluded to implement the toggle via a server round-trip.
	430	+_Workaround:_ Manually edit the URL to give the “`ln`” query parameter
	431	+per [the `/file` docs](/help?cmd=/file).
	432	+
	433	+_Potential Better Workaround:_ Someone sufficiently interested could
	434	+[provide a patch][cg] to add a `<noscript>` wrapped HTML button that
	435	+would reload the page with this parameter included/excluded to implement
	436	+the toggle via a server round-trip.
270	437
271	438	As of Fossil 2.12, there is also a JavaScript-based interactive method
272	439	for selecting a range of lines by clicking the line numbers when they’re
273	440	visible, then copying the resulting URL to share your selection with
274	441	others.
275	442
276		-_Workaround:_ These interactive features absolutely require JavaScript.
277		-The alternative is to manually edit the URL, per above.
	443	+_Workaround:_ These interactive features would be difficult and
	444	+expensive (in terms of network I/O) to implement without JavaScript. A
	445	+far simpler alternative is to manually edit the URL, per above.
278	446
279	447	[mainc]: https://fossil-scm.org/fossil/artifact?ln&name=87d67e745
280	448
281	449
282	450	### <a id="sxsdiff"></a>Side-by-Side Diff Mode
		@@ -322,12 +490,12 @@
322	490	similar, hovering over that check-in shows a tooltip with details about
323	491	the type of artifact the hash refers to and allows you to click to copy
324	492	the hash to the clipboard.
325	493
326	494	_Graceful Fallback:_ When JavaScript is disabled, these tooltips simply
327		-don’t appear. You can then select and copy the hash using your browser,
328		-make “`fossil info`” queries on those hashes, etc.
	495	+don’t appear, but you can still select and copy the hash using your
	496	+platform’s “copy selected text” feature.
329	497
330	498
331	499	### <a id="bots"></a>Anti-Bot Defenses
332	500
333	501	Fossil has [anti-bot defenses][abd], and it has some JavaScript code
		@@ -352,26 +520,75 @@
352	520
353	521	_Graceful Fallback:_ Clicking the hamburger menu button with JavaScript
354	522	disabled will take you to the `/sitemap` page instead of showing a
355	523	simplified version of that page’s content in a drop-down.
356	524
357		-_Workaround:_ You can remove this button by [editing the skin][cs]
	525	+_Workaround:_ You can remove this button by [editing the skin][cskin]
358	526	header.
359	527
360	528
361	529	### <a id="clock"></a>Clock
362	530
363	531	Some stock Fossil skins include JavaScript-based features such as the
364	532	current time of day. The Xekri skin includes this in its header, for
365		-example. A clock feature requires JavaScript not only to get the time
366		-and update inline on the page once a minute, but also so it displays *in
367		-the local time zone.*
368		-
369		-Since none of this code provides a necessary Fossil feature, the core
370		-developers are unlikely to try to make these features work better in the
371		-absence of JavaScript.
372		-
373		-However, we are willing to study patches to make this better. For
374		-example, the wall clock displays could include the page load time in the
375		-dynamically generated HTML shipped from the remote Fossil server, so
376		-that in the absence of JavaScript, you at least get the page generation
377		-time, expressed in the server’s time zone.
	533	+example. A clock feature requires JavaScript to get the time on initial
	534	+page load and then to update it once a minute.
	535	+
	536	+You may observe that the server could provide the current time when
	537	+generating the page, but the client and server may not be in the same
	538	+time zone, and there is no reliably-provided information from the client
	539	+that would let the server give the page load time in the client’s local
	540	+time zone. The server could only tell you its local time at page
	541	+request time, not the client’s time. That still wouldn’t be a “clock,”
	542	+since without client-side JavaScript code running, that part of the page
	543	+couldn’t update once a second.
	544	+
	545	+_Potential Graceful Fallback:_ You may consider showing the server’s
	546	+page generation time rather than the client’s wall clock time in the
	547	+local time zone to be a useful fallback for the current feature, so [a
	548	+patch to do this][cg] may well be accepted. Since this is not a
	549	+necessary Fossil feature, an interested user is unlikely to get the
	550	+core developers to do this work for them.
	551	+
	552	+----
	553	+
	554	+## <a id="future"></a>Future Plans for JavaScript in Fossil
	555	+
	556	+As of mid-2020, the informal provisional plan is to increase Fossil
	557	+UI's use of JavaScript considerably compared to its historically minimal
	558	+uses. To that end, a framework of Fossil-centric APIs is being developed
	559	+in conjunction with new features to consolidate Fossil's historical
	560	+hodge-podge of JavaScript snippets into a coherent code base.
	561	+
	562	+When deciding which features to port to JavaScript, the rules of thumb
	563	+for this ongoing effort are:
	564	+
	565	+- Pages which primarily display data (e.g. the timeline) will remain
	566	+ largely static HTML with graceful fallbacks for all places they do
	567	+ use JavaScript. Though JavaScript can be used effectively to power
	568	+ all sorts of wonderful data presentation, Fossil currently doesn't
	569	+ benefit greatly from doing so. We use JavaScript on these pages only
	570	+ to improve their usability, not to define their primary operations.
	571	+
	572	+- Pages which act as editors of some sort (e.g. the `/info` page) are
	573	+ prime candidates for getting the same treatment as the old wiki
	574	+ editor: reimplemented from the ground up in JavaScript using Ajax
	575	+ type techniques. Similarly, a JS-driven overhaul is planned for the
	576	+ forum’s post editor.
	577	+
	578	+These are guidelines, not immutable requirements. Our development
	579	+direction is guided by our priorities:
	580	+
	581	+1) Features the developers themselves want to have and/or work on.
	582	+
	583	+2) Features end users request which catch the interest of one or more
	584	+developers, provided the developer(s) in question are in a position to
	585	+expend the effort.
	586	+
	587	+3) Features end users and co-contributors can convince a developer into
	588	+coding even when they really don't want to. 😉
	589	+
	590	+In all of this, Fossil's project lead understandably has the final
	591	+say-so in whether any given feature indeed gets merged into the mainline
	592	+trunk. Development of any given feature, no matter how much effort was
	593	+involved, does not guarantee its eventual inclusion into the public
	594	+releases.
378	595

	--- www/javascript.md
	+++ www/javascript.md
	@@ -1,28 +1,28 @@
1	# Use of JavaScript in Fossil
2
3	## Philosophy
4
5	The Fossil development project’s policy is to use JavaScript where it
6	helps make its web UI better, but to offer graceful fallbacks wherever
7	practical. The intent is that the UI be usable with JavaScript entirely
8	disabled. In every place where Fossil uses JavaScript, it is an
9	enhancement to provided functionality, and there is always another way
10	to accomplish a given end without using JavaScript.
11
12	This is not to say that Fossil’s fall-backs for such cases are always as
13	elegant and functional as a no-JS purist might wish. That is simply
14	because [the vast majority of web users run with JS enabled](#stats),
15	and a minority of those run with some kind of conditional JavaScript
16	blocking in place. Fossil’s active developers do not deviate from that
17	norm enough that we have many no-JS purists among us, so the no-JS case
18	doesn’t get as much attention as some might want. We do [accept code
19	contributions][cg], and we are philosophically in favor of graceful
20	fall-backs, so you are welcome to appoint yourself the position of no-JS
21	czar for the Fossil project!
22
23	Evil is in actions, not in nouns, so we do not believe JavaScript can
24	be evil. It is an active technology, but the actions that matter here
25	are those of writing the code and checking it into the Fossil project
26	repository. None of the JavaScript code in Fossil is evil, a fact we
27	enforce by being careful about who we give check-in rights on the
28	repository to and by policing what code does get contributed. The Fossil
	@@ -30,98 +30,265 @@
30
31	We think it’s better to ask not whether Fossil requires JavaScript but
32	whether Fossil uses JavaScript well, so that [you can decide](#block)
33	to block or allow Fossil’s use of JavaScript.
34











35	[cg]: ./contribute.wiki
36
37
38	## <a id="block"></a>Blocking JavaScript
39
40	Rather than either block JavaScript wholesale or give up on blocking
41	JavaScript entirely, we recommend that you use tools like [NoScript][ns]
42	or [uBlock Origin][ub] to selectively block problematic uses of
43	JavaScript so the rest of the web can use the technology productively,
44	as it was intended. There are doubtless other useful tools of this sort;
45	we recommend only these two due to our limited experience, not out of
46	any wish to exclude other tools.
47
48	The primary difference between these two for our purposes is that
49	NoScript lets you select scripts to run on a page on a case-by-case
50	basis, whereas uBlock Origin delegates those choices to a group of
51	motivated volunteers who maintain whitelists and blacklists to control
52	all of this; you can then override UBO’s stock rules as needed.
53
54	[ns]: https://noscript.net/
55	[ub]: https://github.com/gorhill/uBlock/
56
57
58	## <a id="stats"></a>How Many Users Run with JavaScript Disabled Anyway?
59
60	There are several studies that have directly measured the web audience
61	to answer this question:
62
63	* [What percentage of browsers with javascript disabled?][s1]
64	* [How many people are missing out on JavaScript enhancement?][s2]
65	* [Just how many web users really disable cookies or JavaScript?][s3]
66
67	Our sense of this data is that only about 0.2% of web users had
68	JavaScript disabled while participating in these studies.
69
70	The Fossil user community is not typical of the wider web, but if we
71	were able to comprehensively survey our users, we’d expect to find an
72	interesting dichotomy. Because Fossil is targeted at software
73	developers, who in turn are more likely to be power-users, we’d expect
74	to find Fossil users to be more in favor of some amount of JavaScript
75	blocking than the average web user. Yet, we’d also expect to find that
76	our user base has a disproportionately high number who run [powerful
77	conditional blocking plugins](#block) in their browsers, rather than
78	block JS entirely. We suspect that between these two forces, the number
79	of no-JS purists among Fossil’s user base is still a tiny minority.
80
81	[s1]: https://blockmetry.com/blog/javascript-disabled
82	[s2]: https://gds.blog.gov.uk/2013/10/21/how-many-people-are-missing-out-on-javascript-enhancement/
83	[s3]: https://w3techs.com/technologies/overview/client_side_language/all
84
85
86	## <a id="3pjs"></a>No Third-Party JavaScript in Fossil
87
88	Fossil does not use any third-party JavaScript libraries, not even very
89	common ones like jQuery. Every bit of JavaScript served by the stock
90	version of Fossil was written specifically for the Fossil project and is
91	stored [in its code repository](https://fossil-scm.org/fossil/file).
92
93	Therefore, if you want to hack on the JavaScript code served by Fossil
94	and mechanisms like [skin editing][cs] don’t suffice for your purposes,
95	you can hack on the JavaScript in your local instance directly, just as
96	you can hack on its C, SQL, and Tcl code. Fossil is free and open source
97	software, under [a single license][2cbsd].
98
99	[2cbsd]: https://fossil-scm.org/home/doc/trunk/COPYRIGHT-BSD2.txt
100	[cs]: ./customskin.md
101
102
103	## <a id="snoop"></a>Fossil Does Not Snoop On You
104
105	There is no tracking or other snooping technology in Fossil other than
106	that necessary for basic security, such as IP address logging on
107	check-ins. (This is in part why we have no [comprehensive user
108	statistics](#stats)!)
109
110	Fossil attempts to set two cookies on all web clients: a login session
111	cookie and a display preferences cookie. These cookies are restricted to
112	the Fossil instance, so even this limited data cannot leak between
113	Fossil instances or into other web sites.
114
115	There is some server-side event logging, but that is done entirely
116	without JavaScript, so it’s off-topic here.
117



























































































































































118
119	## <a id="uses"></a>Places Where Fossil’s Web UI Uses JavaScript
120
121	The remainder of this document will explain how Fossil currently uses
122	JavaScript and what it does when these uses are blocked.

123
124
125	### <a id="timeline"></a>Timeline Graph
126
127	Fossil’s [web timeline][wt] uses JavaScript to render the graph
	@@ -140,22 +307,22 @@
140	command, by clicking around within the web UI, etc.
141
142	_Potential Workaround:_ The timeline could be enhanced with `<noscript>`
143	tags that replace the graph with a column of checkboxes that control
144	what a series of form submit buttons do when clicked, replicating the
145	current JS-based features of the graph using client-server round-trips.
146	For example, you could click two of those checkboxes and then a button
147	labeled “Diff Selected” to replicate the current “click two nodes to
148	diff them” feature.
149
150	[wt]: https://fossil-scm.org/fossil/timeline
151
152
153	### <a id="wedit"></a>The New Wiki Editor
154
155	As of Fossil 2.12, the [Fossil wiki][fwt] document editor requires
156	JavaScript, for a few unavoidable reasons.
157
158	First, it allows in-browser previews without losing client-side editor
159	state, such as where your cursor is. With the old editor, you had to
160	re-locate the place you were last editing on each preview, which would
161	reduce the incentive to use the preview function. In the new wiki
	@@ -174,14 +341,10 @@
174	that there is a way for the app to restore its prior state from
175	persistent media when it’s restarted, giving the illusion that it was
176	never shut down in the first place. This feature of Fossil’s new wiki
177	editor provides that.
178
179	There are many other new features in the enhanced Fossil 2.12 wiki
180	editor, but those are the ones that absolutely require JavaScript to
181	work.
182
183	With this change, we lost the old WYSIWYG wiki editor, available since
184	Fossil version 1.24. It hadn’t been maintained for years, it was
185	disabled by default, and no one stepped up to defend its existence when
186	this new editor was created, replacing it. If someone rescues that
187	feature, merging it in with the new editor, it will doubtless require
	@@ -192,34 +355,36 @@
192
193	_Graceful Fallback:_ Unlike in the Fossil 2.11 and earlier days, there
194	is no longer a script-free wiki editor mode. This is not from lack of
195	desire, only because the person who wrote the new wiki editor didn’t
196	want to maintain three different editors. (New Ajaxy editor, old
197	script-free HTML form based editor, and old WYSIWYG JS-based editor.) If
198	someone wants to implement a `<noscript>` alternative to the new wiki
199	editor, we will likely accept that [contribution][cg] as long as it
200	doensn’t interfere with the new editor. (The same goes for adding a
201	WYSIWYG mode to the new Ajaxy wiki editor.)
202
203	_Workaround:_ You don’t have to use the browser-based wiki editor to
204	maintain your repository’s wiki at all. Fossil’s [`wiki` command][fwc]
205	lets you manipulate wiki documents from the command line. For example,
206	consider this `vi` based workflow:
207
208	```shell
209	$ vi 'My Article.wiki' # write, write, write...
210	:!fossil create 'My Article' '%' # current file (%) to new article


211	...write, write, write some more...
212	:w # save changes to disk copy
213	:!fossil commit 'My Article' '%' # update article from disk
214	:q # done writing for today
215
216	....days later...
217	$ vi # work sans named file today
218	:r !fossil wiki export 'My Article' - # article text into vi buffer
219	...write, write, write yet more...
220	:w !fossil wiki commit - # update article with buffer
221	```
222
223	Extending this concept to other text editors is an exercise left to the
224	reader.
225
	@@ -251,32 +416,35 @@
251	would have no local backup if something crashes, etc. Still, we are
252	likely to accept such a [contribution][cg] as long as it doesn’t
253	interfere with the new editor.
254
255	[edoc]: /doc/trunk/www/embeddeddoc.wiki
256	[fedit]: /help?cmd=/fileedit
257
258
259	### <a id="ln"></a>Line Numbering
260
261	When viewing source files, Fossil offers to show line numbers in some
262	cases. ([Example][mainc].) Toggling them on and off is currently handled
263	in JavaScript, rather than forcing a page-reload via a button click.
264
265	_Workaround:_ Edit the URL to give the “`ln`” query parameter per [the
266	`/file` docs](/help?cmd=/file). Alternately, someone sufficiently
267	interested could [provide a patch][cg] to add a `<noscript>` wrapped
268	HTML button that would reload the page with this parameter
269	included/excluded to implement the toggle via a server round-trip.


270
271	As of Fossil 2.12, there is also a JavaScript-based interactive method
272	for selecting a range of lines by clicking the line numbers when they’re
273	visible, then copying the resulting URL to share your selection with
274	others.
275
276	_Workaround:_ These interactive features absolutely require JavaScript.
277	The alternative is to manually edit the URL, per above.

278
279	[mainc]: https://fossil-scm.org/fossil/artifact?ln&name=87d67e745
280
281
282	### <a id="sxsdiff"></a>Side-by-Side Diff Mode
	@@ -322,12 +490,12 @@
322	similar, hovering over that check-in shows a tooltip with details about
323	the type of artifact the hash refers to and allows you to click to copy
324	the hash to the clipboard.
325
326	_Graceful Fallback:_ When JavaScript is disabled, these tooltips simply
327	don’t appear. You can then select and copy the hash using your browser,
328	make “`fossil info`” queries on those hashes, etc.
329
330
331	### <a id="bots"></a>Anti-Bot Defenses
332
333	Fossil has [anti-bot defenses][abd], and it has some JavaScript code
	@@ -352,26 +520,75 @@
352
353	_Graceful Fallback:_ Clicking the hamburger menu button with JavaScript
354	disabled will take you to the `/sitemap` page instead of showing a
355	simplified version of that page’s content in a drop-down.
356
357	_Workaround:_ You can remove this button by [editing the skin][cs]
358	header.
359
360
361	### <a id="clock"></a>Clock
362
363	Some stock Fossil skins include JavaScript-based features such as the
364	current time of day. The Xekri skin includes this in its header, for
365	example. A clock feature requires JavaScript not only to get the time
366	and update inline on the page once a minute, but also so it displays *in
367	the local time zone.*
368
369	Since none of this code provides a necessary Fossil feature, the core
370	developers are unlikely to try to make these features work better in the
371	absence of JavaScript.
372
373	However, we are willing to study patches to make this better. For
374	example, the wall clock displays could include the page load time in the
375	dynamically generated HTML shipped from the remote Fossil server, so
376	that in the absence of JavaScript, you at least get the page generation
377	time, expressed in the server’s time zone.

















































378

	--- www/javascript.md
	+++ www/javascript.md
	@@ -1,28 +1,28 @@
1	# Use of JavaScript in Fossil
2
3	## Philosophy & Policy
4
5	The Fossil development project’s policy is to use JavaScript where it
6	helps make its web UI better, but to offer graceful fallbacks wherever
7	practical. The intent is that the UI be usable with JavaScript
8	entirely disabled. In almost all places where Fossil uses JavaScript,
9	it is an enhancement to provided functionality, and there is always
10	another way to accomplish a given end without using JavaScript.
11
12	This is not to say that Fossil’s fall-backs for such cases are always as
13	elegant and functional as a no-JS purist might wish. That is simply
14	because [the vast majority of web users run with JavaScript enabled](#stats),
15	and a minority of those run with some kind of [conditional JavaScript
16	blocking](#block) in place. Fossil’s active developers do not deviate from that
17	norm enough that we have many no-JS purists among us, so the no-JS case
18	doesn’t get as much attention as some might want. We do [accept code
19	contributions][cg], and we are philosophically in favor of graceful
20	fall-backs, so you are welcome to appoint yourself the position of no-JS
21	czar for the Fossil project!
22
23	Evil is in actions, not in nouns: we do not believe JavaScript can
24	be evil. It is an active technology, but the actions that matter here
25	are those of writing the code and checking it into the Fossil project
26	repository. None of the JavaScript code in Fossil is evil, a fact we
27	enforce by being careful about who we give check-in rights on the
28	repository to and by policing what code does get contributed. The Fossil
	@@ -30,98 +30,265 @@
30
31	We think it’s better to ask not whether Fossil requires JavaScript but
32	whether Fossil uses JavaScript well, so that [you can decide](#block)
33	to block or allow Fossil’s use of JavaScript.
34
35	The Fossil developers want to see the project thrive, and we achieve
36	that best by making it usable and friendly to a wider audience than the
37	minority of static web app purists. Modern users generally expect a
38	smoother experience than was available with 1990s style HTTP
39	POST-and-response `<form>` based interaction. We also increase the set
40	of potential Fossil developers if we do not restrict them to such
41	antiquated methods.
42
43	JavaScript is not perfect, but it's what we have, so we will use it
44	where we find it advantageous.
45
46	[cg]: ./contribute.wiki
47
48
49	## <a id="debate"></a>Arguments Against JavaScript & Our Rebuttals
50
51	There many common arguments against the use of JavaScript. Rather than
52	rehash these same arguments on the [forum][ffor], we distill the common
53	ones we’ve heard before and give our stock answers to them here:
54
55	1. “It increases the size of the page download.”
56
57	The heaviest such pages served by Fossil only have about 8 kB of
58	compressed JavaScript. (You have to go out of your way to get Fossil
59	to serve uncompressed pages.) This is negligible, even over very
60	slow data connnections. If you are still somehow on a 56 kbit/sec
61	analog telephone modem, this extra script code would download in
62	about a second.
63
64	Most JavaScript-based Fossil pages use less code than that.
65
66	Atop that, Fossil 2.12 adds new script delivery methods with
67	aggressive caching enabled so that typical page loads will skip
68	re-loading this content on subsequent loads. These features are
69	currently optional: you must either set the new [`fossil server
70	--jsmode` option][fsrv] or the corresponding `jsmode` control line
71	in your [`fossil cgi`][fcgi] script when setting up your
72	[Fossil server][fshome]. That done, Fossil’s JavaScript files will
73	load almost instantly from the browser’s cache after the initial
74	page load, rather than be re-transferred over the network.
75
76	Between the improved caching and the fact that it’s quicker to
77	transfer a partial Ajax page load than reload the entire page, the
78	aggregate cost of such pages is typically lower than the older
79	methods based on HTTP POST with a full server round-trip. You can
80	expect to recover the cost of the initial page load in 1-2
81	round-trips. If we were to double the amount of JavaScript code in
82	Fossil, the payoff time would increase to 2-4 round-trips.
83
84	2. “JavaScript is slow.”
85
86	It was, before September 2008. Google's introduction of [their V8
87	JavaScript engine][v8] taught the world that JavaScript need not be
88	slow. This competitive pressure caused the other common JavaScript
89	interpreters to either improve or be replaced by one of the engines
90	that did improve to approach V8’s speed.
91
92	Nowadays JavaScript is, as a rule, astoundingly fast. As the world
93	continues to move more and more to web-based applications and
94	services, JavaScript engine developers have ample motivation to keep
95	their engines fast and competitive.
96
97	Once the scripts are cached, Ajax based page updates are faster than
98	the alternative, a full HTTP POST round-trip.
99
100	3. <a id="3pjs"></a>“Third-party JavaScript cannot be trusted.”
101
102	Fossil does not use any third-party JavaScript libraries, not even
103	very common ones like jQuery. Every bit of JavaScript served by the
104	stock version of Fossil was written specifically for the Fossil
105	project and is stored [in its code repository][fsrc].
106
107	Therefore, if you want to hack on the JavaScript code served by
108	Fossil and mechanisms like [skin editing][cskin] don’t suffice for your
109	purposes, you can hack on the JavaScript in your local instance
110	directly, just as you can hack on its C, SQL, and Tcl code. Fossil
111	is free and open source software, under [a single license][2cbsd].
112
113	4. <a id="snoop"></a>“JavaScript and cookies are used to snoop on web users.”
114
115	There is no tracking or other snooping technology in Fossil other than
116	that necessary for basic security, such as IP address logging on
117	check-ins. (This is in part why we have no [comprehensive user
118	statistics](#stats)!)
119
120	Fossil attempts to set two cookies on all web clients: a login session
121	cookie and a display preferences cookie. These cookies are restricted to
122	the Fossil instance, so even this limited data cannot leak between
123	Fossil instances or into other web sites.
124
125	5. “JavaScript is fundamentally insecure.”
126
127	JavaScript is certainly sometimes used for nefarious ends, but if we
128	wish to have more features in Fossil, the alternative is to add more
129	code to the Fossil binary, [most likely in C][fslpl], a language
130	implicated in [over 4× more security vulnerabilities][whmsl].
131
132	Therefore, does it not make sense to place approximately four times
133	as much trust in Fossil’s JavaScript code as in its C code?
134
135	The question is not whether JavaScript is itself evil, it is whether
136	its authors are evil. Every byte of JavaScript code used within
137	the Fossil UI is:
138
139	* ...written by the Fossil developers, vetted by their peers.
140
141	* ...[open source][flic] and [available][fsrc] to be inspected,
142	audited, and changed by its users.
143
144	* ...compiled directly into the `fossil` binary in a
145	non-obfuscated form during the build process, so there are no
146	third-party servers delivering mysterious, obfuscated JavaScript
147	code blobs to the user.
148
149	Local administrators can [modify the repository’s skin][cskin] to
150	inject additional JavaScript code into pages served by their Fossil
151	server. A typical case is to add a syntax highlighter like
152	[Prism.js][pjs] or [highlightjs][hljs] to the local repository. At
153	that point, your trust concern is not with Fossil’s use of
154	JavaScript, but with your trust in that repository’s administrator.
155
156	Fossil's [default content security policy][dcsp] (CSP)
157	prohibits execution of JavaScript code which is delivered from
158	anywhere but the Fossil server which delivers the page. A local
159	administrator can change this CSP, but again this comes down to a
160	matter of trust with the administrator, not with Fossil itself.
161
162	6. “Cross-browser compatibility is poor.”
163
164	It most certainly was in the first decade or so of JavaScript’s
165	lifetime, resulting in the creation of powerful libraries like
166	jQuery to patch over the incompatibilities. Over time, the need for
167	such libraries has dropped as browser vendors have fixed the
168	incompatibilities. Cross-browser JavaScript compatibility issues
169	which affect web developers are, by and large, a thing of the past.
170
171	7. “Fossil UI works fine today without JavaScript. Why break it?”
172
173	While this is true today, and we have no philosophical objection to
174	it remaining true, we do not intend to limit ourselves to only those
175	features that can be created without JavaScript. The mere
176	availability of alternatives is not a good justification for holding
177	back on notable improvements when they're within easy reach.
178
179	The no-JS case is a [minority position](#stats), so those that want
180	Fossil to have no-JS alternatives and graceful fallbacks will need
181	to get involved with the development if they want this state of
182	affairs to continue.
183
184	8. <a id="stats"></a>“A large number of users run without JavaScript enabled.”
185
186	That’s not what web audience measurements say:
187
188	* [What percentage of browsers with javascript disabled?][s1]
189	* [How many people are missing out on JavaScript enhancement?][s2]
190	* [Just how many web users really disable cookies or JavaScript?][s3]
191
192	Our sense of this data is that only about 0.2% of web users had
193	JavaScript disabled while participating in these studies.
194
195	The Fossil user community is not typical of the wider web, but if we
196	were able to comprehensively survey our users, we’d expect to find
197	an interesting dichotomy. Because Fossil is targeted at software
198	developers, who in turn are more likely to be power-users, we’d
199	expect to find Fossil users to be more in favor of some amount of
200	JavaScript blocking than the average web user. Yet, we’d also expect
201	to find that our user base has a disproportionately high number who
202	run [powerful conditional blocking plugins](#block) in their
203	browsers, rather than block JavaScript entirely. We suspect that
204	between these two forces, the number of no-JS purists among Fossil’s
205	user base is still a tiny minority.
206
207	9. <a id="block"></a>“I block JavaScript entirely in my browser. That breaks Fossil.”
208
209	First, see our philosophy statements above. Briefly, we intend that
210	there always be some other way to get any given result without using
211	JavaScript, developer interest willing.
212
213	But second, it doesn’t have to be all-or-nothing. We recommend that
214	those interested in blocking problematic uses of JavaScript use
215	tools like [NoScript][ns] or [uBlock Origin][ubo] to selectively
216	block JavaScript so the rest of the web can use the technology
217	productively, as it was intended.
218
219	There are doubtless other useful tools of this sort. We recommend
220	these two only from our limited experience, not out of any wish to
221	exclude other tools.
222
223	The primary difference between these two for our purposes is that
224	NoScript lets you select scripts to run on a page on a case-by-case
225	basis, whereas uBlock Origin delegates those choices to a group of
226	motivated volunteers who maintain allow/block lists to control all
227	of this; you can then override UBO’s stock rules as needed.
228
229
230	10. “*My browser doesn’t even have* a JavaScript interpreter.**”
231
232	The Fossil open source project has no full-time developers, and only
233	a few of these part-timers are responsible for the bulk of the code
234	in Fossil. If you want Fossil to support such niche use cases, then
235	you will have to [get involved with its development][cg]: it’s
236	your uncommon itch.
237
238	11. <a id="compat"></a>“Fossil’s JavaScript code isn’t compatible with my browser.”
239
240	The Fossil project’s developers aim to remain compatible with
241	the largest portions of the client-side browser base. We use only
242	standards-defined JavaScript features which are known to work in the
243	overwhelmingly vast majority of browsers going back approximately 5
244	years, at minimum, as documented by [Can I Use...?][ciu] We avoid use of
245	features added to the language more recently or those which are still in
246	flux in standards committees.
247
248	We set this threshold based on the amount of time it typically takes for
249	new standards to propagate through the installed base.
250
251	As of this writing, this means we are only using features defined in
252	[ECMAScript 2015][es2015], colloquially called “JavaScript 6.” That
253	is a sufficiently rich standard that it more than suffices for our
254	purposes, and it is [widely deployed][es6dep]. The biggest single
255	outlier remaining is MSIE 11, and [even Microsoft is moving their
256	own products off of it][ie11x].
257
258	[2cbsd]: https://fossil-scm.org/home/doc/trunk/COPYRIGHT-BSD2.txt
259	[ciu]: https://caniuse.com/
260	[cskin]: ./customskin.md
261	[dcsp]: ./defcsp.md
262	[es2015]: https://ecma-international.org/ecma-262/6.0/
263	[es6dep]: https://caniuse.com/#feat=es6
264	[fcgi]: /help?cmd=cgi
265	[ffor]: https://fossil-scm.org/forum/
266	[flic]: /doc/trunk/COPYRIGHT-BSD2.txt
267	[fshome]: /doc/trunk/www/server/
268	[fslpl]: /doc/trunk/www/fossil-v-git.wiki#portable
269	[fsrc]: https://fossil-scm.org/home/file/src
270	[fsrv]: /help?cmd=server
271	[hljs]: https://fossil-scm.org/forum/forumpost/9150bc22ca
272	[ie11x]: https://techcommunity.microsoft.com/t5/microsoft-365-blog/microsoft-365-apps-say-farewell-to-internet-explorer-11-and/ba-p/1591666
273	[ns]: https://noscript.net/
274	[pjs]: https://fossil-scm.org/forum/forumpost/1198651c6d
275	[s1]: https://blockmetry.com/blog/javascript-disabled
276	[s2]: https://gds.blog.gov.uk/2013/10/21/how-many-people-are-missing-out-on-javascript-enhancement/
277	[s3]: https://w3techs.com/technologies/overview/client_side_language/all
278	[ubo]: https://github.com/gorhill/uBlock/
279	[v8]: https://en.wikipedia.org/wiki/V8_(JavaScript_engine)
280	[whmsl]: https://www.whitesourcesoftware.com/most-secure-programming-languages/
281
282
283	----
284
285	## <a id="uses"></a>Places Where Fossil’s Web UI Uses JavaScript
286
287	This section documents the areas where Fossil currently uses JavaScript
288	and what it does when these uses are blocked. It also gives common
289	workarounds where necessary.
290
291
292	### <a id="timeline"></a>Timeline Graph
293
294	Fossil’s [web timeline][wt] uses JavaScript to render the graph
	@@ -140,22 +307,22 @@
307	command, by clicking around within the web UI, etc.
308
309	_Potential Workaround:_ The timeline could be enhanced with `<noscript>`
310	tags that replace the graph with a column of checkboxes that control
311	what a series of form submit buttons do when clicked, replicating the
312	current JavaScript-based features of the graph using client-server round-trips.
313	For example, you could click two of those checkboxes and then a button
314	labeled “Diff Selected” to replicate the current “click two nodes to
315	diff them” feature.
316
317	[wt]: https://fossil-scm.org/fossil/timeline
318
319
320	### <a id="wedit"></a>The New Wiki Editor
321
322	The [new wiki editor][fwt] added in Fossil 2.12 has many new features, a
323	few of which are impossible to get without use of JavaScript.
324
325	First, it allows in-browser previews without losing client-side editor
326	state, such as where your cursor is. With the old editor, you had to
327	re-locate the place you were last editing on each preview, which would
328	reduce the incentive to use the preview function. In the new wiki
	@@ -174,14 +341,10 @@
341	that there is a way for the app to restore its prior state from
342	persistent media when it’s restarted, giving the illusion that it was
343	never shut down in the first place. This feature of Fossil’s new wiki
344	editor provides that.
345




346	With this change, we lost the old WYSIWYG wiki editor, available since
347	Fossil version 1.24. It hadn’t been maintained for years, it was
348	disabled by default, and no one stepped up to defend its existence when
349	this new editor was created, replacing it. If someone rescues that
350	feature, merging it in with the new editor, it will doubtless require
	@@ -192,34 +355,36 @@
355
356	_Graceful Fallback:_ Unlike in the Fossil 2.11 and earlier days, there
357	is no longer a script-free wiki editor mode. This is not from lack of
358	desire, only because the person who wrote the new wiki editor didn’t
359	want to maintain three different editors. (New Ajaxy editor, old
360	script-free HTML form based editor, and the old WYSIWYG JavaScript-based
361	editor.) If someone wants to implement a `<noscript>` alternative to the
362	new wiki editor, we will likely accept that [contribution][cg] as long
363	as it doesn’t interfere with the new editor. (The same goes for adding
364	a WYSIWYG mode to the new Ajaxy wiki editor.)
365
366	_Workaround:_ You don’t have to use the browser-based wiki editor to
367	maintain your repository’s wiki at all. Fossil’s [`wiki` command][fwc]
368	lets you manipulate wiki documents from the command line. For example,
369	consider this Vi based workflow:
370
371	```shell
372	$ vi 'My Article.wiki' # begin work on new article
373	...write, write, write...
374	:w # save changes to disk copy
375	:!fossil wiki create 'My Article' '%' # current file (%) to new article
376	...write, write, write some more...
377	:w # save again
378	:!fossil wiki commit 'My Article' '%' # update article from disk
379	:q # done writing for today
380
381	....days later...
382	$ vi # work sans named file today
383	:r !fossil wiki export 'My Article' - # pull article text into vi buffer
384	...write, write, write yet more...
385	:w !fossil wiki commit - # vi buffer updates article
386	```
387
388	Extending this concept to other text editors is an exercise left to the
389	reader.
390
	@@ -251,32 +416,35 @@
416	would have no local backup if something crashes, etc. Still, we are
417	likely to accept such a [contribution][cg] as long as it doesn’t
418	interfere with the new editor.
419
420	[edoc]: /doc/trunk/www/embeddeddoc.wiki
421	[fedit]: /doc/trunk/www/fileedit-page.md
422
423
424	### <a id="ln"></a>Line Numbering
425
426	When viewing source files, Fossil offers to show line numbers in some
427	cases. ([Example][mainc].) Toggling them on and off is currently handled
428	in JavaScript, rather than forcing a page-reload via a button click.
429
430	_Workaround:_ Manually edit the URL to give the “`ln`” query parameter
431	per [the `/file` docs](/help?cmd=/file).
432
433	_Potential Better Workaround:_ Someone sufficiently interested could
434	[provide a patch][cg] to add a `<noscript>` wrapped HTML button that
435	would reload the page with this parameter included/excluded to implement
436	the toggle via a server round-trip.
437
438	As of Fossil 2.12, there is also a JavaScript-based interactive method
439	for selecting a range of lines by clicking the line numbers when they’re
440	visible, then copying the resulting URL to share your selection with
441	others.
442
443	_Workaround:_ These interactive features would be difficult and
444	expensive (in terms of network I/O) to implement without JavaScript. A
445	far simpler alternative is to manually edit the URL, per above.
446
447	[mainc]: https://fossil-scm.org/fossil/artifact?ln&name=87d67e745
448
449
450	### <a id="sxsdiff"></a>Side-by-Side Diff Mode
	@@ -322,12 +490,12 @@
490	similar, hovering over that check-in shows a tooltip with details about
491	the type of artifact the hash refers to and allows you to click to copy
492	the hash to the clipboard.
493
494	_Graceful Fallback:_ When JavaScript is disabled, these tooltips simply
495	don’t appear, but you can still select and copy the hash using your
496	platform’s “copy selected text” feature.
497
498
499	### <a id="bots"></a>Anti-Bot Defenses
500
501	Fossil has [anti-bot defenses][abd], and it has some JavaScript code
	@@ -352,26 +520,75 @@
520
521	_Graceful Fallback:_ Clicking the hamburger menu button with JavaScript
522	disabled will take you to the `/sitemap` page instead of showing a
523	simplified version of that page’s content in a drop-down.
524
525	_Workaround:_ You can remove this button by [editing the skin][cskin]
526	header.
527
528
529	### <a id="clock"></a>Clock
530
531	Some stock Fossil skins include JavaScript-based features such as the
532	current time of day. The Xekri skin includes this in its header, for
533	example. A clock feature requires JavaScript to get the time on initial
534	page load and then to update it once a minute.
535
536	You may observe that the server could provide the current time when
537	generating the page, but the client and server may not be in the same
538	time zone, and there is no reliably-provided information from the client
539	that would let the server give the page load time in the client’s local
540	time zone. The server could only tell you its local time at page
541	request time, not the client’s time. That still wouldn’t be a “clock,”
542	since without client-side JavaScript code running, that part of the page
543	couldn’t update once a second.
544
545	_Potential Graceful Fallback:_ You may consider showing the server’s
546	page generation time rather than the client’s wall clock time in the
547	local time zone to be a useful fallback for the current feature, so [a
548	patch to do this][cg] may well be accepted. Since this is not a
549	necessary Fossil feature, an interested user is unlikely to get the
550	core developers to do this work for them.
551
552	----
553
554	## <a id="future"></a>Future Plans for JavaScript in Fossil
555
556	As of mid-2020, the informal provisional plan is to increase Fossil
557	UI's use of JavaScript considerably compared to its historically minimal
558	uses. To that end, a framework of Fossil-centric APIs is being developed
559	in conjunction with new features to consolidate Fossil's historical
560	hodge-podge of JavaScript snippets into a coherent code base.
561
562	When deciding which features to port to JavaScript, the rules of thumb
563	for this ongoing effort are:
564
565	- Pages which primarily display data (e.g. the timeline) will remain
566	largely static HTML with graceful fallbacks for all places they do
567	use JavaScript. Though JavaScript can be used effectively to power
568	all sorts of wonderful data presentation, Fossil currently doesn't
569	benefit greatly from doing so. We use JavaScript on these pages only
570	to improve their usability, not to define their primary operations.
571
572	- Pages which act as editors of some sort (e.g. the `/info` page) are
573	prime candidates for getting the same treatment as the old wiki
574	editor: reimplemented from the ground up in JavaScript using Ajax
575	type techniques. Similarly, a JS-driven overhaul is planned for the
576	forum’s post editor.
577
578	These are guidelines, not immutable requirements. Our development
579	direction is guided by our priorities:
580
581	1) Features the developers themselves want to have and/or work on.
582
583	2) Features end users request which catch the interest of one or more
584	developers, provided the developer(s) in question are in a position to
585	expend the effort.
586
587	3) Features end users and co-contributors can convince a developer into
588	coding even when they really don't want to. 😉
589
590	In all of this, Fossil's project lead understandably has the final
591	say-so in whether any given feature indeed gets merged into the mainline
592	trunk. Development of any given feature, no matter how much effort was
593	involved, does not guarantee its eventual inclusion into the public
594	releases.
595

Fossil SCM

Keyboard Shortcuts