Fossil SCM
Clarity pass on the definition of "Project" in the glossary, removing redundancies and simplifying the illlustrative examples. Also clarified the purpose of the bullet points after each definition.
Commit
db6674638ae60a51ff65749b8a9ccbc3793cd9034dbb8080d85a3a44d4ae2230
Parent
ce8598b6c1e1336…
1 file changed
+26
-28
+26
-28
| --- www/glossary.md | ||
| +++ www/glossary.md | ||
| @@ -5,12 +5,13 @@ | ||
| 5 | 5 | technical associations that can lead someone to either use the terms |
| 6 | 6 | incorrectly or to get the wrong idea from someone using those terms |
| 7 | 7 | correctly. We hope to teach users how to properly “speak Fossil” with |
| 8 | 8 | this glossary. |
| 9 | 9 | |
| 10 | -Each definition is followed by a bullet-point list of clarifying | |
| 11 | -details. These are not part of the definition itself. | |
| 10 | +The bullet-point lists following each definition are meant to be | |
| 11 | +clarifying and illustrative. They are not part of the definitions | |
| 12 | +themselves. | |
| 12 | 13 | |
| 13 | 14 | |
| 14 | 15 | ## <a id="project"></a>Project |
| 15 | 16 | |
| 16 | 17 | A collection of one or more computer files that serve some conceptually |
| @@ -44,41 +45,32 @@ | ||
| 44 | 45 | more often the case that when you get to something of a scale |
| 45 | 46 | sufficient to be called a “project,” there is more than one |
| 46 | 47 | version-tracked file involved, if not at the start, then certainly |
| 47 | 48 | by the end of the project. |
| 48 | 49 | |
| 49 | - We used the example of a fiction book above, with one chapter per | |
| 50 | - file. That implies scripts for combining those chapters into the | |
| 51 | - finished book and converting that into PDF and ePub outputs, each of | |
| 52 | - which benefit from being version-tracked. | |
| 53 | - | |
| 54 | - You could instead use a Word DOCX file for the entire book project, | |
| 55 | - with these implicit scripts replaced by Word menu commands. Fossil | |
| 56 | - will happily track that single file’s evolution for you, though | |
| 57 | - there are [good reasons](./image-format-vs-repo-size.md) to *not* do | |
| 58 | - that. | |
| 59 | - | |
| 60 | - Let us say you choose to solve the primary problems brought up in | |
| 61 | - that document by using a format like AsciiDoc instead. You could | |
| 62 | - still use a single file for the entire book’s prose content, but | |
| 63 | - even then you’re still likely to want separate files for a style | |
| 64 | - sheet, a script to convert the HTML to PDF and ePub in a reliably | |
| 65 | - repeatable fashion, cover artwork files, instructions to the | |
| 66 | - printing house, and so forth. | |
| 50 | + To take the example of a fiction book above, instead of putting each | |
| 51 | + chapter in a separate file, you could use a single AsciiDoc file for | |
| 52 | + the entire book project rather than make use of its [include | |
| 53 | + facility][AIF] to assemble it from chapter files, since that does at | |
| 54 | + least solve the [key problems][IFRS] inherent in version-tracking | |
| 55 | + something like Word’s DOCX format with Fossil instead. | |
| 56 | + | |
| 57 | + While Fossil will happily track the single file containing the prose | |
| 58 | + of your book project for you, you’re still likely to want separate | |
| 59 | + files for the cover artwork, a style sheet for use in converting the | |
| 60 | + source document to HTML, scripts to convert that intermediate output | |
| 61 | + to PDF and ePub in a reliably repeatable fashion, a `README` file | |
| 62 | + containing instructions to the printing house, and so forth. | |
| 67 | 63 | |
| 68 | 64 | * Fossil requires that all the files for a project be collected into a |
| 69 | 65 | single directory hierarchy, owned by a single user with full rights |
| 70 | 66 | to modify those files. Fossil is not a good choice for managing a |
| 71 | 67 | project that has files scattered hither and yon all over the file |
| 72 | 68 | system, nor of collections of files with complicated ownership and |
| 73 | 69 | access rights. |
| 74 | 70 | |
| 75 | - A good mental model for a Fossil project is a versioned zip file or | |
| 76 | - tarball. If you cannot easily conceive of creating or extracting | |
| 77 | - such an archive for your project, Fossil is probably not a good fit. | |
| 78 | - | |
| 79 | - As a counterexample, a project made of an operating system | |
| 71 | + A project made of an operating system | |
| 80 | 72 | installation’s configuration file set is not a good use of Fossil, |
| 81 | 73 | because you’ll have all of your OS’s *other* files intermixed. |
| 82 | 74 | Worse, Fossil doesn’t track OS permissions, so even if you were to |
| 83 | 75 | try to use Fossil as a system deployment tool by archiving versions |
| 84 | 76 | of the OS configuration files and then unpacking them on a new |
| @@ -87,17 +79,23 @@ | ||
| 87 | 79 | wanting. |
| 88 | 80 | |
| 89 | 81 | Even with these problems aside, do you really want a `.fslckout` |
| 90 | 82 | SQLite database at the root of your filesystem? Are you prepared for |
| 91 | 83 | the consequences of saying `fossil clean --verily` on such a system? |
| 84 | + You can constrain that with [the `ignore-glob` setting][IGS], but | |
| 85 | + are you prepared to write and maintain all the rules needed to keep | |
| 86 | + Fossil from blowing away the untracked portions of the file system? | |
| 92 | 87 | We believe Fossil is a poor choice for a whole-system configuration |
| 93 | 88 | backup utility. |
| 94 | 89 | |
| 95 | - And as a counter-counterexample, a project made of your user’s [Vim] | |
| 96 | - configuration is a much better use of Fossil, because it’s all held | |
| 97 | - within `~/.vim`, and your user has full rights to that subdirectory. | |
| 90 | + As a counterexample, a project tracking your [Vim] configuration | |
| 91 | + history is a much better use of Fossil, because it’s all held within | |
| 92 | + `~/.vim`, and your user has full rights to that subdirectory. | |
| 98 | 93 | |
| 94 | +[AIF]: https://docs.asciidoctor.org/asciidoc/latest/directives/include/ | |
| 95 | +[IGS]: /help?cmd=ignore-glob | |
| 96 | +[IFRS]: ./image-format-vs-repo-size.md | |
| 99 | 97 | [tarball]: /help?cmd=tarball |
| 100 | 98 | [tw]: /help?cmd=/tarball |
| 101 | 99 | [Vim]: https://www.vim.org/ |
| 102 | 100 | [zip]: /help?cmd=zip |
| 103 | 101 | [zw]: /help?cmd=/zip |
| 104 | 102 |
| --- www/glossary.md | |
| +++ www/glossary.md | |
| @@ -5,12 +5,13 @@ | |
| 5 | technical associations that can lead someone to either use the terms |
| 6 | incorrectly or to get the wrong idea from someone using those terms |
| 7 | correctly. We hope to teach users how to properly “speak Fossil” with |
| 8 | this glossary. |
| 9 | |
| 10 | Each definition is followed by a bullet-point list of clarifying |
| 11 | details. These are not part of the definition itself. |
| 12 | |
| 13 | |
| 14 | ## <a id="project"></a>Project |
| 15 | |
| 16 | A collection of one or more computer files that serve some conceptually |
| @@ -44,41 +45,32 @@ | |
| 44 | more often the case that when you get to something of a scale |
| 45 | sufficient to be called a “project,” there is more than one |
| 46 | version-tracked file involved, if not at the start, then certainly |
| 47 | by the end of the project. |
| 48 | |
| 49 | We used the example of a fiction book above, with one chapter per |
| 50 | file. That implies scripts for combining those chapters into the |
| 51 | finished book and converting that into PDF and ePub outputs, each of |
| 52 | which benefit from being version-tracked. |
| 53 | |
| 54 | You could instead use a Word DOCX file for the entire book project, |
| 55 | with these implicit scripts replaced by Word menu commands. Fossil |
| 56 | will happily track that single file’s evolution for you, though |
| 57 | there are [good reasons](./image-format-vs-repo-size.md) to *not* do |
| 58 | that. |
| 59 | |
| 60 | Let us say you choose to solve the primary problems brought up in |
| 61 | that document by using a format like AsciiDoc instead. You could |
| 62 | still use a single file for the entire book’s prose content, but |
| 63 | even then you’re still likely to want separate files for a style |
| 64 | sheet, a script to convert the HTML to PDF and ePub in a reliably |
| 65 | repeatable fashion, cover artwork files, instructions to the |
| 66 | printing house, and so forth. |
| 67 | |
| 68 | * Fossil requires that all the files for a project be collected into a |
| 69 | single directory hierarchy, owned by a single user with full rights |
| 70 | to modify those files. Fossil is not a good choice for managing a |
| 71 | project that has files scattered hither and yon all over the file |
| 72 | system, nor of collections of files with complicated ownership and |
| 73 | access rights. |
| 74 | |
| 75 | A good mental model for a Fossil project is a versioned zip file or |
| 76 | tarball. If you cannot easily conceive of creating or extracting |
| 77 | such an archive for your project, Fossil is probably not a good fit. |
| 78 | |
| 79 | As a counterexample, a project made of an operating system |
| 80 | installation’s configuration file set is not a good use of Fossil, |
| 81 | because you’ll have all of your OS’s *other* files intermixed. |
| 82 | Worse, Fossil doesn’t track OS permissions, so even if you were to |
| 83 | try to use Fossil as a system deployment tool by archiving versions |
| 84 | of the OS configuration files and then unpacking them on a new |
| @@ -87,17 +79,23 @@ | |
| 87 | wanting. |
| 88 | |
| 89 | Even with these problems aside, do you really want a `.fslckout` |
| 90 | SQLite database at the root of your filesystem? Are you prepared for |
| 91 | the consequences of saying `fossil clean --verily` on such a system? |
| 92 | We believe Fossil is a poor choice for a whole-system configuration |
| 93 | backup utility. |
| 94 | |
| 95 | And as a counter-counterexample, a project made of your user’s [Vim] |
| 96 | configuration is a much better use of Fossil, because it’s all held |
| 97 | within `~/.vim`, and your user has full rights to that subdirectory. |
| 98 | |
| 99 | [tarball]: /help?cmd=tarball |
| 100 | [tw]: /help?cmd=/tarball |
| 101 | [Vim]: https://www.vim.org/ |
| 102 | [zip]: /help?cmd=zip |
| 103 | [zw]: /help?cmd=/zip |
| 104 |
| --- www/glossary.md | |
| +++ www/glossary.md | |
| @@ -5,12 +5,13 @@ | |
| 5 | technical associations that can lead someone to either use the terms |
| 6 | incorrectly or to get the wrong idea from someone using those terms |
| 7 | correctly. We hope to teach users how to properly “speak Fossil” with |
| 8 | this glossary. |
| 9 | |
| 10 | The bullet-point lists following each definition are meant to be |
| 11 | clarifying and illustrative. They are not part of the definitions |
| 12 | themselves. |
| 13 | |
| 14 | |
| 15 | ## <a id="project"></a>Project |
| 16 | |
| 17 | A collection of one or more computer files that serve some conceptually |
| @@ -44,41 +45,32 @@ | |
| 45 | more often the case that when you get to something of a scale |
| 46 | sufficient to be called a “project,” there is more than one |
| 47 | version-tracked file involved, if not at the start, then certainly |
| 48 | by the end of the project. |
| 49 | |
| 50 | To take the example of a fiction book above, instead of putting each |
| 51 | chapter in a separate file, you could use a single AsciiDoc file for |
| 52 | the entire book project rather than make use of its [include |
| 53 | facility][AIF] to assemble it from chapter files, since that does at |
| 54 | least solve the [key problems][IFRS] inherent in version-tracking |
| 55 | something like Word’s DOCX format with Fossil instead. |
| 56 | |
| 57 | While Fossil will happily track the single file containing the prose |
| 58 | of your book project for you, you’re still likely to want separate |
| 59 | files for the cover artwork, a style sheet for use in converting the |
| 60 | source document to HTML, scripts to convert that intermediate output |
| 61 | to PDF and ePub in a reliably repeatable fashion, a `README` file |
| 62 | containing instructions to the printing house, and so forth. |
| 63 | |
| 64 | * Fossil requires that all the files for a project be collected into a |
| 65 | single directory hierarchy, owned by a single user with full rights |
| 66 | to modify those files. Fossil is not a good choice for managing a |
| 67 | project that has files scattered hither and yon all over the file |
| 68 | system, nor of collections of files with complicated ownership and |
| 69 | access rights. |
| 70 | |
| 71 | A project made of an operating system |
| 72 | installation’s configuration file set is not a good use of Fossil, |
| 73 | because you’ll have all of your OS’s *other* files intermixed. |
| 74 | Worse, Fossil doesn’t track OS permissions, so even if you were to |
| 75 | try to use Fossil as a system deployment tool by archiving versions |
| 76 | of the OS configuration files and then unpacking them on a new |
| @@ -87,17 +79,23 @@ | |
| 79 | wanting. |
| 80 | |
| 81 | Even with these problems aside, do you really want a `.fslckout` |
| 82 | SQLite database at the root of your filesystem? Are you prepared for |
| 83 | the consequences of saying `fossil clean --verily` on such a system? |
| 84 | You can constrain that with [the `ignore-glob` setting][IGS], but |
| 85 | are you prepared to write and maintain all the rules needed to keep |
| 86 | Fossil from blowing away the untracked portions of the file system? |
| 87 | We believe Fossil is a poor choice for a whole-system configuration |
| 88 | backup utility. |
| 89 | |
| 90 | As a counterexample, a project tracking your [Vim] configuration |
| 91 | history is a much better use of Fossil, because it’s all held within |
| 92 | `~/.vim`, and your user has full rights to that subdirectory. |
| 93 | |
| 94 | [AIF]: https://docs.asciidoctor.org/asciidoc/latest/directives/include/ |
| 95 | [IGS]: /help?cmd=ignore-glob |
| 96 | [IFRS]: ./image-format-vs-repo-size.md |
| 97 | [tarball]: /help?cmd=tarball |
| 98 | [tw]: /help?cmd=/tarball |
| 99 | [Vim]: https://www.vim.org/ |
| 100 | [zip]: /help?cmd=zip |
| 101 | [zw]: /help?cmd=/zip |
| 102 |