Fossil SCM
Editing pass on javascript.md.
Commit
202a6616124002f7f454d43d150973e4555f115c9b93c1e97f6f59d428649c8c
Parent
85c7bdb285c46d4…
1 file changed
+24
-24
+24
-24
| --- www/javascript.md | ||
| +++ www/javascript.md | ||
| @@ -10,21 +10,18 @@ | ||
| 10 | 10 | 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 | 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 in place. Fossil’s active developers do not deviate from that | |
| 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 | -We cover some of the common arguments against JavaScript | |
| 24 | -[below](#debate), with our rebuttals to them. | |
| 25 | - | |
| 26 | 23 | Evil is in actions, not in nouns: we do not believe JavaScript *can* |
| 27 | 24 | be evil. It is an active technology, but the actions that matter here |
| 28 | 25 | are those of writing the code and checking it into the Fossil project |
| 29 | 26 | repository. None of the JavaScript code in Fossil is evil, a fact we |
| 30 | 27 | enforce by being careful about who we give check-in rights on the |
| @@ -62,11 +59,11 @@ | ||
| 62 | 59 | to serve uncompressed pages.) This is negligible, even over very |
| 63 | 60 | slow data connnections. If you are still somehow on a 56 kbit/sec |
| 64 | 61 | analog telephone modem, this extra script code would download in |
| 65 | 62 | about a second. |
| 66 | 63 | |
| 67 | - Most JavaScript-based Fossil pages use less JavaScript than that. | |
| 64 | + Most JavaScript-based Fossil pages use less code than that. | |
| 68 | 65 | |
| 69 | 66 | Atop that, Fossil 2.12 adds new script delivery methods with |
| 70 | 67 | aggressive caching enabled so that typical page loads will skip |
| 71 | 68 | re-loading this content on subsequent loads. These features are |
| 72 | 69 | currently optional: you must either set the new [`fossil server |
| @@ -79,12 +76,12 @@ | ||
| 79 | 76 | Between the improved caching and the fact that it’s quicker to |
| 80 | 77 | transfer a partial Ajax page load than reload the entire page, the |
| 81 | 78 | aggregate cost of such pages is typically *lower* than the older |
| 82 | 79 | methods based on HTTP POST with a full server round-trip. You can |
| 83 | 80 | expect to recover the cost of the initial page load in 1-2 |
| 84 | - round-trips. If we were to double the amount of JavaScript code, the | |
| 85 | - payoff time would increase to 2-4 round-trips. | |
| 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. | |
| 86 | 83 | |
| 87 | 84 | 2. “**JavaScript is slow.**” |
| 88 | 85 | |
| 89 | 86 | It *was*, before September 2008. Google's introduction of [their V8 |
| 90 | 87 | JavaScript engine][v8] taught the world that JavaScript need not be |
| @@ -96,11 +93,11 @@ | ||
| 96 | 93 | continues to move more and more to web-based applications and |
| 97 | 94 | services, JavaScript engine developers have ample motivation to keep |
| 98 | 95 | their engines fast and competitive. |
| 99 | 96 | |
| 100 | 97 | Once the scripts are cached, Ajax based page updates are faster than |
| 101 | - the alternative. | |
| 98 | + the alternative, a full HTTP POST round-trip. | |
| 102 | 99 | |
| 103 | 100 | 3. <a id="3pjs"></a>“**Third-party JavaScript cannot be trusted.**” |
| 104 | 101 | |
| 105 | 102 | Fossil does not use any third-party JavaScript libraries, not even |
| 106 | 103 | very common ones like jQuery. Every bit of JavaScript served by the |
| @@ -111,11 +108,11 @@ | ||
| 111 | 108 | Fossil and mechanisms like [skin editing][cskin] don’t suffice for your |
| 112 | 109 | purposes, you can hack on the JavaScript in your local instance |
| 113 | 110 | directly, just as you can hack on its C, SQL, and Tcl code. Fossil |
| 114 | 111 | is free and open source software, under [a single license][2cbsd]. |
| 115 | 112 | |
| 116 | -4. <a id="snoop"></a>“**JavaScript and cookiers are used to snoop on web users.**” | |
| 113 | +4. <a id="snoop"></a>“**JavaScript and cookies are used to snoop on web users.**” | |
| 117 | 114 | |
| 118 | 115 | There is no tracking or other snooping technology in Fossil other than |
| 119 | 116 | that necessary for basic security, such as IP address logging on |
| 120 | 117 | check-ins. (This is in part why we have no [comprehensive user |
| 121 | 118 | statistics](#stats)!) |
| @@ -148,11 +145,11 @@ | ||
| 148 | 145 | audited, and changed by its users. |
| 149 | 146 | |
| 150 | 147 | * ...compiled directly into the `fossil` binary in a |
| 151 | 148 | non-obfuscated form during the build process, so there are no |
| 152 | 149 | third-party servers delivering mysterious, obfuscated JavaScript |
| 153 | - code to the user. | |
| 150 | + code blobs to the user. | |
| 154 | 151 | |
| 155 | 152 | Local administrators can [modify the repository’s skin][cskin] to |
| 156 | 153 | inject additional JavaScript code into pages served by their Fossil |
| 157 | 154 | server. A typical case is to add a syntax highlighter like |
| 158 | 155 | [Prism.js][pjs] or [highlightjs][hljs] to the local repository. At |
| @@ -241,11 +238,11 @@ | ||
| 241 | 238 | you will have to [get involved with its development][cg]; it’s |
| 242 | 239 | *your* uncommon itch. |
| 243 | 240 | |
| 244 | 241 | 11. <a id="compat"></a>“**Fossil’s JavaScript code isn’t compatible with my browser.**” |
| 245 | 242 | |
| 246 | - The Fossil project’s developers aim to remain relatively compatible with | |
| 243 | + The Fossil project’s developers aim to remain compatible with | |
| 247 | 244 | the largest portions of the client-side browser base. We use only |
| 248 | 245 | standards-defined JavaScript features which are known to work in the |
| 249 | 246 | overwhelmingly vast majority of browsers going back approximately 5 |
| 250 | 247 | years, at minimum, as documented by [Can I Use...?][ciu] We avoid use of |
| 251 | 248 | features added to the language more recently or those which are still in |
| @@ -281,12 +278,13 @@ | ||
| 281 | 278 | |
| 282 | 279 | ---- |
| 283 | 280 | |
| 284 | 281 | ## <a id="uses"></a>Places Where Fossil’s Web UI Uses JavaScript |
| 285 | 282 | |
| 286 | -The remainder of this document will explain how Fossil currently uses | |
| 287 | -JavaScript and what it does when these uses are blocked. | |
| 283 | +This section documents the areas where Fossil currently uses JavaScript | |
| 284 | +and what it does when these uses are blocked. It also gives common | |
| 285 | +workarounds where necessary. | |
| 288 | 286 | |
| 289 | 287 | |
| 290 | 288 | ### <a id="timeline"></a>Timeline Graph |
| 291 | 289 | |
| 292 | 290 | Fossil’s [web timeline][wt] uses JavaScript to render the graph |
| @@ -316,11 +314,11 @@ | ||
| 316 | 314 | |
| 317 | 315 | |
| 318 | 316 | ### <a id="wedit"></a>The New Wiki Editor |
| 319 | 317 | |
| 320 | 318 | As of Fossil 2.12, the [Fossil wiki][fwt] document editor requires |
| 321 | -JavaScript, for a few unavoidable reasons. | |
| 319 | +JavaScript for a few unavoidable reasons. | |
| 322 | 320 | |
| 323 | 321 | First, it allows in-browser previews without losing client-side editor |
| 324 | 322 | state, such as where your cursor is. With the old editor, you had to |
| 325 | 323 | re-locate the place you were last editing on each preview, which would |
| 326 | 324 | reduce the incentive to use the preview function. In the new wiki |
| @@ -357,34 +355,36 @@ | ||
| 357 | 355 | |
| 358 | 356 | _Graceful Fallback:_ Unlike in the Fossil 2.11 and earlier days, there |
| 359 | 357 | is no longer a script-free wiki editor mode. This is not from lack of |
| 360 | 358 | desire, only because the person who wrote the new wiki editor didn’t |
| 361 | 359 | want to maintain three different editors. (New Ajaxy editor, old |
| 362 | -script-free HTML form based editor, and old WYSIWYG JavaScript-based editor.) If | |
| 363 | -someone wants to implement a `<noscript>` alternative to the new wiki | |
| 364 | -editor, we will likely accept that [contribution][cg] as long as it | |
| 365 | -doensn’t interfere with the new editor. (The same goes for adding a | |
| 366 | -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 doensn’t interfere with the new editor. (The same goes for adding | |
| 364 | +a WYSIWYG mode to the new Ajaxy wiki editor.) | |
| 367 | 365 | |
| 368 | 366 | _Workaround:_ You don’t have to use the browser-based wiki editor to |
| 369 | 367 | maintain your repository’s wiki at all. Fossil’s [`wiki` command][fwc] |
| 370 | 368 | lets you manipulate wiki documents from the command line. For example, |
| 371 | 369 | consider this `vi` based workflow: |
| 372 | 370 | |
| 373 | 371 | ```shell |
| 374 | - $ vi 'My Article.wiki' # write, write, write... | |
| 372 | + $ vi 'My Article.wiki' # begin work on new article | |
| 373 | + ...write, write, write... | |
| 374 | + :w # save changes to disk copy | |
| 375 | 375 | :!fossil create 'My Article' '%' # current file (%) to new article |
| 376 | 376 | ...write, write, write some more... |
| 377 | - :w # save changes to disk copy | |
| 377 | + :w # save again | |
| 378 | 378 | :!fossil commit 'My Article' '%' # update article from disk |
| 379 | 379 | :q # done writing for today |
| 380 | 380 | |
| 381 | 381 | ....days later... |
| 382 | 382 | $ vi # work sans named file today |
| 383 | - :r !fossil wiki export 'My Article' - # article text into vi buffer | |
| 383 | + :r !fossil wiki export 'My Article' - # pull article text into vi buffer | |
| 384 | 384 | ...write, write, write yet more... |
| 385 | - :w !fossil wiki commit - # update article with buffer | |
| 385 | + :w !fossil wiki commit - # vi buffer updates article | |
| 386 | 386 | ``` |
| 387 | 387 | |
| 388 | 388 | Extending this concept to other text editors is an exercise left to the |
| 389 | 389 | reader. |
| 390 | 390 | |
| 391 | 391 |
| --- www/javascript.md | |
| +++ www/javascript.md | |
| @@ -10,21 +10,18 @@ | |
| 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 JavaScript 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 | We cover some of the common arguments against JavaScript |
| 24 | [below](#debate), with our rebuttals to them. |
| 25 | |
| 26 | Evil is in actions, not in nouns: we do not believe JavaScript *can* |
| 27 | be evil. It is an active technology, but the actions that matter here |
| 28 | are those of writing the code and checking it into the Fossil project |
| 29 | repository. None of the JavaScript code in Fossil is evil, a fact we |
| 30 | enforce by being careful about who we give check-in rights on the |
| @@ -62,11 +59,11 @@ | |
| 62 | to serve uncompressed pages.) This is negligible, even over very |
| 63 | slow data connnections. If you are still somehow on a 56 kbit/sec |
| 64 | analog telephone modem, this extra script code would download in |
| 65 | about a second. |
| 66 | |
| 67 | Most JavaScript-based Fossil pages use less JavaScript than that. |
| 68 | |
| 69 | Atop that, Fossil 2.12 adds new script delivery methods with |
| 70 | aggressive caching enabled so that typical page loads will skip |
| 71 | re-loading this content on subsequent loads. These features are |
| 72 | currently optional: you must either set the new [`fossil server |
| @@ -79,12 +76,12 @@ | |
| 79 | Between the improved caching and the fact that it’s quicker to |
| 80 | transfer a partial Ajax page load than reload the entire page, the |
| 81 | aggregate cost of such pages is typically *lower* than the older |
| 82 | methods based on HTTP POST with a full server round-trip. You can |
| 83 | expect to recover the cost of the initial page load in 1-2 |
| 84 | round-trips. If we were to double the amount of JavaScript code, the |
| 85 | payoff time would increase to 2-4 round-trips. |
| 86 | |
| 87 | 2. “**JavaScript is slow.**” |
| 88 | |
| 89 | It *was*, before September 2008. Google's introduction of [their V8 |
| 90 | JavaScript engine][v8] taught the world that JavaScript need not be |
| @@ -96,11 +93,11 @@ | |
| 96 | continues to move more and more to web-based applications and |
| 97 | services, JavaScript engine developers have ample motivation to keep |
| 98 | their engines fast and competitive. |
| 99 | |
| 100 | Once the scripts are cached, Ajax based page updates are faster than |
| 101 | the alternative. |
| 102 | |
| 103 | 3. <a id="3pjs"></a>“**Third-party JavaScript cannot be trusted.**” |
| 104 | |
| 105 | Fossil does not use any third-party JavaScript libraries, not even |
| 106 | very common ones like jQuery. Every bit of JavaScript served by the |
| @@ -111,11 +108,11 @@ | |
| 111 | Fossil and mechanisms like [skin editing][cskin] don’t suffice for your |
| 112 | purposes, you can hack on the JavaScript in your local instance |
| 113 | directly, just as you can hack on its C, SQL, and Tcl code. Fossil |
| 114 | is free and open source software, under [a single license][2cbsd]. |
| 115 | |
| 116 | 4. <a id="snoop"></a>“**JavaScript and cookiers are used to snoop on web users.**” |
| 117 | |
| 118 | There is no tracking or other snooping technology in Fossil other than |
| 119 | that necessary for basic security, such as IP address logging on |
| 120 | check-ins. (This is in part why we have no [comprehensive user |
| 121 | statistics](#stats)!) |
| @@ -148,11 +145,11 @@ | |
| 148 | audited, and changed by its users. |
| 149 | |
| 150 | * ...compiled directly into the `fossil` binary in a |
| 151 | non-obfuscated form during the build process, so there are no |
| 152 | third-party servers delivering mysterious, obfuscated JavaScript |
| 153 | code to the user. |
| 154 | |
| 155 | Local administrators can [modify the repository’s skin][cskin] to |
| 156 | inject additional JavaScript code into pages served by their Fossil |
| 157 | server. A typical case is to add a syntax highlighter like |
| 158 | [Prism.js][pjs] or [highlightjs][hljs] to the local repository. At |
| @@ -241,11 +238,11 @@ | |
| 241 | you will have to [get involved with its development][cg]; it’s |
| 242 | *your* uncommon itch. |
| 243 | |
| 244 | 11. <a id="compat"></a>“**Fossil’s JavaScript code isn’t compatible with my browser.**” |
| 245 | |
| 246 | The Fossil project’s developers aim to remain relatively compatible with |
| 247 | the largest portions of the client-side browser base. We use only |
| 248 | standards-defined JavaScript features which are known to work in the |
| 249 | overwhelmingly vast majority of browsers going back approximately 5 |
| 250 | years, at minimum, as documented by [Can I Use...?][ciu] We avoid use of |
| 251 | features added to the language more recently or those which are still in |
| @@ -281,12 +278,13 @@ | |
| 281 | |
| 282 | ---- |
| 283 | |
| 284 | ## <a id="uses"></a>Places Where Fossil’s Web UI Uses JavaScript |
| 285 | |
| 286 | The remainder of this document will explain how Fossil currently uses |
| 287 | JavaScript and what it does when these uses are blocked. |
| 288 | |
| 289 | |
| 290 | ### <a id="timeline"></a>Timeline Graph |
| 291 | |
| 292 | Fossil’s [web timeline][wt] uses JavaScript to render the graph |
| @@ -316,11 +314,11 @@ | |
| 316 | |
| 317 | |
| 318 | ### <a id="wedit"></a>The New Wiki Editor |
| 319 | |
| 320 | As of Fossil 2.12, the [Fossil wiki][fwt] document editor requires |
| 321 | JavaScript, for a few unavoidable reasons. |
| 322 | |
| 323 | First, it allows in-browser previews without losing client-side editor |
| 324 | state, such as where your cursor is. With the old editor, you had to |
| 325 | re-locate the place you were last editing on each preview, which would |
| 326 | reduce the incentive to use the preview function. In the new wiki |
| @@ -357,34 +355,36 @@ | |
| 357 | |
| 358 | _Graceful Fallback:_ Unlike in the Fossil 2.11 and earlier days, there |
| 359 | is no longer a script-free wiki editor mode. This is not from lack of |
| 360 | desire, only because the person who wrote the new wiki editor didn’t |
| 361 | want to maintain three different editors. (New Ajaxy editor, old |
| 362 | script-free HTML form based editor, and old WYSIWYG JavaScript-based editor.) If |
| 363 | someone wants to implement a `<noscript>` alternative to the new wiki |
| 364 | editor, we will likely accept that [contribution][cg] as long as it |
| 365 | doensn’t interfere with the new editor. (The same goes for adding a |
| 366 | WYSIWYG mode to the new Ajaxy wiki editor.) |
| 367 | |
| 368 | _Workaround:_ You don’t have to use the browser-based wiki editor to |
| 369 | maintain your repository’s wiki at all. Fossil’s [`wiki` command][fwc] |
| 370 | lets you manipulate wiki documents from the command line. For example, |
| 371 | consider this `vi` based workflow: |
| 372 | |
| 373 | ```shell |
| 374 | $ vi 'My Article.wiki' # write, write, write... |
| 375 | :!fossil create 'My Article' '%' # current file (%) to new article |
| 376 | ...write, write, write some more... |
| 377 | :w # save changes to disk copy |
| 378 | :!fossil 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' - # article text into vi buffer |
| 384 | ...write, write, write yet more... |
| 385 | :w !fossil wiki commit - # update article with buffer |
| 386 | ``` |
| 387 | |
| 388 | Extending this concept to other text editors is an exercise left to the |
| 389 | reader. |
| 390 | |
| 391 |
| --- www/javascript.md | |
| +++ www/javascript.md | |
| @@ -10,21 +10,18 @@ | |
| 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 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 |
| @@ -62,11 +59,11 @@ | |
| 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 |
| @@ -79,12 +76,12 @@ | |
| 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 |
| @@ -96,11 +93,11 @@ | |
| 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 |
| @@ -111,11 +108,11 @@ | |
| 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)!) |
| @@ -148,11 +145,11 @@ | |
| 145 | audited, and changed by its users. |
| 146 | |
| 147 | * ...compiled directly into the `fossil` binary in a |
| 148 | non-obfuscated form during the build process, so there are no |
| 149 | third-party servers delivering mysterious, obfuscated JavaScript |
| 150 | code blobs to the user. |
| 151 | |
| 152 | Local administrators can [modify the repository’s skin][cskin] to |
| 153 | inject additional JavaScript code into pages served by their Fossil |
| 154 | server. A typical case is to add a syntax highlighter like |
| 155 | [Prism.js][pjs] or [highlightjs][hljs] to the local repository. At |
| @@ -241,11 +238,11 @@ | |
| 238 | you will have to [get involved with its development][cg]; it’s |
| 239 | *your* uncommon itch. |
| 240 | |
| 241 | 11. <a id="compat"></a>“**Fossil’s JavaScript code isn’t compatible with my browser.**” |
| 242 | |
| 243 | The Fossil project’s developers aim to remain compatible with |
| 244 | the largest portions of the client-side browser base. We use only |
| 245 | standards-defined JavaScript features which are known to work in the |
| 246 | overwhelmingly vast majority of browsers going back approximately 5 |
| 247 | years, at minimum, as documented by [Can I Use...?][ciu] We avoid use of |
| 248 | features added to the language more recently or those which are still in |
| @@ -281,12 +278,13 @@ | |
| 278 | |
| 279 | ---- |
| 280 | |
| 281 | ## <a id="uses"></a>Places Where Fossil’s Web UI Uses JavaScript |
| 282 | |
| 283 | This section documents the areas where Fossil currently uses JavaScript |
| 284 | and what it does when these uses are blocked. It also gives common |
| 285 | workarounds where necessary. |
| 286 | |
| 287 | |
| 288 | ### <a id="timeline"></a>Timeline Graph |
| 289 | |
| 290 | Fossil’s [web timeline][wt] uses JavaScript to render the graph |
| @@ -316,11 +314,11 @@ | |
| 314 | |
| 315 | |
| 316 | ### <a id="wedit"></a>The New Wiki Editor |
| 317 | |
| 318 | As of Fossil 2.12, the [Fossil wiki][fwt] document editor requires |
| 319 | JavaScript for a few unavoidable reasons. |
| 320 | |
| 321 | First, it allows in-browser previews without losing client-side editor |
| 322 | state, such as where your cursor is. With the old editor, you had to |
| 323 | re-locate the place you were last editing on each preview, which would |
| 324 | reduce the incentive to use the preview function. In the new wiki |
| @@ -357,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 doensn’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 create 'My Article' '%' # current file (%) to new article |
| 376 | ...write, write, write some more... |
| 377 | :w # save again |
| 378 | :!fossil 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 | |
| 391 |