Today I was invited to give a talk via Zoom on Fossil. The particulars have not in any way been nailed down; for example when it will happen, who will be attending, how long the presentation should go, if anything specific needs to be discussed, if there will be multiple sessions, or if I can record and republish. The person who asked me said he will try to talk his employer into adding me to the schedule, since they apparently have weekly enrichment sessions featuring invited presenters. At this point there are no guarantees of anything.

I'd like the presentation to be a screencast showing my Linux environment as I do various tasks, though if technology is not my ally, I can also just talk and paste URLs and commands into a chat log. (That's a real possibility given my poor upload speeds at home.)

Here is a huge yet very rough list of ideas I have for things to discuss. What I actually talk about will be subject to time restrictions and the input of the person who invited this talk.

Part 1

After introducing Fossil, I first want to motivate the audience using flashy web interface stuff. As exciting as the command line may be to me, starting there makes for a tougher sell. (Though I'm told that the git command line is loathed, so maybe Fossil's cleaner commands are exciting after all.)

• Introduction to Fossil
  • What is it? (Software configuration management)
  • Why does it exist? (Manage development of SQLite)
  • What else is it good for? (Manage your own projects, details to come)
  • What sets it apart? (Clear data model, easy deployment, philosophy of permanence, flexible sync'ing)
• Tour a few timelines
  • Look at the SQLite timeline (Show off most critical role)
  • Look at the Fossil timeline (Proof of dogfood, somewhat more easygoing project structure)
  • Look at the Pikchr timeline (Very simple project structure)
  • Look at the Tcl timeline (Elaborate project structure)
• Explore more of the web interface
  • Browse the Fossil web documentation (Key to self-sufficiency)
  • Browse the Fossil source tree
  • Browse the Fossil forum
  • Browse the SQLite ticket tracker
  • Browse the Fossil wiki
  • Browse the Fossil activity reports
  • Look at diffs and annotated diffs (Including reverse annotation)
• Hosting options
  • Local, single-user project (Local filesystem, beware of NFS)
  • Intranet hosting (SSH, HTTP, HTTPS, SSH)
  • Internet hosting (Standalone, CGI, SCGI, socket listener)
  • Chiselapp (Free public hosting, access controls, private repos)

Part 2

Now that the audience hopefully wants to give Fossil a spin, it's time to actually walk them through exactly that. Here begins usage of the command line.

• Getting Fossil
  • Download ready-made binaries (Show off unversioned feature)
  • Download source snapshot (Show off tarball generation)
  • Compile and install (Single-file deployment)
• First steps
  • Clone an existing repository (Fossil itself would be a good choice)
  • Create a new repository
  • Open a repository (Also mention "fossil open"'s ability to clone)
  • Add files
  • Commit
  • Modify files
  • Show changes
  • Delete files
  • Rename files
  • Change metadata (Executable and symlink)
• Advanced tasks
  • Undo/redo
  • Bisection
  • Stashing
  • Merging
  • Amendments (Comment, author, date, branch, cancellation)
  • Branches (Creating, merging, integrating, forking, closing, reopening, hiding, coloring, private, publishing)
  • Symbolic tags
  • Wiki for check-ins, branches, and tags
  • Shunning
  • Nested checkouts
  • Versioned settings
  • Ignore/binary/CRLF/encoding globs
  • Clean/keep globs (I don't use these)
  • Operations on "all" repositories and checkouts
  • Embedded documentation
  • Tar/zip/SQLAR
• Web-based configuration
  • Basic project settings
  • Access controls
  • Skins
  • Ticket system
  • Wiki and interwiki

Part 3

If I can get this far, I'd like to talk about using Fossil to actually manage projects. I'll just list a few things here for now but have no expectation that it'll actually matter for now.

• Branch policies
  • Stability thresholds (Expectations for each branch)
  • Activity branches (Mandatory or optional)
  • Upstream merges (Prerequisites for doing so, e.g. successful peer review)
  • Release/maintenance branches
  • Program/customer branches
  • Integration branches
  • Traceability (Customer/derived requirements, billing/work package, discrepancy report, possibility of many-to-many, Fossil tickets)
  • Rework policy (How to deal with rework after having merged upstream)
• Tag policies
  • Release numbering
  • Export/import markers
• Documentation
  • Embedded documentation
  • Wiki
  • Source code comments (Literate programming)
  • Check-in comments
  • Wiki pages for check-ins, branches, and tags

Part 4

Should I actually have time for all of the above (highly unlikely), it would be good also to get into the technical side of Fossil. In my opinion, the fact that Fossil remains simple enough to understand despite its extensive functionality is one of the major things that sets it apart from the crowd.

• Data model
  • SHA3-256 (Also history of SHA-1 and hardened SHA-1)
  • Artifacts
  • Files
  • Manifests
  • Blockchain (Tamper-proof artifact record)
  • Tree structure
  • Structural artifacts
  • Baseline/delta manifests (Avoid)
• Database architecture
  • Delta compression (Don't worry about making small changes to large artifacts such as manifests)
  • Repository database (Stores and indexes artifacts)
  • Checkout database (Stores checkout data such as changes and stash)
  • User database (Stores global settings and list of all repositories)
• Fossil source code
  • Style (Indenting, intra-line spacing, variable naming, commenting)
  • Extensions to C (Header generation, "@" lines, command/web page dispatch, documentation generation from comments, static code safety checks)
  • Memory leak policy (Time spent managing memory is often time not spent writing useful code, so let the OS be your garbage collector)
  • Child process policy (Get in and get out fast)
  • Difficulty integrating as a library (Consequence of the above)
  • Use of SQLite
  • Use of TH1
  • Contributor agreement

Part X

As much as I list above, there's so much more that can be discussed. Here are a few things I'm thinking of.

• Tcl integration
• JSON
• Pikchr
• Hooks
• Email
• Login groups
• Direct usage of SQL
• Debugging techniques
  • configure CFLAGS="-O0 -ggdb3"
  • -sqltrace
  • -httptrace
  • gdb args http < httplog_XXX.txt
• RSS
• Vim integration
• Full-text search
• Reparenting
• SCM integration
  • git
  • Subversion
  • Other
• Comparison with other SCM systems
  • CVS and CVSTrac
  • Subversion
  • Monotone
  • git
• FUSE
• Using Fossil to manage /etc
• Bundles
• Synchronization across air-gapped networks
• Parent projects and repository forking
• Caching
• Use cases for nested repositories
• Use cases for unversioned files
• Integrating Fossil with a build system
• Integrating Fossil with application code
• Security considerations
• /fileedit

Closing thoughts

This isn't so much closing thoughts about my talk but rather about this forum post.

I highly doubt I'll actually be able to cover even a fraction of what I listed out above, so it's more a brainstorm from which I can select items worth talking about. Suppose I'm given only fifteen minutes. I won't be spending that time talking about all the different types of cards in a forum post artifact. Rather I'd pick a few things from Parts 1 and 2, e.g. introduce Fossil, show the web interface a bit, then do some basic commands.

The notion of "if given unlimited time" is an interesting one, since a serious exploration of that particular hypothetical eventually results in writing a book. I might just do that someday, with the above being the first sketch of what the table of contents might look like.

See also: my write-up of Fossil for SlackBuilds.

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.

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.

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

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.

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?

I too am willing to help.

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.

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