I highly doubt I'll actually be able to cover even a fraction of what I listed out above,

Holy cow, that's a heck of a list. My own use of fossil is so limited in scope that i often forget how much it can do.

O'Reilly's awaiting your book proposal. Fossil in a Nutshell might be the first of their books for which a long-deceased animal would be appropriate on the cover.

Stephen said: "Holy cow, that's a heck of a list."

It certainly is! All very worthwhile topics.

I provide technical support for a corporate e-learning system. I wrote it many years ago and redeveloped it this year. I am not involved in the pedagogical side of things, but what I hear from that side of the business is that short doses of education are better than long ones. We have courses of duration about one hour that are broken into 4 to 6 modules, each of which is started separately and all can be interrupted and restarted.

Your list is so long that I can not imagine it fitting in a single session. While an O'Reilly book might be in the future, I think your current target audience would be better served by a series of progressive presentations.

If you are able to record the presentations then Youtube or some such platform is calling and a series would be suitable there too.

Chris

Andy, follow the KISS principles and think about "less is more" ...

I think you should focus on use-cases and principles and not the technical side (except your audience are fossil users already).

Diversification from other similar available software, use cases:

• distributed version control for software sources and configurations
• delta-compression for lossless long life conservation
• block-chained content protection
• self-contained with wiki documentation, forum, ticket system and notifications (with markup formatting even of simple graphics)
• TechNotes with attachments

Also to mention where it is not (yet) for:

• Huge projects like OpenBSD in Git style
• branch sliced development style (as usual with Git)
• rebase and polishing after commit and sync

Technology specifics:

• web based (timeline as project tracker)
• command-line usage (analogy with other systems like SVN, Git, Mercurial)
• security concept (against alterations and web attacks)
• multiple checkouts simultaneously
• single file distributed, no dependencies, self-contained

Outlook for next enhancements:

• hooks for automation and CI/CD purposes

If you count my bullet points and if you spend 1 min per point then you will just make it in a quarter of an hour. Audience concentration lasts for approximately 20 min, so you will be fine to plan 15 and do 20 min.

The person who invited my talk reviewed this thread and says he will be working with his management team to figure out what topics they most want discussed. This brainstorming session was useful to outline the general shape of the possible universe of discourse. Thank you to all who chipped in, and please continue to do so.

One thing he already suggested was more comparison with git and GitHub with some details about ways in which Fossil comes out on top. He also said to not make it be a sales pitch but rather to slyly allow the facts to speak for themselves. I further think I shouldn't go out of my way to do so but to have any such discussion be in service to another, more practical exercise. Show, don't tell.

Good points to cover, provided your audience can absorb it all in the time you've allotted. Personally I would focus on how people can download it and use it. Maybe setup a mock repo that resembles some commits and branching your viewers are likely to experience. Then you can explain how to clone it and start it up. I imagine the talk/discussion will be didactic and not just a conceptual, so have them get their hands dirty.

You might find something useful from drh's talk on FLOSS weekly from FIVE YEARS AGO. There's also some talks he's given elsewhere that are available on youtube.

Wow, that was a quick five years for me.

What sets it apart?

It might be good to re-read the Fossil vs Git article to refresh your mind on the pluses and minuses. I doubt it'll teach you anything you didn't know, but it's a compendium of arguments that you might not have immediately at hand in the crunch if you haven't reviewed it recently.

Tour a few timelines

Maybe also show some corresponding GitHub timelines, to show how impoverished the conversion is.

Beware that some viewers will see this as an improvement, a simplification, if you don't take care to show what you can't find out from these timelines, which Fossil makes explicit or easily retrieved.

Browse the Fossil web documentation (Key to self-sufficiency)

I don't think I'd do more than point them at the Quick Start guide and then at the doc index.

The Fossil docs aren't what I'd call "browseable," not in the way of, say, Wikipedia, where you may easily emerge 2 hours and 23 links away from where you started. Fossil's web docs are largely disconnected, with no clear path from one to the other except through the too-sparse explicit interlinks.

This is the main reason I mourn the obsolescence of the Shimpf book.

Yet, although I'm in a pretty good position to solve that problem, either within Fossil's existing structure, by resurrecting the Schimpf book, or by adding a third work above both, I struggle to see that it's a good use of my time. The fact is, many people expect to do web searches to pull up the pieces of info they need immediately — else why is this funny? — or to fire off support messages to get someone else to do the Googling for them.

If there was a new Fossil book, I think it'd be praised by a few illuminati and then largely ignored.

Bottom line, go to where your audience is, rather than try to drag them to where you want them to be.

Explore more of the web interface

If you just take them on a feature-list whirlwind tour, your viewers will likely end up dizzy. They may remember that some of this exists when they need it later, but it's better to anchor that to a purposeful task-oriented example. For instance:

1. Start with a forum post from a clueless newbie who didn't provide nearly enough info to go on.

2. Follow the thread down to the point where the maintainers arm-twist the user into filing a sane ticket. Show the interlink between forum and tickets.

3. Visit the ticket, the initial comment of which doubtless lacks enough info to properly diagnose the problem. Show the further back-and-forth in the ticket comments.

4. Show the developer's bisect process, pulling up the bug cause quickly.

5. Show the link to the resulting fossil bisect ui output, linked from the comment closing the ticket, which also links to a commit ID.

6. Go back and follow the commit ID link to show the fix's diff and the commit comment with the struck-through ticket ID.

7. Point out that Fossil shows the next commit after the breakage point, not just the prior. Git can't do that.

8. Point out that the commit's /info page links to the ticket not just through the comment reference but also in the References section. Explain how this improves situational awareness.

I tried to dig up such a thing, but none of the public Fossil repos I'm aware of have an example of this. There may be partial examples of this in the Fossil and SQLite projects, but the problem there is that because the forum is disconnected from the code repo and tickets are either never used or only used by developers, you are missing big elements of my example above.

If you don't have such a thing in one of your repos that you're willing to show, it might be worth constructing a demo for the purpose. I assume you can draw from years of painful experience to produce a suitably convincing exchange, which will draw sympathy from your audience, who have also had such interactions.

Show how Fossil addresses the audience members' pain points.

Hosting options

I'd stop at the /server doc index page, scrolling down to the grid of options for your audience to contemplate as you quickly run through the options.

Your biggest danger here is people coming away thinking it's all too complicated to mess with. Remember that your competition here is GitHub. Try to spin it as "options" rather than "complexity."

Present four simple configurations:

1. Local-only operation through a shared repo. Show that you still use "clone" in this case to avoid locking problems with two local users trying to commit to the same DB overlapping, or with "fossil serve" locking up the UI so it can't be committed to without retries.

2. Remote via SSH. Same as #1, just with a different clone URL.

3. "fossil server" on a fixed custom port.

   There's a faction here that will tell you CGI's easier, but I don't buy it. If you do, however, you should do it "cooking show" style: have the Fossil CGI script already written and just drop it into place within an already set up HTTP server's CGI root, then reload the browser, showing the "fresh from the oven" result.

4. Show off the new "fossil remote" feature to combine #2 and #3. I assume every one of your audience currently has a problem in this time of COVID-19: how to work from home some of the time while still having off-machine backups, and then how to sync it all up occasionally.

   Show how you can give a "fossil remote home" command before working at home, syncing with a local SSH server, then "fossil remote work" to push to the big web server in the office to offload remote work occasionally.

   Alternately, show local syncs to a second LAN machine for day-to-day work from home, then connect to a VPN/SSH tunnel and do an end-of-day sync to the office over a different protocol.

Compile and install

I'd do that in terms of a Fossil clone rather than a tarball. Show that "fossil ui" from the repo dir gives you a complete-ish clone of fossil-scm.org/fossil. (Minus the forum and other things outside the repo.)

Have the source already compiled and ready to install. You might dare to do a "fossil up && make -j11" to do a quick update, if you've got a machine that will do that quickly enough.

Single-file deployment

As always, show, don't tell: say "make install" and point out that it's basically a one-liner: cp fossil $PREFIX/bin (It's actually 2 lines: it does a mkdir first, just in case.)

Also mention "fossil open"'s ability to clone

Again, show rather than tell. Take them through the full detailed clone, mkdir, open, mkdir, open... dance to get multiple checkouts of a given repo, but then show off the simple case where only a single checkout dir is needed. Then go back to the multiple checkouts method to show off why this is a better option if your use cases are at all complicated.

Placate the Git-ites, but show them the path to the holy land.

Amendments (Comment, author, date, branch, cancellation)

Both from the UI and from the command line. Different people engage with this one differently. Some view the UI as simpler and better, while others see the UI amendment feature as confusing because it doesn't map 1:1 to the view given in the branching doc.

Advanced tasks

I wouldn't call all of your list "advanced", and I'd reorder what you do have considerably, putting more common things first:

Intermediate Tasks:

• Merging
• Branches & tags
• Wiki for check-ins, branches, and tags
• Construct /tarball and /zip links in the wiki "Home" article
• Embedded documentation as alternative to wiki
• Stashing
• Bisection
• Undo/redo

Advanced Tasks:

• Settings: repo-local, machine-global, and versioned
• Amendments
• Nested checkouts

Rarely-Done Tasks:

• Shunning

I'd cover "fossil all" much earlier, as part of your initial tour, if only by running a "fossil all sync" early on, getting everything up to date while you talk about other things.

I wouldn't talk about SQLar at all. It's neat, but it's the sort of thing you learn about 6 months into your Fossil journey, not 1 hour in.

Versioned settings

Be sure to use either a stable and well tested older version of Fossil or tip-of-trunk. There's been some breakage in this area recently, and you don't want to stumble over it in mid-presentation because you're on a version from last month or similar.

Wiki and interwiki

Basic wiki use should be part of First Steps, as it is part of setting up a repo, since the stock Fossil config redirects / to a Home wiki article by default. Write that article. Show off /wikiedit in terms of an established project, where features like wiki list and diff take effect.

I'm not sure I'd talk about interwiki at all. It solves a problem most Fossil users won't have, at least for many months after first starting to use it.

Part 4

Nuke this entirely. What you're proposing here is a longtime Fossil user brain-dump. Until your audience has used Fossil for a year or so, they'll simply be leaning on you for this stuff. At the end of that time, you can start taking some of your most engaged students through some of this. This is absolutely not something to show on day 1.

If some of it comes up in Q&A, fine, but I'd consider the presentation a success if none of it came up at all.

It's also fine to touch on some of this in passing in earlier parts of the presentation. Just rein in the temptation to give a brain dump. That'll baffle most of your audience with detail far too abstruse to matter to them on day 1.

Tcl integration

I don't see that feature as being in any kind of shape to be treated as a show-off feature. I'd expect more "You have to do what?" reactions than "Wow, that's really cool!"

Instead, show:

• TH1 skin adjustments (e.g. cause buttons to appear under different conditions)
• Ticket customizations, if only to the Common section's Tcl lists
• Hooks: CI/CD, static analysis nannying...

JSON

Only if you can "cooking show" the demo. This one's likely to get down into the weeds quickly otherwise.

Pikchr

I'd put this much higher up the list. Maybe part of your wiki demo. Every software team can benefit from quick and easy diagrams.

Email

I'd mention that in passing in two places:

1. When talking about what happens as part of a commit. Mention that you can configure Fossil to send out email alerts when this happens.

2. When talking about the forum.

Unless you're going to give them a glimpse at working config, which means opening the kimono to Admin access, I wouldn't go into any details. It's fairly involved to set this up, and it has steep prereqs. (i.e. Having Postfix already set up and working, having a public DNS setup, having DKIM working...)

Debugging techniques

This goes into the Part 4 brain dump bucket. It's for you to know as an expert, not for you to baffle newbies with.

SCM integration...git...Subversion

I wouldn't show anything more than GitHub export here, today.

If this were 2012, and CVS and Subversion were still widely in use, then fine, but by now, it's all "Git, plus everything else."

If an audience member asks about other cases, or if you know for a fact that your audience uses something other than Git now, fine, go into that. Otherwise, leave it in the dustbin of history.

Using Fossil to manage /etc

I thought that was generally a bad idea, due to Fossil's inability to version file and directory permissions. How does this not result in "find /etc -type -f chmod -R 600 {} \;"?

I'm aware that there are good answers to that question, but then there's a new question: are you demoing your alternative to etckeeper, or demoing Fossil?

/fileedit

I'd be tempted to cover that much earlier, as part of /wikiedit and embedded documentation.

This is the main reason I mourn the obsolescence of the Shimpf book.

Yet, although I'm in a pretty good position to solve that problem, either within Fossil's existing structure, by resurrecting the Schimpf book, or by adding a third work above both, I struggle to see that it's a good use of my time. The fact is, many people expect to do web searches to pull up the pieces of info they need immediately — else why is this funny? — or to fire off support messages to get someone else to do the Googling for them.

If there was a new Fossil book, I think it'd be praised by a few illuminati and then largely ignored.

I learned fossil from the Schimpf book and have taught others from it as well. I even have a copy of the repo with some fixes in it.

So I for one would greatly appreciate an updated copy of this.

Having a book with examples and a path with best practices for development using fossil I think is more important than you state. Also maybe a companion fossil repo that encompasses the "purposeful task-oriented example" you mention above that can be used as a companion to the book.

John, did you just volunteer to help bring the Schimpf book up-to-date? Because that's what I heard you saying. :-)

How can I assist you with this task? Would it help to have a video-chat (perhaps with some of the other key developers) to go over a plan-of-action for getting the book updated?

Richard can you drop me an email at the address on the forum and we can discuss offline first.

Richard Hipp (drh) on 2020-09-28 20:27:04:

John, did you just volunteer to help bring the Schimpf book up-to-date? Because that's what I heard you saying. :-)

I pulled the Schimpf book sources to review (as a consumer, I hasten to add) and quickly decided it needed updated and then got an impression of just how much work this would be ("a lot" :). But I am certainly up for contributing patches from my own notes if someone else was doing the heavy lifting.

In a separate thought, the Schimpf book 2nd edition is written in LaTeX. Perhaps now in 2020 it is worth considering whether Schimpf 3rd edition should be done in Pandoc Markdown, which is intended for books. But if Pandoc Markdown, why not Fossil Markdown over time? Then the Fossil book could be self-hosting. This is a speculative comment, not a "here's a patch" comment :-)

Dan

I ended up in the same boat. There are some patches in the trunk branch that aren't needed in the v2 branch (formatting changes unique to LyX??), but there are also some text changes that I committed to the V2 tree in my repo.

I am not in a position to do a lot of heavy lifting so we would need a few more people to help out. I still think a book format is better for learning. It is too easy to end up with holes in your knowledge when you flit between wiki pages compared with reading a book cover to cover.

This could be handled with pandoc markdown and a TOC with next links allowing the series of pages to be read serially like a book. The question is how to implement that as embedded documentation in a fossil repo.

I am willing to help, but we need a larger team.

I too am willing to help.

For the second time in as many years, I downloaded the Schimpf repository; this time to understand what is needed for an update to a new edition.

The repository holds a prior attempt, tagged 2ndEdition. It includes the useful splitting of fossil.lyx into multiple chapters. This would allow more independent work by a number of contributors without repeated stepping on toes.

HOWEVER, the 2ndEdition included output in Tex format in the Chapters directory. Reverting to Lyx format for these chapters was a trivial import into Lyx which had the side effect of creating the .lyx file for each before importing it.

My question is: given the obvious word processing-like features of Lyx, what are the benefits of moving to Tex or Markdown for original source documents? There is a mechanism for generating HTML, PDF, and Markdown from the Lyx source, using pandoc.

It seems to me that original source in Markdown would reduce flexibility in content and layout. Markdown is designed to simplify HTML generation not to enhance it.

Staying in Lyx, I am willing to assist, at a minimum to edit text and capture new screen images. My writing style is more stilted/formal than most so it is not clear that I should do original content creation.

I've never composed in Tex format, but I have no interest in writing that way if layout instructions must be written in addition to subject text. Been there done that in the days before WYSIWYG and don't wish to do it again. I am occupied with merged HTML tags and text content in my day job.

We could have pretty advanced layout options via Pandoc templates while keeping writing markup and tech simple. See for example the PDF we did while porting the Spanish Data Journalism Manual to our "pocket infrastructures" (which include Fossil). You can find more info about this approach in:

https://mutabit.com/repos.fossil/mapeda

Cheers,

My question is: given the obvious word processing-like features of Lyx, what are the benefits of moving to Tex or Markdown for original source documents?

As an external observer interested in having a more comprehensive and unified version of the book, I'd say that the answer depends on whether the need is to have a document which can be easily accessible for modifications by a team of people instead of a single author, or a very beautifully composed PDF file generated from any TeX-handling toolchain.

I'll add that I have tried to contact the author on my own, in the only email address that has been published (AFAIK), and I never received response. Does anyone know anything about Mr. Schimpf current whereabouts?

To me the value of shifting to Markdown is that then the book-level Fossil documentation becomes self-hosting.

I'd say that diagrams should then migrate to pikchr.

As my Fossil learning has shifted from novice to journeyman, I have struggled with finding my way through the myriad single-topic documents, and have had trouble connecting the workflow documents up to my use cases.

I think I actually began with the Schrimpf doc, but then was told by a mentor (hello Warren!) that the reason why the thing I was doing didn't work was that the Schrimpf doc was too far out of date.

I was unfamiliar with Lyx, so I glanced at the overview at lyx.org.

Funny story: At one time I was a member of the Open Software Foundation's Document Architecture Working Group. It was at the time when the ODA/ODIF was just coming out, but all the documentation we were looking at for OSF-1 and other projects was written in troff. We actually hammered out DTDs for SGML that was to be compatible with the popular troff macros's semantics (-man, -ms if memory serves). I know the value of semantic markup as espoused by Lyx, and as contrasted with Markdown which is somewhat semantic, but somewhat descriptive.

Fossil, at so many levels, has adopted Markdown as the approach to writing documentation -- in Wiki, in Forums, in README.md. In my opinion, which is informed by a fair bit of professional experience in document architecture, is that the migration to Lyx was a good decision for a book, but is a less good decision for self-hosting book-length documentation.

By way of full disclosure I will say that I have a mild preference against LaTEX and TeX as being overkill, and continue to lament the demise of Scribe.

Bottom line: I advocate for taking version 2 from Lyx into Markdown, and organizing a collaborative effort to divide and conquer the update across chapters. To this end, I'll look at what's there and see if there is a chapter I can volunteer to work on.

The weight of opinion indicates that Markdown is the format of choice.

So, at this site:

https://www.breksta.net/Book.cgi

you will find a cloned copy of:

http://www.fossil-scm.org/schimpf-book/wiki?name=clone

with the following changes:

1. a new branch has been created: 2ndEditionMarkdown

2. existing files in Chapters/*.tex were imported into Lyx to create *.lyx and the content of these files was displayed in Lyx and selected/copied/pasted into my editor then saved as Chapters/*.md

3. the *.md files have been edited lightly:

   • the chapter entry was given a two-hash prefix.
   • interior section headers were given a three-hash prefix.
   • interior sub-section headers were given a four-hash prefix.
   • unordered list prefix was changed from a non-standard bullet symbol to a plus sign, which will present as a bullet in markdown.
   • instances of the back-tick have different meanings in TH1 and Markdown so they have been prefixed by backslash in the text.

There plenty of other changes to be made by a careful editor. I encourage use of a side-by-side display with your editor and the existing .pdf to adapt the Markdown content while retaining layout as close as possible to the existing book.

The clone user with pw: clone has been retained. This user has read and clone permissions at this time.

The clone operation:

https://clone:clone@www.breksta.net/Book.cgi {your-file-name}

will work as expected but commits are disabled at the moment. See the next point.

Fossil does not have the pull request concept, so either committing users need to be added to the user list, or some patch file process needs to be adopted. I am mindful of security in a world of malicious actors but I'm open to changing this condition of use.

There is need of a guidance committee to set policy for use and contributions. I invite all interested readers who are potential committers to volunteer.

I consider this new repository to be a draft only. If the guidance committee thinks there is a better place to host it then so be it.

Other comments and suggestions are welcomed.

Chris

Fossil does not have the pull request concept, so either committing users need to be added to the user list, or some patch file process needs to be adopted.

Fossil's "bundle" concept was designed for that:

https://fossil-scm.org/fossil/help?cmd=bundle

and

https://fossil-scm.org/fossil/help?cmd=publish

The idea is that someone provides a drive-by patch using a bundle (mail attachment or cloud storage link or whatever), which a repo maintainer can import, try out, and optionally keep or discard.

I starting writing more explanation of activity but concluded we have been hijacking this topic so when I have it ready to publish then I will open another topic in the forum.

I think this topic should revert to its original discussion on the Presentation Opportunity.

Chris

Hi,

what is actually the status of this effort? The clone at brakstra.net gives me an error 500 and I cannot find a follow-up forum post of this last message. If I find the time, I would be willing to contribute.

I didn't even see that the changes obviously done on the clone, as reported in this thread, were ever fed back to the repo at fossil-scm.org. It would be a shame loosing this initial effort to write a new edition of the book!

Torsten

Ah, I hate it when I find the solution myself only a few minutes after posting ...

The cloned FossilBook repository is now here at breksta.com.

The last activity is from November 2020. So, the question (to Chris) remains. What is the status? Is there ongoing work?

Chris here.

I stopped work after converting from a single Lyx file to multiple markdown files when I realised that keeping it up to date would be very difficult with the changes that were and are happening to the Fossil code.

In addition, I concluded that the simplicity of markdown does not work well when there are lots of screenshots without ability to control where they appear in the flow of text. The existing screenshots are out of date.

Using section and paragraph numbering is not possible in plain markdown, so a CSS section heads each page. This header is not processed by Fossil for its pages.

Pandoc, latex and pdfunite are also needed to generate the pdf version.

Using pandoc to generate html files that stand alone without Fossil results in different output from that required for use within a Fossil repository.

Finally, there are editorial decisions to make about the target audience and what should be included in the documentation. For instance, the chapter on TH1 is an advanced topic that does not suit the rest of the document. It's not clear if the chapter on ChiselApp should be included.

You are most welcome to clone the repository (available to anonymous users) and continue the work in a direction you think most suitable.

Chris