		Search-engine friendly clone of the ACL2 documentation.

Save

Deploying-manuals

How to distribute XDOC manuals for other people to use.

After you have documented your books with XDOC and created a manual, you may wish to share your manual with coworkers, collaborators, customers, sponsors, etc. The best way to do this may depend on many factors.

By default, the manuals created by save use only client-side JavaScript code. This makes deployment very easy: you can just copy the files to wherever you like, and you don't even need a web server.

This approach—just copying the default manual—is well-suited for:

Browsing from your local hard-drive, or
Browsing from a fast NFS drive or intranet server

But the default manuals will perform badly on slow connections. So, if your users are going to read the manual over, e.g., VPNs or public web sites, then you may wish to read on.

Server-Supported Manuals

The basic reason that the default manuals are slow is that they work by simply loading the data for every topic, at startup. As of October 2013, this comes to around 25 MB of data for the basic doc/top.lisp manual. It's no big deal to load 25 MB from a local hard drive or a fast intranet connection, but it can be quite slow over the internet.

The XDOC manuals created by save can be reconfigured to just load the :long sections as they are accessed. This results in a much faster-loading manual, and is how, for instance, the online XDOC manual at Centaur was deployed.

This option requires a small amount of configuration, and you may need to coordinate with your network administrator to get certain software installed.

If you want to use our scripts directly, you will need a web server that supports Perl scripts with the CGI, DBI, and DBD::SQLite modules installed. If for some reason this poses a problem, you may find that you can easily port these scripts to other popular languages, like PHP or Ruby, with SQLite support.

Step 1: Create the Database

In the manual directory you created with the save command, you should find a Perl script named xdata2sql.pl. When you run this script, you should see something like the following output:

$ cd my-library/manual
$ perl xdata2sql.pl
-------------------------------------------------------------------------------

xdata2sql.pl: Convert xdata.js into xdata.db (an sqlite3 database)

   NOTE: Most folks don't need to run this at all!
         If you just want to:
          - browse an XDOC manual on your local hard drive, or
          - share an XDOC manual on your fast intranet
         then ignore this script and just see index.html.

The main use for this script is to share XDOC manuals on the internet.  In this
scenario, just having the web browser load in the entire (generally 20+ MB)
xdata.js file is not very practical, because some users will have slow
connections and will take too long to load the file.

There are many ways to solve this.  Our approach is to convert xdata.js into an
sqlite3 database, and then use a server-side script that will allow us to
access topics only as they are requested.

-------------------------------------------------------------------------------

; Converting xdata.js

; Reading file
; Checking file
; Parsing JSON data.
; Creating new xdata.db.
; Creating xdoc_data table.
; Populating xdoc_data table.
; All done.

To actually use the database, see xdataget.pl.

After this step, you should have a new file named xdata.db in your manual directory. This is an SQLite3 database that has the information for your XDOC topics. It should be roughly as large as xdata.js.

If you are missing some required Perl modules, then instead of the above output you may see a message such as

Can't locate DBI.pm in @INC ...

In this case, you may need to ask your systems administrator to install the missing modules.

Step 2: Set up the Web Server

Once you have created the xdata.db file, you will need to copy both it and a different script, xdataget.pl, to some directory in your web server.

Typically, for xdataget.pl to work at all, it will need to have its executable bit set, and it may need to be in a special directory within your web server, typically named cgi-bin.

To make sure the script is working, you should now load it in your web browser by going to, e.g., http://my-server/cgi-bin/xdataget.pl. If everything is working, you should see a page that looks like this:

{"results":[

]}

If, instead, you see a message like Internal Server Error, then you may have a permissions problem, or your web server's version of Perl may be missing a require library, or something else may be wrong; ask your systems administrator for help.

You may also wish to load, e.g.,:

http://my-server/cgi-bin/xdataget.pl?keys=ACL2____TOP

and make sure that you can see some text from your top topic.

Step 3: Configure the Manual to use the Server

The final step is to edit the file config.js in your manual. This file contains comments with the example syntax. Basically you just need to change:

var XDATAGET = "";

To have the right URL for your xdataget.pl script, e.g., into:

var XDATAGET = "http://my-server/cgi-bin/xdataget.pl";

At this point, your manual should load topic data dynamically as needed. The result should be much faster for users on slow connections.