Fossil SCM
A few small improvements to embeddeddoc.wiki: added a named anchor so we can refer directly to the section talking about "ckout", referred to checkin_names.wiki only once from the relevant paragraph instead of twice, and added a paragraph explaining why this feature is particularly useful. This is in support of an upcoming commit: we're going to remove some redundant commentary about "commit" in checkin_names.wiki.
Commit
51511b7205f6046a671531784f37665fc97ff99fd781a6047cf04ee1482bab58
Parent
c0a91653abc9a43…
1 file changed
+15
-3
+15
-3
| --- www/embeddeddoc.wiki | ||
| +++ www/embeddeddoc.wiki | ||
| @@ -41,24 +41,36 @@ | ||
| 41 | 41 | [https://www.fossil-scm.org/fossil]. |
| 42 | 42 | If you launch the web server using the "[/help?cmd=ui|fossil ui]" command line, |
| 43 | 43 | then the <i><baseurl></i> is usually |
| 44 | 44 | <b>http://localhost:8080/</b>. |
| 45 | 45 | |
| 46 | -The <i><version></i> is [./checkin_names.wiki|name of a check-in] | |
| 46 | +The <i><version></i> is the | |
| 47 | +[./checkin_names.wiki|name of a check-in] | |
| 47 | 48 | that contains the embedded document. This might be a hash prefix for |
| 48 | 49 | the check-in, or it might be the name of a branch or tag, or it might |
| 49 | -be a timestamp. See the [./checkin_names.wiki|check-in name documentation] | |
| 50 | -for more possibilities and examples. The <i><version></i> can | |
| 50 | +be a timestamp. See the prior link | |
| 51 | +for more possibilities and examples. | |
| 52 | + | |
| 53 | +<a id="ckout"></a>The <i><version></i> can | |
| 51 | 54 | also be the special identifier "<b>ckout</b>". |
| 52 | 55 | The "<b>ckout</b>" keywords means to |
| 53 | 56 | pull the documentation file from the local source tree on disk, not |
| 54 | 57 | from the any check-in. The "<b>ckout</b>" keyword |
| 55 | 58 | only works when you start your server using the |
| 56 | 59 | "[/help?cmd=server|fossil server]" or "[/help?cmd=ui|fossil ui]" |
| 57 | 60 | commands. The "/doc/ckout" URL is intended to show a preview of |
| 58 | 61 | the documentation you are currently editing but have not yet you checked in. |
| 59 | 62 | |
| 63 | +The original designed purpose of the "ckout" feature is to allow the | |
| 64 | +user to preview local changes to documentation before committing the | |
| 65 | +change. This is an important facility, since unlike other document | |
| 66 | +languages like HTML, there is still a lot of variation among rendering | |
| 67 | +engines for Fossil's markup languages, Markdown and Fossil Wiki. Your | |
| 68 | +changes may look fine in your whizzy GUI Markdown editor, but what | |
| 69 | +actually matters is how <i>Fossil</i> will interpret your Markdown text. | |
| 70 | +Therefore, you should always preview your edits before committing them. | |
| 71 | + | |
| 60 | 72 | Finally, the <i><filename></i> element of the URL is the |
| 61 | 73 | pathname of the documentation file relative to the root of the source |
| 62 | 74 | tree. |
| 63 | 75 | |
| 64 | 76 | The mimetype (and thus the rendering) of documentation files is |
| 65 | 77 |
| --- www/embeddeddoc.wiki | |
| +++ www/embeddeddoc.wiki | |
| @@ -41,24 +41,36 @@ | |
| 41 | [https://www.fossil-scm.org/fossil]. |
| 42 | If you launch the web server using the "[/help?cmd=ui|fossil ui]" command line, |
| 43 | then the <i><baseurl></i> is usually |
| 44 | <b>http://localhost:8080/</b>. |
| 45 | |
| 46 | The <i><version></i> is [./checkin_names.wiki|name of a check-in] |
| 47 | that contains the embedded document. This might be a hash prefix for |
| 48 | the check-in, or it might be the name of a branch or tag, or it might |
| 49 | be a timestamp. See the [./checkin_names.wiki|check-in name documentation] |
| 50 | for more possibilities and examples. The <i><version></i> can |
| 51 | also be the special identifier "<b>ckout</b>". |
| 52 | The "<b>ckout</b>" keywords means to |
| 53 | pull the documentation file from the local source tree on disk, not |
| 54 | from the any check-in. The "<b>ckout</b>" keyword |
| 55 | only works when you start your server using the |
| 56 | "[/help?cmd=server|fossil server]" or "[/help?cmd=ui|fossil ui]" |
| 57 | commands. The "/doc/ckout" URL is intended to show a preview of |
| 58 | the documentation you are currently editing but have not yet you checked in. |
| 59 | |
| 60 | Finally, the <i><filename></i> element of the URL is the |
| 61 | pathname of the documentation file relative to the root of the source |
| 62 | tree. |
| 63 | |
| 64 | The mimetype (and thus the rendering) of documentation files is |
| 65 |
| --- www/embeddeddoc.wiki | |
| +++ www/embeddeddoc.wiki | |
| @@ -41,24 +41,36 @@ | |
| 41 | [https://www.fossil-scm.org/fossil]. |
| 42 | If you launch the web server using the "[/help?cmd=ui|fossil ui]" command line, |
| 43 | then the <i><baseurl></i> is usually |
| 44 | <b>http://localhost:8080/</b>. |
| 45 | |
| 46 | The <i><version></i> is the |
| 47 | [./checkin_names.wiki|name of a check-in] |
| 48 | that contains the embedded document. This might be a hash prefix for |
| 49 | the check-in, or it might be the name of a branch or tag, or it might |
| 50 | be a timestamp. See the prior link |
| 51 | for more possibilities and examples. |
| 52 | |
| 53 | <a id="ckout"></a>The <i><version></i> can |
| 54 | also be the special identifier "<b>ckout</b>". |
| 55 | The "<b>ckout</b>" keywords means to |
| 56 | pull the documentation file from the local source tree on disk, not |
| 57 | from the any check-in. The "<b>ckout</b>" keyword |
| 58 | only works when you start your server using the |
| 59 | "[/help?cmd=server|fossil server]" or "[/help?cmd=ui|fossil ui]" |
| 60 | commands. The "/doc/ckout" URL is intended to show a preview of |
| 61 | the documentation you are currently editing but have not yet you checked in. |
| 62 | |
| 63 | The original designed purpose of the "ckout" feature is to allow the |
| 64 | user to preview local changes to documentation before committing the |
| 65 | change. This is an important facility, since unlike other document |
| 66 | languages like HTML, there is still a lot of variation among rendering |
| 67 | engines for Fossil's markup languages, Markdown and Fossil Wiki. Your |
| 68 | changes may look fine in your whizzy GUI Markdown editor, but what |
| 69 | actually matters is how <i>Fossil</i> will interpret your Markdown text. |
| 70 | Therefore, you should always preview your edits before committing them. |
| 71 | |
| 72 | Finally, the <i><filename></i> element of the URL is the |
| 73 | pathname of the documentation file relative to the root of the source |
| 74 | tree. |
| 75 | |
| 76 | The mimetype (and thus the rendering) of documentation files is |
| 77 |