Fossil SCM
Added named anchors in the /fileedit doc page.
Commit
66851cd6bc9091f26280331ceddbf76cb29987f0eb18fee814073968fe1cc545
Parent
4c1d38f97b4ecf1…
1 file changed
+11
-11
+11
-11
| --- www/fileedit-page.md | ||
| +++ www/fileedit-page.md | ||
| @@ -9,11 +9,11 @@ | ||
| 9 | 9 | |
| 10 | 10 | Predictably, the ability to edit files in a repository from a web |
| 11 | 11 | browser halfway around the world comes with several obligatory caveats |
| 12 | 12 | and disclaimers... |
| 13 | 13 | |
| 14 | -## `/fileedit` Does *Nothing* by Default. | |
| 14 | +## <a id="cap"></a> `/fileedit` Does *Nothing* by Default. | |
| 15 | 15 | |
| 16 | 16 | In order to "activate" it, a user with [the "setup" |
| 17 | 17 | permission](./caps/index.md) must set the |
| 18 | 18 | [fileedit-glob](/help?cmd=fileedit-glob) repository setting to a |
| 19 | 19 | comma- or newline-delimited list of globs representing a whitelist of |
| @@ -20,11 +20,11 @@ | ||
| 20 | 20 | files which may be edited online. Any user with commit access may then |
| 21 | 21 | edit files matching one of those globs. Certain pages within the UI |
| 22 | 22 | get an "edit" link added to them when the current user's permissions |
| 23 | 23 | and the whitelist both permit editing of that file. |
| 24 | 24 | |
| 25 | -## CSRF & HTTP Referrer Headers | |
| 25 | +## <a id="csrf"></a> CSRF & HTTP Referrer Headers | |
| 26 | 26 | |
| 27 | 27 | In order to protect against [Cross-site Request Forgery (CSRF)][csrf] |
| 28 | 28 | attacks, Fossil UI features which write to the database require that |
| 29 | 29 | the browser send the so-called [HTTP `Referer` header][referer] |
| 30 | 30 | (noting that the misspelling of "referrer" is a historical accident |
| @@ -53,16 +53,16 @@ | ||
| 53 | 53 | |
| 54 | 54 | [referer]: https://en.wikipedia.org/wiki/HTTP_referer |
| 55 | 55 | [csrf]: https://en.wikipedia.org/wiki/Cross-site_request_forgery |
| 56 | 56 | [xhr]: https://en.wikipedia.org/wiki/XMLHttpRequest |
| 57 | 57 | |
| 58 | -## `/fileedit` **Works by Creating Commits** | |
| 58 | +## <a id="commit"></a> `/fileedit` **Works by Creating Commits** | |
| 59 | 59 | |
| 60 | 60 | Thus any edits made via that page become a normal part of the |
| 61 | 61 | repository. |
| 62 | 62 | |
| 63 | -## `/fileedit` is *Intended* for use with Embedded Docs | |
| 63 | +## <a id="intent"></a> `/fileedit` is *Intended* for use with Embedded Docs | |
| 64 | 64 | |
| 65 | 65 | ... and similar text files, and is most certainly |
| 66 | 66 | **not intended for editing code**. |
| 67 | 67 | |
| 68 | 68 | Editing files with unusual syntax requirements, e.g. hard tabs in |
| @@ -75,11 +75,11 @@ | ||
| 75 | 75 | changes. **Files with mixed EOL styles** *will be normalized to a single |
| 76 | 76 | EOL style* when modified using `/fileedit`. When "inheriting" the EOL |
| 77 | 77 | style from a previous version which has mixed styles, the first EOL |
| 78 | 78 | style detected in the previous version of the file is used. |
| 79 | 79 | |
| 80 | -## `/fileedit` **is Not a Replacement for a Checkout** | |
| 80 | +## <a id="checkout"></a> `/fileedit` **is Not a Replacement for a Checkout** | |
| 81 | 81 | |
| 82 | 82 | A full-featured checkout allows far more possibilities than this basic |
| 83 | 83 | online editor permits, and the feature scope of `/fileedit` is |
| 84 | 84 | intentionally kept small, implementing only the bare necessities |
| 85 | 85 | needed for performing basic edits online. It *is not, and will never |
| @@ -108,11 +108,11 @@ | ||
| 108 | 108 | whether or not to implement them subject to notable contributor |
| 109 | 109 | debate. e.g. the ability to add new files or remove/rename older |
| 110 | 110 | files. |
| 111 | 111 | |
| 112 | 112 | |
| 113 | -## `/fileedit` **Stores Only Limited Local Edits While Working** | |
| 113 | +## <a id="storage"></a> `/fileedit` **Stores Only Limited Local Edits While Working** | |
| 114 | 114 | |
| 115 | 115 | When changes are made to a given checkin/file combination, |
| 116 | 116 | `/fileedit` will, if possible, store them in [`window.localStorage` |
| 117 | 117 | or `window.sessionStorage`][html5storage], if available, but... |
| 118 | 118 | |
| @@ -142,23 +142,23 @@ | ||
| 142 | 142 | If `/filepage` determines that no peristent storage is available a |
| 143 | 143 | warning is displayed on the editor page. |
| 144 | 144 | |
| 145 | 145 | [html5storage]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API |
| 146 | 146 | |
| 147 | -## The Power is Yours, but... | |
| 147 | +## <a id="power"></a> The Power is Yours, but... | |
| 148 | 148 | |
| 149 | 149 | > "With great power comes great responsibility." |
| 150 | 150 | |
| 151 | 151 | **Use this feature judiciously, *if at all*.** |
| 152 | 152 | |
| 153 | 153 | Now, with those warnings and caveats out of the way... |
| 154 | 154 | |
| 155 | 155 | ----- |
| 156 | 156 | |
| 157 | -# Tips and Tricks | |
| 157 | +# <a id="tips"></a> Tips and Tricks | |
| 158 | 158 | |
| 159 | -## `fossil` Global-scope JS Object | |
| 159 | +## <a id="global-js"></a> `fossil` Global-scope JS Object | |
| 160 | 160 | |
| 161 | 161 | `/fileedit` is largely implemented in JavaScript, and makes heavy use |
| 162 | 162 | of the global-scope `fossil` object, which provides |
| 163 | 163 | infrastructure-level features intended for use by Fossil UI pages. |
| 164 | 164 | (That said, that infrastructure was introduced with `/fileedit`, and |
| @@ -169,11 +169,11 @@ | ||
| 169 | 169 | listening to page-specific events so that JS code installed via |
| 170 | 170 | [client-side edits to the site skin's footer](customskin.md) may react |
| 171 | 171 | to those changes somehow. The next section describes one such use for |
| 172 | 172 | such events... |
| 173 | 173 | |
| 174 | -## Integrating Syntax Highlighting | |
| 174 | +## <a id="syn-hl"></a> Integrating Syntax Highlighting | |
| 175 | 175 | |
| 176 | 176 | Assuming a repository has integrated a 3rd-party syntax highlighting |
| 177 | 177 | solution, it can probably (depending on its API) be told how to |
| 178 | 178 | highlight `/fileedit`'s wiki/markdown-format previews. Here are |
| 179 | 179 | instructions for doing so with [highlightjs](https://highlightjs.org/): |
| @@ -223,11 +223,11 @@ | ||
| 223 | 223 | The event listener callback shown above doesn't use the `mimetype`, |
| 224 | 224 | but makes used of the other two. It fishes all `code` blocks out of |
| 225 | 225 | the preview which explicitly have a CSS class named |
| 226 | 226 | `language-`something, and then asks highlightjs to highlight them. |
| 227 | 227 | |
| 228 | -## Integrating a Custom Editor Widget | |
| 228 | +## <a id="editor"></a> Integrating a Custom Editor Widget | |
| 229 | 229 | |
| 230 | 230 | (These instructions also work for the `/wikiedit` page by eplacing |
| 231 | 231 | "fileedit" with "wikiedit" in any strings or symbol names!) |
| 232 | 232 | |
| 233 | 233 | It is possible to replace `/filepage`'s basic text-editing widget (a |
| 234 | 234 |
| --- www/fileedit-page.md | |
| +++ www/fileedit-page.md | |
| @@ -9,11 +9,11 @@ | |
| 9 | |
| 10 | Predictably, the ability to edit files in a repository from a web |
| 11 | browser halfway around the world comes with several obligatory caveats |
| 12 | and disclaimers... |
| 13 | |
| 14 | ## `/fileedit` Does *Nothing* by Default. |
| 15 | |
| 16 | In order to "activate" it, a user with [the "setup" |
| 17 | permission](./caps/index.md) must set the |
| 18 | [fileedit-glob](/help?cmd=fileedit-glob) repository setting to a |
| 19 | comma- or newline-delimited list of globs representing a whitelist of |
| @@ -20,11 +20,11 @@ | |
| 20 | files which may be edited online. Any user with commit access may then |
| 21 | edit files matching one of those globs. Certain pages within the UI |
| 22 | get an "edit" link added to them when the current user's permissions |
| 23 | and the whitelist both permit editing of that file. |
| 24 | |
| 25 | ## CSRF & HTTP Referrer Headers |
| 26 | |
| 27 | In order to protect against [Cross-site Request Forgery (CSRF)][csrf] |
| 28 | attacks, Fossil UI features which write to the database require that |
| 29 | the browser send the so-called [HTTP `Referer` header][referer] |
| 30 | (noting that the misspelling of "referrer" is a historical accident |
| @@ -53,16 +53,16 @@ | |
| 53 | |
| 54 | [referer]: https://en.wikipedia.org/wiki/HTTP_referer |
| 55 | [csrf]: https://en.wikipedia.org/wiki/Cross-site_request_forgery |
| 56 | [xhr]: https://en.wikipedia.org/wiki/XMLHttpRequest |
| 57 | |
| 58 | ## `/fileedit` **Works by Creating Commits** |
| 59 | |
| 60 | Thus any edits made via that page become a normal part of the |
| 61 | repository. |
| 62 | |
| 63 | ## `/fileedit` is *Intended* for use with Embedded Docs |
| 64 | |
| 65 | ... and similar text files, and is most certainly |
| 66 | **not intended for editing code**. |
| 67 | |
| 68 | Editing files with unusual syntax requirements, e.g. hard tabs in |
| @@ -75,11 +75,11 @@ | |
| 75 | changes. **Files with mixed EOL styles** *will be normalized to a single |
| 76 | EOL style* when modified using `/fileedit`. When "inheriting" the EOL |
| 77 | style from a previous version which has mixed styles, the first EOL |
| 78 | style detected in the previous version of the file is used. |
| 79 | |
| 80 | ## `/fileedit` **is Not a Replacement for a Checkout** |
| 81 | |
| 82 | A full-featured checkout allows far more possibilities than this basic |
| 83 | online editor permits, and the feature scope of `/fileedit` is |
| 84 | intentionally kept small, implementing only the bare necessities |
| 85 | needed for performing basic edits online. It *is not, and will never |
| @@ -108,11 +108,11 @@ | |
| 108 | whether or not to implement them subject to notable contributor |
| 109 | debate. e.g. the ability to add new files or remove/rename older |
| 110 | files. |
| 111 | |
| 112 | |
| 113 | ## `/fileedit` **Stores Only Limited Local Edits While Working** |
| 114 | |
| 115 | When changes are made to a given checkin/file combination, |
| 116 | `/fileedit` will, if possible, store them in [`window.localStorage` |
| 117 | or `window.sessionStorage`][html5storage], if available, but... |
| 118 | |
| @@ -142,23 +142,23 @@ | |
| 142 | If `/filepage` determines that no peristent storage is available a |
| 143 | warning is displayed on the editor page. |
| 144 | |
| 145 | [html5storage]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API |
| 146 | |
| 147 | ## The Power is Yours, but... |
| 148 | |
| 149 | > "With great power comes great responsibility." |
| 150 | |
| 151 | **Use this feature judiciously, *if at all*.** |
| 152 | |
| 153 | Now, with those warnings and caveats out of the way... |
| 154 | |
| 155 | ----- |
| 156 | |
| 157 | # Tips and Tricks |
| 158 | |
| 159 | ## `fossil` Global-scope JS Object |
| 160 | |
| 161 | `/fileedit` is largely implemented in JavaScript, and makes heavy use |
| 162 | of the global-scope `fossil` object, which provides |
| 163 | infrastructure-level features intended for use by Fossil UI pages. |
| 164 | (That said, that infrastructure was introduced with `/fileedit`, and |
| @@ -169,11 +169,11 @@ | |
| 169 | listening to page-specific events so that JS code installed via |
| 170 | [client-side edits to the site skin's footer](customskin.md) may react |
| 171 | to those changes somehow. The next section describes one such use for |
| 172 | such events... |
| 173 | |
| 174 | ## Integrating Syntax Highlighting |
| 175 | |
| 176 | Assuming a repository has integrated a 3rd-party syntax highlighting |
| 177 | solution, it can probably (depending on its API) be told how to |
| 178 | highlight `/fileedit`'s wiki/markdown-format previews. Here are |
| 179 | instructions for doing so with [highlightjs](https://highlightjs.org/): |
| @@ -223,11 +223,11 @@ | |
| 223 | The event listener callback shown above doesn't use the `mimetype`, |
| 224 | but makes used of the other two. It fishes all `code` blocks out of |
| 225 | the preview which explicitly have a CSS class named |
| 226 | `language-`something, and then asks highlightjs to highlight them. |
| 227 | |
| 228 | ## Integrating a Custom Editor Widget |
| 229 | |
| 230 | (These instructions also work for the `/wikiedit` page by eplacing |
| 231 | "fileedit" with "wikiedit" in any strings or symbol names!) |
| 232 | |
| 233 | It is possible to replace `/filepage`'s basic text-editing widget (a |
| 234 |
| --- www/fileedit-page.md | |
| +++ www/fileedit-page.md | |
| @@ -9,11 +9,11 @@ | |
| 9 | |
| 10 | Predictably, the ability to edit files in a repository from a web |
| 11 | browser halfway around the world comes with several obligatory caveats |
| 12 | and disclaimers... |
| 13 | |
| 14 | ## <a id="cap"></a> `/fileedit` Does *Nothing* by Default. |
| 15 | |
| 16 | In order to "activate" it, a user with [the "setup" |
| 17 | permission](./caps/index.md) must set the |
| 18 | [fileedit-glob](/help?cmd=fileedit-glob) repository setting to a |
| 19 | comma- or newline-delimited list of globs representing a whitelist of |
| @@ -20,11 +20,11 @@ | |
| 20 | files which may be edited online. Any user with commit access may then |
| 21 | edit files matching one of those globs. Certain pages within the UI |
| 22 | get an "edit" link added to them when the current user's permissions |
| 23 | and the whitelist both permit editing of that file. |
| 24 | |
| 25 | ## <a id="csrf"></a> CSRF & HTTP Referrer Headers |
| 26 | |
| 27 | In order to protect against [Cross-site Request Forgery (CSRF)][csrf] |
| 28 | attacks, Fossil UI features which write to the database require that |
| 29 | the browser send the so-called [HTTP `Referer` header][referer] |
| 30 | (noting that the misspelling of "referrer" is a historical accident |
| @@ -53,16 +53,16 @@ | |
| 53 | |
| 54 | [referer]: https://en.wikipedia.org/wiki/HTTP_referer |
| 55 | [csrf]: https://en.wikipedia.org/wiki/Cross-site_request_forgery |
| 56 | [xhr]: https://en.wikipedia.org/wiki/XMLHttpRequest |
| 57 | |
| 58 | ## <a id="commit"></a> `/fileedit` **Works by Creating Commits** |
| 59 | |
| 60 | Thus any edits made via that page become a normal part of the |
| 61 | repository. |
| 62 | |
| 63 | ## <a id="intent"></a> `/fileedit` is *Intended* for use with Embedded Docs |
| 64 | |
| 65 | ... and similar text files, and is most certainly |
| 66 | **not intended for editing code**. |
| 67 | |
| 68 | Editing files with unusual syntax requirements, e.g. hard tabs in |
| @@ -75,11 +75,11 @@ | |
| 75 | changes. **Files with mixed EOL styles** *will be normalized to a single |
| 76 | EOL style* when modified using `/fileedit`. When "inheriting" the EOL |
| 77 | style from a previous version which has mixed styles, the first EOL |
| 78 | style detected in the previous version of the file is used. |
| 79 | |
| 80 | ## <a id="checkout"></a> `/fileedit` **is Not a Replacement for a Checkout** |
| 81 | |
| 82 | A full-featured checkout allows far more possibilities than this basic |
| 83 | online editor permits, and the feature scope of `/fileedit` is |
| 84 | intentionally kept small, implementing only the bare necessities |
| 85 | needed for performing basic edits online. It *is not, and will never |
| @@ -108,11 +108,11 @@ | |
| 108 | whether or not to implement them subject to notable contributor |
| 109 | debate. e.g. the ability to add new files or remove/rename older |
| 110 | files. |
| 111 | |
| 112 | |
| 113 | ## <a id="storage"></a> `/fileedit` **Stores Only Limited Local Edits While Working** |
| 114 | |
| 115 | When changes are made to a given checkin/file combination, |
| 116 | `/fileedit` will, if possible, store them in [`window.localStorage` |
| 117 | or `window.sessionStorage`][html5storage], if available, but... |
| 118 | |
| @@ -142,23 +142,23 @@ | |
| 142 | If `/filepage` determines that no peristent storage is available a |
| 143 | warning is displayed on the editor page. |
| 144 | |
| 145 | [html5storage]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API |
| 146 | |
| 147 | ## <a id="power"></a> The Power is Yours, but... |
| 148 | |
| 149 | > "With great power comes great responsibility." |
| 150 | |
| 151 | **Use this feature judiciously, *if at all*.** |
| 152 | |
| 153 | Now, with those warnings and caveats out of the way... |
| 154 | |
| 155 | ----- |
| 156 | |
| 157 | # <a id="tips"></a> Tips and Tricks |
| 158 | |
| 159 | ## <a id="global-js"></a> `fossil` Global-scope JS Object |
| 160 | |
| 161 | `/fileedit` is largely implemented in JavaScript, and makes heavy use |
| 162 | of the global-scope `fossil` object, which provides |
| 163 | infrastructure-level features intended for use by Fossil UI pages. |
| 164 | (That said, that infrastructure was introduced with `/fileedit`, and |
| @@ -169,11 +169,11 @@ | |
| 169 | listening to page-specific events so that JS code installed via |
| 170 | [client-side edits to the site skin's footer](customskin.md) may react |
| 171 | to those changes somehow. The next section describes one such use for |
| 172 | such events... |
| 173 | |
| 174 | ## <a id="syn-hl"></a> Integrating Syntax Highlighting |
| 175 | |
| 176 | Assuming a repository has integrated a 3rd-party syntax highlighting |
| 177 | solution, it can probably (depending on its API) be told how to |
| 178 | highlight `/fileedit`'s wiki/markdown-format previews. Here are |
| 179 | instructions for doing so with [highlightjs](https://highlightjs.org/): |
| @@ -223,11 +223,11 @@ | |
| 223 | The event listener callback shown above doesn't use the `mimetype`, |
| 224 | but makes used of the other two. It fishes all `code` blocks out of |
| 225 | the preview which explicitly have a CSS class named |
| 226 | `language-`something, and then asks highlightjs to highlight them. |
| 227 | |
| 228 | ## <a id="editor"></a> Integrating a Custom Editor Widget |
| 229 | |
| 230 | (These instructions also work for the `/wikiedit` page by eplacing |
| 231 | "fileedit" with "wikiedit" in any strings or symbol names!) |
| 232 | |
| 233 | It is possible to replace `/filepage`'s basic text-editing widget (a |
| 234 |