Here is a sample WDF document that contains the (latest snapshot) of the SQLite documentation:

1. Download https://sqlite.org/tmp/sqlite-docs-20200407.wdf (16MB)
2. Run "fossil ui sqlite-docs-20200407.wdf"

Nice idea! Doesn't require pandoc or extra tools, but it would require Fossil and a web browser.

If you had not provided the wdf file, what steps are needed to make it?

Is it basically the .fossil of the repo with this new extension?

If you had not provided the wdf file, what steps are needed to make it?

Steps 1-4 in Richard's initial post

Is it basically the .fossil of the repo with this new extension?

Yes, for some value of "basically". Some tools or other non-viewable stuff would be left out.

Steps 1-7 in Richard's initial post

Well in the case of the sqlite documentation, I wouldn't create a new repo - I'd clone an existing repo.

This feels to me to be running in the same space as various ebook formats.

Notably E-PUB. The link goes to the implementation section on the wikipedia page.

The description there is quite similar to what you wrote here.

It might be worthwhile to get a variety of .epub's and look at their structure (They are just zip files with html, other assets, and meta data in XML).

Because it took some non-trivial time (for me) to interpret this step,

`6. Make whatever style adjustments seem appropriate.

, I offer this experience to guide that "seems appropriate" state of mind:

If

  <somePath>/index.html

, as added to the repository and committed, is going to become the initial page served up by 'fossil ui' (or 'fossil server <somedoc.wdf>'), then in fossil's web ui, navigate to Admin / Configuration , and set the Index Page item to

  /doc/trunk/<somePath>/index.html

.

Any other stylistic adjustments that seem appropriate, or setting project names, etc. as Fossil docs and books suggest, may also be done.

This seems like a pretty useful idea and is similar to what we are using for our Coronapedia, because we need a self contained documentation repository. In our approach we packaged Markdeep and Font Awesome as part of the repository.

The clickable WDF file launching a local server is a good idea, for "end users" of such documentation. It would become almost download and click. It also has advantages over alternative approaches like EPUB, particularly build in collaboration and versioning.

You may consider some issues:

1. What happens if the repository includes unversioned files (raw images, PDF's and so on)? With this idea of simplicity in mind (download and run), wouldn't be good to provide a way to package such files in the repository? (as discussed in other thread and addressing the different namespaces raised there)

2. Could Fossil package itself and/or can we have a WDF player (like Wolfram/Mathematica player)? I think that this is already reaching the extension capabilities mentioned in the unversioned files thread, and this maybe something not really needed, as we have now one line installers for Fossil in most common platforms, but for non technical people, installing Fossil can be tricky. I imagine something like the a way to package Fossil and the WDF in the same file, so people can download and click/launch, according to their platform. Other approach would be to distribute something like the Wolfram Player, that allows to read documents in the Computable Document Format. The advantage is that such player is just the Fossil binary in a click and install/run format.

3. Could we have some config (yaml, toml, json) file for the WDF repository? So we could do something like fossil new mydoc.wdf from config.yaml that essentially would tell which directory to use, the default file to be used as the document "landing page", the repository title and description, if search is enabled by default and so on. This file could be part of the repository, internalizing the setup options that usually are defined via command shell for an easier setup and increased reproducibility (we make something like this in a special node inside Grafoscopio notebooks).

This could have important impacts for reproducible research and publishing. I use Fossil mostly for documentation (software source code is in SmalltalkHub and soon unfortunately on Git :-/ ) and I made a prototype of how to use Fossil to version interactive notebooks about the [Panama Papers as reproducible research]. The WDF would automatize this greatly and improve the overall user experience.

I really like this idea. I think it could be a great contender as an alternative for simple (and maybe even not so simple) Word/OpenOffice docs - but much easier to edit and of course having history tracking, and even tickets etc.

I envision something like:

1. double click the 'doc.wdf' file
   • the contents are checked out to folder named 'doc' along side the file
   • fossil ui is launched and browser opened to the main page
2. make changes to the .md or .html etc files using whatever editor
3. refresh the browser (maybe it can auto refresh on changes?)
4. provide a 'Commit' button on the page or a simple shell/bat 'commit' script which will commit all changes with a 'wip' message or just the date.
   • the web ui could provide a box to enter the commit message
   • the button or script means (on Windows especially) super simple, easy and quick updates without opening terminals, navigating to the folder, and typing the commands (especially for non-technical folks).
5. another button/script to push/pull the changes to/from the source (the URL of which could be stored in a file within the repo).

the fossil scripts could be generated by fossil, further reducing the technical load on document writers.