Fossil SCM
Added "Embedded Documentation" section to the glossary per larrybr's request in /chat. It's a Fossil-specific term of art. It also gives us a place to contrast with the wiki; that could live in the docs for the wiki or embedded docs instead, but the glossary is where newbies go to get oriented on terms, so the "but which should I use" question falls right out of the terminology.
Commit
e583b48a0453c6a062aceba88648313b7dbed6dbea62591587304ff0e331fc88
Parent
834db57d95f6e16…
1 file changed
+73
+73
| --- www/glossary.md | ||
| +++ www/glossary.md | ||
| @@ -298,7 +298,80 @@ | ||
| 298 | 298 | [h2cflp]: https://www.sqlite.org/howtocorrupt.html#_file_locking_problems |
| 299 | 299 | [fpvsc]: https://marketplace.visualstudio.com/items?itemName=koog1000.fossil |
| 300 | 300 | [open]: /help?cmd=open |
| 301 | 301 | [mwd]: ./ckout-workflows.md#mcw |
| 302 | 302 | [update]: /help?cmd=update |
| 303 | + | |
| 304 | + | |
| 305 | +## <a id="docs"></a>Embedded Documentation | |
| 306 | + | |
| 307 | +Serving as an alternative to Fossil’s built-in [wiki], the [embedded | |
| 308 | +documentation feature][edoc] stores the same type of marked-up text | |
| 309 | +files, but under Fossil’s powerful version control features. | |
| 310 | + | |
| 311 | +* The simple rule for determining whether to use the wiki or embedded | |
| 312 | + docs for any given document is whether the content is considered | |
| 313 | + “evergreen,” as with a Wikipedia article. | |
| 314 | + | |
| 315 | + While Fossil’s wiki feature does store the history of each | |
| 316 | + document’s changes, Fossil always presents the current version of | |
| 317 | + the document unless you manually go out of your way to dig back into | |
| 318 | + the history. Then, having done so, links from that historical | |
| 319 | + version of the wiki document take you to the current versions of the | |
| 320 | + target documents, not to the version contemporaneous with the source | |
| 321 | + document. | |
| 322 | + | |
| 323 | + The consequence is that if say something like… | |
| 324 | + | |
| 325 | + $ fossil up 2020-04-01 | |
| 326 | + $ fossil ui | |
| 327 | + | |
| 328 | + …you will **not** see the wiki as of April Fool’s Day in 2020. | |
| 329 | + You’ll see the current wiki article versions, same as if you ran it | |
| 330 | + from a check-out of the tip-of-trunk. | |
| 331 | + | |
| 332 | + Contrast embedded docs, which are not only version-controlled as | |
| 333 | + normal files are in Fossil, they participate in all the tagging, | |
| 334 | + branching, and other versioning features. There are several | |
| 335 | + consequences of this, such as that Fossil’s [special check-in | |
| 336 | + names][ciname] work with embedded doc URLs: | |
| 337 | + | |
| 338 | + * <p>If you visit an embedded doc as `/doc/release/file.md` and | |
| 339 | + then click on a relative link from that document, you will remain on | |
| 340 | + the release branch. This lets you see not only the release | |
| 341 | + version of a software project but also the documentation as of | |
| 342 | + that release.</p> | |
| 343 | + | |
| 344 | + * <p>If you visit `/doc/2020-04-01/file.md`, you will not only | |
| 345 | + pull up the version of `file.md` as of that date, relative links | |
| 346 | + will take you to contemporaneous versions of those embedded docs | |
| 347 | + as well.</p> | |
| 348 | + | |
| 349 | + * <p>If you say `fossil up 2020-04-01 && fossil ui` and then visit | |
| 350 | + `/doc/ckout/file.md`, you’ll not only see the checked-out | |
| 351 | + version of the file as of that date, relative links will show | |
| 352 | + you other files within that checkout.</p> | |
| 353 | + | |
| 354 | +* Fossil’s wiki presents a flat list of articles, while embedded docs | |
| 355 | + are stored in the repository’s file hierarchy, a powerful | |
| 356 | + organizational tool well-suited to complicated documentation. | |
| 357 | + | |
| 358 | +* Your repository’s Home page is a good candidate for the wiki, as is | |
| 359 | + documentation meant for use only with the current version of the | |
| 360 | + repository’s contents. | |
| 361 | + | |
| 362 | +* If you are at all uncertain whether to use the wiki or the embedded | |
| 363 | + documentation feature, prefer the latter, since it is more powerful | |
| 364 | + and, with the addition of the [`/fileedit` feature][fef] in Fossil | |
| 365 | + 2.12, it’s nearly as easy to use. | |
| 366 | + | |
| 367 | + (This very file is embedded documentation: clone | |
| 368 | + [Fossil’s self-hosting repository][fshr] and you will find it as | |
| 369 | + `www/glossary.md`.) | |
| 370 | + | |
| 371 | +[edoc]: ./embeddeddoc.wiki | |
| 372 | +[fef]: ./fileedit-page.md | |
| 373 | +[fshr]: ./selfhost.wiki | |
| 374 | +[wiki]: ./wikitheory.wiki | |
| 375 | + | |
| 303 | 376 | |
| 304 | 377 | <div style="height:50em" id="this-space-intentionally-left-blank"></div> |
| 305 | 378 |
| --- www/glossary.md | |
| +++ www/glossary.md | |
| @@ -298,7 +298,80 @@ | |
| 298 | [h2cflp]: https://www.sqlite.org/howtocorrupt.html#_file_locking_problems |
| 299 | [fpvsc]: https://marketplace.visualstudio.com/items?itemName=koog1000.fossil |
| 300 | [open]: /help?cmd=open |
| 301 | [mwd]: ./ckout-workflows.md#mcw |
| 302 | [update]: /help?cmd=update |
| 303 | |
| 304 | <div style="height:50em" id="this-space-intentionally-left-blank"></div> |
| 305 |
| --- www/glossary.md | |
| +++ www/glossary.md | |
| @@ -298,7 +298,80 @@ | |
| 298 | [h2cflp]: https://www.sqlite.org/howtocorrupt.html#_file_locking_problems |
| 299 | [fpvsc]: https://marketplace.visualstudio.com/items?itemName=koog1000.fossil |
| 300 | [open]: /help?cmd=open |
| 301 | [mwd]: ./ckout-workflows.md#mcw |
| 302 | [update]: /help?cmd=update |
| 303 | |
| 304 | |
| 305 | ## <a id="docs"></a>Embedded Documentation |
| 306 | |
| 307 | Serving as an alternative to Fossil’s built-in [wiki], the [embedded |
| 308 | documentation feature][edoc] stores the same type of marked-up text |
| 309 | files, but under Fossil’s powerful version control features. |
| 310 | |
| 311 | * The simple rule for determining whether to use the wiki or embedded |
| 312 | docs for any given document is whether the content is considered |
| 313 | “evergreen,” as with a Wikipedia article. |
| 314 | |
| 315 | While Fossil’s wiki feature does store the history of each |
| 316 | document’s changes, Fossil always presents the current version of |
| 317 | the document unless you manually go out of your way to dig back into |
| 318 | the history. Then, having done so, links from that historical |
| 319 | version of the wiki document take you to the current versions of the |
| 320 | target documents, not to the version contemporaneous with the source |
| 321 | document. |
| 322 | |
| 323 | The consequence is that if say something like… |
| 324 | |
| 325 | $ fossil up 2020-04-01 |
| 326 | $ fossil ui |
| 327 | |
| 328 | …you will **not** see the wiki as of April Fool’s Day in 2020. |
| 329 | You’ll see the current wiki article versions, same as if you ran it |
| 330 | from a check-out of the tip-of-trunk. |
| 331 | |
| 332 | Contrast embedded docs, which are not only version-controlled as |
| 333 | normal files are in Fossil, they participate in all the tagging, |
| 334 | branching, and other versioning features. There are several |
| 335 | consequences of this, such as that Fossil’s [special check-in |
| 336 | names][ciname] work with embedded doc URLs: |
| 337 | |
| 338 | * <p>If you visit an embedded doc as `/doc/release/file.md` and |
| 339 | then click on a relative link from that document, you will remain on |
| 340 | the release branch. This lets you see not only the release |
| 341 | version of a software project but also the documentation as of |
| 342 | that release.</p> |
| 343 | |
| 344 | * <p>If you visit `/doc/2020-04-01/file.md`, you will not only |
| 345 | pull up the version of `file.md` as of that date, relative links |
| 346 | will take you to contemporaneous versions of those embedded docs |
| 347 | as well.</p> |
| 348 | |
| 349 | * <p>If you say `fossil up 2020-04-01 && fossil ui` and then visit |
| 350 | `/doc/ckout/file.md`, you’ll not only see the checked-out |
| 351 | version of the file as of that date, relative links will show |
| 352 | you other files within that checkout.</p> |
| 353 | |
| 354 | * Fossil’s wiki presents a flat list of articles, while embedded docs |
| 355 | are stored in the repository’s file hierarchy, a powerful |
| 356 | organizational tool well-suited to complicated documentation. |
| 357 | |
| 358 | * Your repository’s Home page is a good candidate for the wiki, as is |
| 359 | documentation meant for use only with the current version of the |
| 360 | repository’s contents. |
| 361 | |
| 362 | * If you are at all uncertain whether to use the wiki or the embedded |
| 363 | documentation feature, prefer the latter, since it is more powerful |
| 364 | and, with the addition of the [`/fileedit` feature][fef] in Fossil |
| 365 | 2.12, it’s nearly as easy to use. |
| 366 | |
| 367 | (This very file is embedded documentation: clone |
| 368 | [Fossil’s self-hosting repository][fshr] and you will find it as |
| 369 | `www/glossary.md`.) |
| 370 | |
| 371 | [edoc]: ./embeddeddoc.wiki |
| 372 | [fef]: ./fileedit-page.md |
| 373 | [fshr]: ./selfhost.wiki |
| 374 | [wiki]: ./wikitheory.wiki |
| 375 | |
| 376 | |
| 377 | <div style="height:50em" id="this-space-intentionally-left-blank"></div> |
| 378 |