Fossil SCM

Restructured fileedit-page.md to give more space to/explanation of each caveat/warning bullet point (each of which is now in its own subsection).

stephan 2020-05-14 15:10 fileedit-ajaxify
Commit 33146972e6abbf45cc1d7505b925657e159cc6b3fd7e0b6346a5bb853b34395c
Parent b83ff3f42192c5b…
1 file changed +92 -40
~ www/fileedit-page.md
M www/fileedit-page.md
+92 -40
--- www/fileedit-page.md
+++ www/fileedit-page.md
@@ -1,48 +1,100 @@
11
 # The fileedit Page
22
33
 This document describes some tips and tricks for the [](/fileedit)
4
-page, which provides basic editing features for files via the web
5
-interface.
6
-
7
-# First and Foremost...
8
-
9
-Notes, caveats, and disclaimers:
10
-
11
-- **`/fileedit` does nothing by default.** In order to "activate" it,
12
- a user with [the "setup" permission](./caps/index.md) must set the
13
- [fileedit-glob](/help?cmd=fileedit-glob) repository setting to a
14
- comma- or newline-delimited list of globs representing a whitelist
15
- of files which may be edited online. Any user with commit access may
16
- then edit files matching one of those globs.
17
-- `/fileedit` **works by creating commits** (a.k.a. checkins), thus
18
- any edits made via that page become a normal part of the repository's
19
- blockchain.
20
-- `/fileedit` is **intended to facilitate online edits of
21
- embedded docs and similar text files**, and is most certainly
22
- **not intended for editing code**. Editing files with unusual
23
- syntax requirements, e.g. hard tabs in makefiles, may break
24
- them. *You Have Been Warned.*
25
- - Similarly, though every effort is made to retain the end-of-line
26
- style used by being-edited files, the round-trip through an HTML
27
- textarea element may change the EOLs. The Commit section of the
28
- page offers 3 different options for how to treat newlines when
29
- saving changes. Files with mixed EOL styles *will be normalized
30
- to a single EOL style* when modified using `/fileedit`.
31
-- `/fileedit` **is not a replacement for a checkout**. A full-featured
32
- checkout allows far more possibilities than this basic online editor
33
- permits, and the feature scope of `/fileedit` is intentionally kept
34
- small, implementing only the bare necessities needed for performing
35
- basic edits online.
36
-- `/fileedit` **does not store draft versions while working**. i.e. if
37
- the browser's tab is closed or a link is clicked, taking the user to
38
- a different page, any current edits *will be lost*. See the note
39
- above about this feature *not* being a replacement for a
40
- full-fledged checkout.
41
-- "With great power comes great responsibility." **Use this feature
42
- judiciously, if at all.**
43
-
4
+page, which provides, for users with [checkin
5
+privileges](./caps/index.md), basic editing features for files via the
6
+web interface.
7
+
8
+# Important Caveats and Disclaimers
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
+files which may be edited online. Any user with commit access may then
21
+edit files matching one of those globs.
22
+
23
+### `/fileedit` **Works by Creating Commits**
24
+
25
+Thus any edits made via that page become a normal part of the
26
+repository's blockchain.
27
+
28
+### `/fileedit` is **Intended for use with Embedded Docs**
29
+
30
+... and similar text files, and is most certainly
31
+**not intended for editing code**.
32
+
33
+Editing files with unusual syntax requirements, e.g. hard tabs in
34
+makefiles, may break them. *You Have Been Warned.*
35
+
36
+Similarly, though every effort is made to retain the end-of-line
37
+style used by being-edited files, the round-trip through an HTML
38
+textarea element may change the EOLs. The Commit section of the page
39
+offers three different options for how to treat newlines when saving
40
+changes. **Files with mixed EOL styles** *will be normalized to a single
41
+EOL style* when modified using `/fileedit`. When "inheriting" the EOL
42
+style from a previous version which has mixed styles, the first EOL
43
+style detected in the file is used.
44
+
45
+### `/fileedit` **is Not a Replacement for a Checkout**
46
+
47
+A full-featured checkout allows far more possibilities than this basic
48
+online editor permits, and the feature scope of `/fileedit` is
49
+intentionally kept small, implementing only the bare necessities
50
+needed for performing basic edits online. It *is not, and will never
51
+be, a replacement for a checkout.*
52
+
53
+It is to be expected that users will want to do "more" with this
54
+page, and we generally encourage feature requests, but be aware that
55
+certain types of ostensibly sensible feature requests *will be
56
+rejected* for `/fileedit`. These include, but are not limited to:
57
+
58
+- Features which are already provided by other pages, e.g.
59
+the ability to create a new named branch or add tags.
60
+- Features which would require re-implementing significant
61
+capabilities provided only within a checkout (e.g. merging files).
62
+- The ability to edit/manipulate files which are in a local
63
+checkout. (If you have a checkout, use your local editor, not
64
+`/fileedit`.)
65
+- Editing of non-text files, e.g. images. Use a checkout and your
66
+preferred graphics editor.
67
+- Support for syncing/pulling/pushing of a repository before and/or
68
+after edits. Those features cannot be *reliably* provided via a web
69
+interface for several reasons, not the least of which is that some
70
+backend servers simply do not permit outbound network connections to
71
+arbitrary hosts.
72
+
73
+Similarly, some *potential* features have significant downsides,
74
+abuses, and/or implementation hurdles which make the decision of
75
+whether or not to implement them subject to notable contributor
76
+debate. e.g. the ability to add new files or remove/rename older
77
+files.
78
+
79
+
80
+### `/fileedit` **Does Not Store Draft Versions While Working**
81
+
82
+When using `/fileedit`, if the browser's tab is closed, a link is
83
+clicked, or the user otherwise leaves the page, any current edits
84
+*will be lost*. See the note above about this feature *not* being a
85
+replacement for a full-fledged checkout.
86
+
87
+### The Power is Yours, but...
88
+
89
+> "With great power comes great responsibility."
90
+
91
+**Use this feature judiciously, *if at all*.**
92
+
93
+Now, with those warnings and caveats out of the way...
94
+
95
+-----
4496
4597
 # Tips and Tricks
4698
4799
 ## `fossil` Global-scope JS Object
48100
49101
--- www/fileedit-page.md
+++ www/fileedit-page.md
@@ -1,48 +1,100 @@
1 # The fileedit Page
2
3 This document describes some tips and tricks for the [](/fileedit)
4 page, which provides basic editing features for files via the web
5 interface.
6
7 # First and Foremost...
8
9 Notes, caveats, and disclaimers:
10
11 - **`/fileedit` does nothing by default.** In order to "activate" it,
12 a user with [the "setup" permission](./caps/index.md) must set the
13 [fileedit-glob](/help?cmd=fileedit-glob) repository setting to a
14 comma- or newline-delimited list of globs representing a whitelist
15 of files which may be edited online. Any user with commit access may
16 then edit files matching one of those globs.
17 - `/fileedit` **works by creating commits** (a.k.a. checkins), thus
18 any edits made via that page become a normal part of the repository's
19 blockchain.
20 - `/fileedit` is **intended to facilitate online edits of
21 embedded docs and similar text files**, and is most certainly
22 **not intended for editing code**. Editing files with unusual
23 syntax requirements, e.g. hard tabs in makefiles, may break
24 them. *You Have Been Warned.*
25 - Similarly, though every effort is made to retain the end-of-line
26 style used by being-edited files, the round-trip through an HTML
27 textarea element may change the EOLs. The Commit section of the
28 page offers 3 different options for how to treat newlines when
29 saving changes. Files with mixed EOL styles *will be normalized
30 to a single EOL style* when modified using `/fileedit`.
31 - `/fileedit` **is not a replacement for a checkout**. A full-featured
32 checkout allows far more possibilities than this basic online editor
33 permits, and the feature scope of `/fileedit` is intentionally kept
34 small, implementing only the bare necessities needed for performing
35 basic edits online.
36 - `/fileedit` **does not store draft versions while working**. i.e. if
37 the browser's tab is closed or a link is clicked, taking the user to
38 a different page, any current edits *will be lost*. See the note
39 above about this feature *not* being a replacement for a
40 full-fledged checkout.
41 - "With great power comes great responsibility." **Use this feature
42 judiciously, if at all.**
43
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
44
45 # Tips and Tricks
46
47 ## `fossil` Global-scope JS Object
48
49
--- www/fileedit-page.md
+++ www/fileedit-page.md
@@ -1,48 +1,100 @@
1 # The fileedit Page
2
3 This document describes some tips and tricks for the [](/fileedit)
4 page, which provides, for users with [checkin
5 privileges](./caps/index.md), basic editing features for files via the
6 web interface.
7
8 # Important Caveats and Disclaimers
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 files which may be edited online. Any user with commit access may then
21 edit files matching one of those globs.
22
23 ### `/fileedit` **Works by Creating Commits**
24
25 Thus any edits made via that page become a normal part of the
26 repository's blockchain.
27
28 ### `/fileedit` is **Intended for use with Embedded Docs**
29
30 ... and similar text files, and is most certainly
31 **not intended for editing code**.
32
33 Editing files with unusual syntax requirements, e.g. hard tabs in
34 makefiles, may break them. *You Have Been Warned.*
35
36 Similarly, though every effort is made to retain the end-of-line
37 style used by being-edited files, the round-trip through an HTML
38 textarea element may change the EOLs. The Commit section of the page
39 offers three different options for how to treat newlines when saving
40 changes. **Files with mixed EOL styles** *will be normalized to a single
41 EOL style* when modified using `/fileedit`. When "inheriting" the EOL
42 style from a previous version which has mixed styles, the first EOL
43 style detected in the file is used.
44
45 ### `/fileedit` **is Not a Replacement for a Checkout**
46
47 A full-featured checkout allows far more possibilities than this basic
48 online editor permits, and the feature scope of `/fileedit` is
49 intentionally kept small, implementing only the bare necessities
50 needed for performing basic edits online. It *is not, and will never
51 be, a replacement for a checkout.*
52
53 It is to be expected that users will want to do "more" with this
54 page, and we generally encourage feature requests, but be aware that
55 certain types of ostensibly sensible feature requests *will be
56 rejected* for `/fileedit`. These include, but are not limited to:
57
58 - Features which are already provided by other pages, e.g.
59 the ability to create a new named branch or add tags.
60 - Features which would require re-implementing significant
61 capabilities provided only within a checkout (e.g. merging files).
62 - The ability to edit/manipulate files which are in a local
63 checkout. (If you have a checkout, use your local editor, not
64 `/fileedit`.)
65 - Editing of non-text files, e.g. images. Use a checkout and your
66 preferred graphics editor.
67 - Support for syncing/pulling/pushing of a repository before and/or
68 after edits. Those features cannot be *reliably* provided via a web
69 interface for several reasons, not the least of which is that some
70 backend servers simply do not permit outbound network connections to
71 arbitrary hosts.
72
73 Similarly, some *potential* features have significant downsides,
74 abuses, and/or implementation hurdles which make the decision of
75 whether or not to implement them subject to notable contributor
76 debate. e.g. the ability to add new files or remove/rename older
77 files.
78
79
80 ### `/fileedit` **Does Not Store Draft Versions While Working**
81
82 When using `/fileedit`, if the browser's tab is closed, a link is
83 clicked, or the user otherwise leaves the page, any current edits
84 *will be lost*. See the note above about this feature *not* being a
85 replacement for a full-fledged checkout.
86
87 ### The Power is Yours, but...
88
89 > "With great power comes great responsibility."
90
91 **Use this feature judiciously, *if at all*.**
92
93 Now, with those warnings and caveats out of the way...
94
95 -----
96
97 # Tips and Tricks
98
99 ## `fossil` Global-scope JS Object
100
101

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button