Fossil SCM
Updated the "Wiki Editor" section of javascript.md to cover the new `/wikiedit` implementation.
Commit
31c40509d4a41a77d214701dabcfd3907cd3196fa48ea1a160e31ada232d35c4
Parent
38fa17e47972b17…
1 file changed
+75
-15
+75
-15
| --- www/javascript.md | ||
| +++ www/javascript.md | ||
| @@ -148,25 +148,85 @@ | ||
| 148 | 148 | diff them” feature. |
| 149 | 149 | |
| 150 | 150 | [wt]: https://fossil-scm.org/fossil/timeline |
| 151 | 151 | |
| 152 | 152 | |
| 153 | -### <a id="wedit"></a>WYSIWYG Wiki Editor | |
| 154 | - | |
| 155 | -The Admin → Wiki → “Enable WYSIWYG Wiki Editing” toggle switches the | |
| 156 | -default plaintext editor for [Fossil wiki][fw] documents to one that | |
| 157 | -works like a basic word processor. This feature requires JavaScript in | |
| 158 | -order to react to editor button clicks like the “**B**” button, meaning | |
| 159 | -“make \[selected\] text boldface.” There is no standard WYSIWYG editor | |
| 160 | -component in browsers, doubtless because it’s relatively straightforward | |
| 161 | -to create one using JavaScript. | |
| 162 | - | |
| 163 | -_Graceful Fallback:_ Edit your wiki documents in the default plain text | |
| 164 | -wiki editor. Fossil’s wiki and Markdown language processors were | |
| 165 | -designed to be edited that way. | |
| 166 | - | |
| 167 | -[fw]: ./wikitheory.wiki | |
| 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 | |
| 162 | +editor, you just click the Preview tab to see how Fossil interprets your | |
| 163 | +markup, then click back to the Editor tab to resume work with the prior | |
| 164 | +context undisturbed. | |
| 165 | + | |
| 166 | +Second, it continually saves your document state in client-side storage | |
| 167 | +in the background while you’re editing it so that if the browser closes | |
| 168 | +without saving the changes back to the Fossil repository, you can resume | |
| 169 | +editing from the stored copy without losing work. This feature is not so | |
| 170 | +much about saving you from crashes of various sorts, since computers are | |
| 171 | +so much more reliable these days. It is far more likely to save you from | |
| 172 | +the features of mobile OSes like Android and iOS which aggressively shut | |
| 173 | +down and restart apps to save on RAM. That OS design philosophy assumes | |
| 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 | |
| 188 | +JavaScript in order to react to editor button clicks like the “**B**” | |
| 189 | +button, meaning “make \[selected\] text boldface.” There is no standard | |
| 190 | +WYSIWYG editor component in browsers, doubtless because it’s relatively | |
| 191 | +straightforward to create one using JavaScript. | |
| 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 | + | |
| 226 | +[fwc]: /help?cmd=wiki | |
| 227 | +[fwt]: ./wikitheory.wiki | |
| 168 | 228 | |
| 169 | 229 | |
| 170 | 230 | ### <a id="ln"></a>Line Numbering |
| 171 | 231 | |
| 172 | 232 | When viewing source files, Fossil offers to show line numbers in some |
| 173 | 233 |
| --- www/javascript.md | |
| +++ www/javascript.md | |
| @@ -148,25 +148,85 @@ | |
| 148 | diff them” feature. |
| 149 | |
| 150 | [wt]: https://fossil-scm.org/fossil/timeline |
| 151 | |
| 152 | |
| 153 | ### <a id="wedit"></a>WYSIWYG Wiki Editor |
| 154 | |
| 155 | The Admin → Wiki → “Enable WYSIWYG Wiki Editing” toggle switches the |
| 156 | default plaintext editor for [Fossil wiki][fw] documents to one that |
| 157 | works like a basic word processor. This feature requires JavaScript in |
| 158 | order to react to editor button clicks like the “**B**” button, meaning |
| 159 | “make \[selected\] text boldface.” There is no standard WYSIWYG editor |
| 160 | component in browsers, doubtless because it’s relatively straightforward |
| 161 | to create one using JavaScript. |
| 162 | |
| 163 | _Graceful Fallback:_ Edit your wiki documents in the default plain text |
| 164 | wiki editor. Fossil’s wiki and Markdown language processors were |
| 165 | designed to be edited that way. |
| 166 | |
| 167 | [fw]: ./wikitheory.wiki |
| 168 | |
| 169 | |
| 170 | ### <a id="ln"></a>Line Numbering |
| 171 | |
| 172 | When viewing source files, Fossil offers to show line numbers in some |
| 173 |
| --- www/javascript.md | |
| +++ www/javascript.md | |
| @@ -148,25 +148,85 @@ | |
| 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 |
| 162 | editor, you just click the Preview tab to see how Fossil interprets your |
| 163 | markup, then click back to the Editor tab to resume work with the prior |
| 164 | context undisturbed. |
| 165 | |
| 166 | Second, it continually saves your document state in client-side storage |
| 167 | in the background while you’re editing it so that if the browser closes |
| 168 | without saving the changes back to the Fossil repository, you can resume |
| 169 | editing from the stored copy without losing work. This feature is not so |
| 170 | much about saving you from crashes of various sorts, since computers are |
| 171 | so much more reliable these days. It is far more likely to save you from |
| 172 | the features of mobile OSes like Android and iOS which aggressively shut |
| 173 | down and restart apps to save on RAM. That OS design philosophy assumes |
| 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 |
| 188 | JavaScript in order to react to editor button clicks like the “**B**” |
| 189 | button, meaning “make \[selected\] text boldface.” There is no standard |
| 190 | WYSIWYG editor component in browsers, doubtless because it’s relatively |
| 191 | straightforward to create one using JavaScript. |
| 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 | |
| 226 | [fwc]: /help?cmd=wiki |
| 227 | [fwt]: ./wikitheory.wiki |
| 228 | |
| 229 | |
| 230 | ### <a id="ln"></a>Line Numbering |
| 231 | |
| 232 | When viewing source files, Fossil offers to show line numbers in some |
| 233 |