This is the project that maintains the documentation for LumoSQL. LumoSQL enhances the SQLite database library without forking it.
Lumodoc is a Science Communication project, discussing the computer science, mathematics and human factors to do with LumoSQL. The software engineering project LumoSQL has created a new kind of database.
LumoSQL and any other project wanting to link to the LumoSQL docs need to point at the "doc" directory within the Lumodoc project using this URL: https://lumosql.org/doc. That is intended to be the finished product, the output of "make all" within Lumodoc.
The README.md document you are reading is part of the Lumodoc project, not the finished product Lumodoc produces, and the master version of this README.md is kept at the top level of this repository . The documentation for the Lumodoc project is in the "docdoc" subdirectory because it is documentation about documentation.
The list of jobs is in the LumoDoc ToDo long-running forum thread.
Lumodoc sources and the official website are managed using the FossilSCM. If you are reading this on Github or anywhere other than lumosql.org then you are looking at a read-only mirror. Mirrors are good and important, but everything else in this project assumes you are working with the master repository for Lumodoc, hosted at lumosql.org.
Drop in to the Lumodoc forum and post a message about what you think needs done. You can tell us about corrections to the documentation, or contribute anything else you wish, noting that the forum understands the Markdown format. You can subscribe to email alerts for when there has been a commit to the repository, or to get copies of all forum posts as email.
To contribute or to explore how the docs work you need to download Fossil or build it on your local computer. Then run:
fossil clone https://lumosql.org/src/lumodoc
which will download the Fossil repository into lumodoc.fossil, create a directory called "lumodoc", and then open the new local repository into that directory. You won't be able to push your commits back up to the central lumodoc repository without a username and password, but otherwise you have everything you need to play around with the documentation tools.
The "fossil ui" command invokes Fossil's [embedded documentation][https://fossil-scm.org/home/doc/trunk/www/embeddeddoc.wiki] to render markdown documents on your local computer. Here is the command to render the README.md document you are reading right now:
fossil ui --page doc/trunk/README.md
If you want to render a file in a local directory before it is committed to the repository (which is a much better way of developing - always test before committing!) then you can use the special version "ckout" instead of "trunk" like this:
fossil ui --page doc/ckout/README.md
If you want all the internal links in the README to be converted too (that is, links which point to other files with the respository rather than URLs for external sites) then you can use "--ckout-alias" like this:
fossil ui --ckout-alias trunk --page doc/trunk/README.md
This allows relative links to appear in embedded documentation of the form:
/doc/trunk/docdoc/README.md
which will then be read off your local directory.
The URL https://lumosql.org/doc is an Apache webserver alias pointing to the Fossil repository directory doc/. Fossil serves up the current version of the requested file, processing all markup according to Fossil's Markdown rules, and generating HTML. The HTML is then served by Apache just as if it was contained in my-webpage.html .
With the Markdown text, diagrams are specified using Pikchr, a plain text format that generates SVG.
In a near-future version of the LumoDoc project it is almost inevitable that we will change this workflow to include the amazing Pandoc document convertor. The first step to using Pandoc would be to have it process the Markdown files and generate new Markdown files that include a table of contents (all ToCs are currently generated by a tool and imported manually.) Pandoc can convert from Markdown to PDF and HTML, so there are many other eventual possibilities.
In more detail... while there are a few very code-specific technical documents included in the main LumoSQL project, everything else is here because:
- Document management tools, scripts and work-in-progress notes are nothing to do with a production database system and shouldn't be mixed up with it
- Other output formats such as a website(s) or a book are even further from a production database
- Documentation often has a very different release cycle and management process than code
- Bugs, fixes and complaints to documentation shouldn't generally be mixed up with code problems
- LumoDoc mainly uses a documentation-specific Creative Commons licence. Over LumoSQL everything is under one single code-specific licence .
Co-incidentally, SQLite documentation is also managed in a separate repository from the code. This is one of many examples where the LumoSQL project is somewhat similar to SQLite.