The SQLite language documentation is great! I want to use the same thing to document my own stuff. How can I generate those diagrams and associated text?

Here's a link to one page, for example: https://www.sqlite.org/lang_createtable.html

hmmmm... I got to the web page with the list of files: https://www.sqlite.org/docsrc/dir?ci=tip

Now, how do I actually download those file? I can't find an option anywhere on the page. There are more than 70 files.

There are "Tarball" and "ZIP Archive" links on the https://www.sqlite.org/docsrc/vinfo?name=15a047bc79409af5 page.

I must be blind because I can find links to neither Tarball nor ZIP Archive on the page you referenced.

I must be blind because I can find links to neither Tarball nor ZIP Archive on the page you referenced.

There's a Fossil feature that controls whether they're available to users not logged in or logged in as "anonymous." The capability to allow zip and tarball access is apparently not given to such users on that repo.

Until/unless drh changes that, you can clone the whole repo, giving you everything in the repo, including historical material:

sudo apt install fossil        # or download from fossil-scm.org, or...
mkdir ~/museum                 # where one keeps Fossils
fossil clone https://www.sqlite.org/docsrc ~/museum/sqlite-docsrc.fossil
mkdir -p ~/src/sqlite/docsrc/trunk
cd ~/src/sqlite/docsrc/trunk
fossil open ~/museum/sqlite-docsrc.fossil

The ~/src/sqlite/docsrc/trunk directory structure allows for things like ~/src/sqlite/docsrc/2019-06-30 or ~/src/sqlite/sqlite3/trunk. You could flatten it if you just want a single SQLite-related Fossil repo checkout.

Thanks, Warren. I have now turned on the "z" permission bit on the docsrc repository. The Tarball and ZIP Archive lines should now be available to all.

Thanks, Richard :)

Is there an implementation of that syntax diagram maker in PostScript?

I downloaded the tarball and got the source. I am on W10 so not unix. I installed Linux Ubuntu package, so I have bash. Now I'm trying to build your stuff so I can see how it works (it's not simple). I get an error on the build no matter what make target I use:

$ make schema make: *** No rule to make target '../sqlite/src/test_md5.c', needed by 'tclsh.docsrc'. Stop.

Where is test_md5.c?

Where is test_md5.c?

You ignored step 1 on the home page of the docsrc repo: "The SQLite install should be in ../sqlite" etc.

Sorry, I must be going blind again. I downloaded the amalgamation but no test_md5.c. In fact, no "src" folder either:

doug@HP610:/mnt/q/qt_projects/dancemusicmanager/doc/sqlite$ ls -al total 15744 drwxrwxrwx 1 root root 512 Apr 15 13:25 . drwxrwxrwx 1 root root 512 Apr 15 08:25 .. -rwxrwxrwx 1 root root 4393914 Apr 15 13:16 Documentation+Source+Text-15a047bc79.zip drwxrwxrwx 1 root root 512 Apr 14 22:15 dst -rwxrwxrwx 1 root root 591565 Jan 28 03:25 shell.c -rwxrwxrwx 1 root root 2389909 Apr 21 11:41 sqlite-amalgamation-3310100.zip -rwxrwxrwx 1 root root 8074669 Jan 28 03:25 sqlite3.c -rwxrwxrwx 1 root root 576161 Jan 28 03:25 sqlite3.h -rwxrwxrwx 1 root root 34802 Jan 28 03:25 sqlite3ext.h

The "source trees" referenced in the same step are not the amalgamations. It's referring to the full and complete source code trees for the software referenced.

For SQLite, that means this: https://sqlite.org/src/

The small bundle of files referred to as "the amalgamation" does not contain source files such as test_md5.c ; it only has

> unzip -v sqlite-amalgamation-3300100.zip
Archive:  sqlite-amalgamation-3300100.zip
 Length   Method    Size  Cmpr    Date    Time   CRC-32   Name
--------  ------  ------- ---- ---------- ----- --------  ----
       0  Stored        0   0% 10/11/2019 07:26 00000000  sqlite-amalgamation-3300100/
 7947211  Defl:N  2050426  74% 10/11/2019 07:26 beace389  sqlite-amalgamation-3300100/sqlite3.c
  588681  Defl:N   148854  75% 10/11/2019 07:26 977b314b  sqlite-amalgamation-3300100/shell.c
   34156  Defl:N     6012  82% 10/11/2019 07:26 cd5c3e82  sqlite-amalgamation-3300100/sqlite3ext.h
  564824  Defl:N   146169  74% 10/11/2019 07:26 29978aed  sqlite-amalgamation-3300100/sqlite3.h
--------          -------  ---                            -------
 9134872          2351461  74%                            5 files

>

Peruse near the bottom of the download page for "Source Code Repositories". From there, you should be able to get to the files that go into the amalgamation.

Go into the sqlite directory and say make tclsqlite3.c, then return to the docsrc directory and try again.

(Basically, missing step.)

It turns out that I had to build Sqlite in order to get tclsqlite.c. I was successful in building that and in building the doc files.

However, my goal is to build my own docs. I can't figure out what the minimum set of files and processes are to get something that works. Can you tell me what that minimum set is and what processes I have to run (by hand) to gen the docs, please?

You need two files from docsrc:

• art/syntax/bubble-generator.tcl
• art/syntax/bubble-generator-data.tcl

The second file (the "-data.tcl" file) is the one you customize in order to generate your desired bubble diagrams. The first file is code that translates your "-data.tcl" file into art.

You will need "wish" (the Tcl/Tk command-line shell) in order to run the bubble-generator.tcl tool. And you will need "convert" to translate the Postscript output from "wish" into GIF. And you will need "display" to display the generated GIF for verification. Summary of third-party tools needed:

• wish
• convert
• display

I don't recall any other requirements right this moment.

Now good luck finding these dependencies with such generic names! :)

I tried Googling display and display tool just for fun, and came up dry of course.

I tried searching for "display(1)" and found a manual page, which stated it was part of imagemagick. Convert may be the same. The names are indeed problematically generic.

Thank you, Richard, for how-to generate the bubble diagrams. I can generate the diagrams, but all the text overflows the boundaries of their containers. I changed the font value but it made no difference. Any ideas?

The next request is for the minimum set of files needed to actually generate a multi-page html document which looks like Sqlite's SQL pages. I don't want requirements, nor testing. Just want to document my language. I've spent a couple of days pouring over the files with few results. I know that the lang_xxx files contain the descriptive text and that you use an Sqlite database for the information, but I can't figure out how to populate the database, or even find out how it's used. Can you point me in the right direction? Thanks.

Like doug9forester, I have a project for which this style of diagram seems ideal, and have encountered the same trouble with captions not fitting within containers. I feel there should (or even must) be some parameter which sets limits to the "ballooning", as I notice that the containers are shrunk to fit any very short captions.

I'm also wondering how to specify a rectangular shape for some of the bubbles.

Exploring the code, I've worked out how to specify the -data file on the command line, and also how to hand-code the diagrams in this file. Details are below, in the hope that someone may find this information helpful.

At the top of the file bubble-generator.tcl, Instead of

set datafile [file join [file dirname [info script]] bubble-generator-data.tcl]
source $datafile

I've put the following

if {$argc == 0} {
set datafile [file join [file dirname [info script]] bubble-generator-data.tcl]
} else {
set datafile [lindex $argv 0]
}
source $datafile

And my data file currently looks like what appears below.

# Graphs:
#
set all_graphs {
  ipv4-resolution {
      line /hostname
      {or
          nil
          {line {toploop
                  {or
                      CNAME
                      DNAME
                  }}}} A /ipv4-address-set
  }
  ipv6-resolution {
      line /hostname
      {or
          nil
          {line {loop
                  {or
                      CNAME
                      DNAME
                      }}}} AAAA /ipv6-address-set
  }
}

The SQLite diagrams are called "syntax diagrams" or "railroad diagrams": wikipedia.

Using a search engine for "railroad diagram" shows many ready-to-use tools in different programming languages.