Skip to content
README 11 KiB
Newer Older
See announces about Exscribe on
	http://fare.livejournal.com/tag/exscribe
and the web page on
	http://www.cliki.net/Exscribe

------>8------>8------>8------>8------>8------>8------>8------>8------>8------
COPYRIGHT

Exscribe is written and Copyright (c) 2005-2009 by Francois-Rene Rideau.

Exscribe is available under the terms of the bugroff license.
	http://www.geocities.com/SoHo/Cafe/5947/bugroff.html
You may at your leisure use the LLGPL instead < http://www.cliki.net/LLGPL >

Exscribe depends on cl-launch, scribble, fare-matcher and fare-utils.

If compiled with the PDF backend, then Exscribe also depends on CL-Typesetting
for generating documents. The PDF backend was written by Denis Mashkevich.
The PDF backend isn't very featureful at this time. Contributions welcome.

For projects regarding the extension of Exscribe, see
        http://fare.tunes.org/computing/term-project-proposal.html

------>8------>8------>8------>8------>8------>8------>8------>8------>8------
INSTALLING

You need CL-Launch already installed:
	http://www.cliki.net/CL-Launch

Create and install an exscribe binary by editing the Makefile
to suit your installation paths and then running make install.
        mkdir ~/lib
	make LISPS=clisp INSTALL_LIB=~/lib install

The Lisp implementations are listed there in faster-to-slower order with
respect to running my Exscribe document set (the largest one in the world!)

------>8------>8------>8------>8------>8------>8------>8------>8------>8------
INVOCATION

You may compile files your former Scribe files or new Exscribe documents with
	exscribe -I ${INCLUDE_DIR1} -I ${INCLUDE_DIR2} -v -o foo.html foo.scr
where INCLUDE_DIR1, etc., is where you store your style files.

Options:
 -h -?  --help                          show some help
 -v     --verbose                       output some information along the way
 -I     --include   /PATH/to/style/     add directory to include path
 -o     --output    destination-file    which file to create
 -H     --html                          select the html backend
 -P     --pdf                           select the PDF backend
 -M     --many      src dst files...    compile files from src to dst
 -D     --debug                         enable the Lisp debugger
        --repl                          provide the user a REPL

If you have trouble running your Scribe documents, tell me and I'll either
add features to Exscribe or tell you how to tweak your document to make it
compatible with both Scribe and Exscribe.

------>8------>8------>8------>8------>8------>8------>8------>8------>8------
CALLING EXSCRIBE FROM LISP

If you are debugging Exscribe or integrating it with your code, you may
  (load "/home/fare/fare/lisp/exscribe/setup.lisp")
  (asdf:oos 'asdf:load-op :exscribe) (in-package :exscribe)

And then you can compile a file with
  (add-exscribe-path "/home/fare/fare/www/")
  (exscribe-load-document "/home/fare/fare/www/liberty/microsoft_monopoly.scr")

Or compile it as PDF with
  (add-exscribe-path "/home/fare/fare/www/")
  (setf *exscribe-mode* 'pdf)
  (with-open-file (*standard-output* "/home/fare/microsoft_monopoly.pdf"
                   :direction :output
                   :if-exists :rename-and-delete :if-does-not-exist :create
                   #+sbcl :element-type #+sbcl :default)
    (exscribe-load-document "/home/fare/fare/www/liberty/microsoft_monopoly.scr"))

------>8------>8------>8------>8------>8------>8------>8------>8------>8------
DOCUMENTATION

See Manuel Serrano's Scribe documentation for Exscribe is designed after:
	http://www-sop.inria.fr/mimosa/fp/Scribe/
Exscribe is mostly compatible, as far as the supported basic primitives go.
Bear in mind the following differences and limitations:

 * Exscribe is based on CL rather than Scheme.
  A simple Scheme compatibility layer is provided in simple cases.
 * Error checking and reporting is minimal.
  I use my CL's backtrace to locate and identify errors (with option --debug).
 * Only those features that I use have been implemented.
 * The HTML backend is used and well-maintained.
 * There is a working PDF backend, though it's slow and not very featureful.

If you wonder about how some feature works, you may contact me.
If you require more features, you may contract me.
The source is also open for you to inspect and modify.

------>8------>8------>8------>8------>8------>8------>8------>8------>8------
EXAMPLES

The only currently published example is at
	http://fare.tunes.org/files/asdf-packages/exscribe-examples.tar.gz
It includes one essay that stresses most of the features of exscribe,
as well as a cl-compat.scr file for the original scribe, that shows you
(together with the cl-compat.scr file included in exscribe) how to write
programs that display correctly in both Scribe and Exscribe.

If you are interested in more, contact me.

You may actually download .scr files from bastiat.org -- just change .html
into .scr and in most cases you'll find some valid exscribe source, that
depends on a bo-style.scr file found in the root directory as well as on
the fare-style.scr file found in the above example archive.

------>8------>8------>8------>8------>8------>8------>8------>8------>8------
SUPPORTED IMPLEMENTATIONS

You may use your favorite CL implementation.
Known working from fastest to slowest are
	CMUCL 19c, SBCL 1.0, CLISP 2.41, OPENMCL 1.1pre, Allegro 5.0.
Known not working are ECL 9.6.1 and GCL 2.7 (both bork in weird ways).
Other implementations not supported (yet).

------>8------>8------>8------>8------>8------>8------>8------>8------>8------
PERFORMANCE ISSUE

If you're interested in improving performance, here are the main issues.

New, unsolved issues:

* our PDF backend, in addition to being rather poor in terms of features,
 is also quite slow. The whole architecture of it is rather poor.

Older, solved issues:

* Long time required to compile Scribe files.
 CMUCL used to be about the same speed as CLISP. SBCL used to be 3x slower
 because it insisted on compiling everything.
 SBCL is now almost as fast as CMUCL thanks to its new interpreter. All
 implementations are much faster thanks to cacheing of precompiled style files.
 CLISP is the exception, and became slower between 2006-05 and 2006-10;
 investigation required (apparently, 2.40-2 is faster than 2.38-1).

* Long time required to load the Exscribe FASLs.
 It's half the computation time when compiling microsoft_monopoly.
 After discussion with Xof from #lisp, it seems that correct FASL loading
 is intrinsically computationally intensive. FASLs are no incremental image
 dumps, they must deal with a *lot* of issues, including symbol interning
 and uninterning, special variables, generic-function non-redefinition, etc.
 Solution: dump an lisp image. CL-Launch now has this functionality.

------>8------>8------>8------>8------>8------>8------>8------>8------>8------
PROJECTS:

* Improve the cl-typesetting backend: add styles, boxes, real footnotes, etc.

* Implement pictures and/or embedded cl-typesetting rendering code that
 appears correctly on both PDF and HTML output.

* Use the cl-bibtex stuff in slyrus' smarkup. Maybe his Latex backend, too
   http://www.cyrusharmon.org/cl/projects/

* Use generic functions as in Skribe and/or DefDoc

------>8------>8------>8------>8------>8------>8------>8------>8------>8------
On my libretto U105 (Pentium M 1200):

2007-03-14 (code changes explain a lot of performance difference with previous. But which?)
cmucl 19    =>  31.73s user 4.66s system 95% cpu 38.207 total
           all  29.67s user 2.56s system 96% cpu 33.356 total
sbcl 1.0    =>  37.07s user 3.60s system 94% cpu 42.905 total
                35.29s user 4.15s system 93% cpu 42.166 total
           all  30.87s user 1.36s system 83% cpu 38.394 total
clisp 2.41  =>  161.07s user 23.11s system 93% cpu 3:16.87 total
            =>  194.82s user 22.91s system 96% cpu 3:45.10 total (big discrepancy b/w runs)
           all  194.08s user 20.20s system 94% cpu 3:46.07 total

2006-10-08 -- complete reversal of fortune as compared to previous measurement!
clisp 2.40  =>  188.73s user 25.12s system 82% cpu 4:19.69 total
           all  200.69s user 21.08s system 87% cpu 4:12.16 total
        libcmp  176.21s user 25.16s system 93% cpu 3:36.17 total
    libcmp+all  178.37s user 19.92s system 92% cpu 3:35.35 total
   2.38 libcmp  179.48s user 24.64s system 92% cpu 3:40.79 total
      2.38 big  3.65s user 0.50s system 97% cpu 4.255 total
          null  0.08s user 0.03s system 86% cpu 0.134 total
           big  3.37s user 0.46s system 98% cpu 3.878 total
   nodump+null  4.22s user 0.16s system 93% cpu 4.668 total
    nodump+big  9.24s user 0.72s system 98% cpu 10.124 total

cmucl 19c   =>  189.98s user 24.61s system 91% cpu 3:53.61 total
           all  198.00s user 20.13s system 87% cpu 4:10.43 total
        libcmp  33.45s user 5.16s system 90% cpu 42.703 total
    libcmp+all  31.52s user 2.62s system 78% cpu 43.656 total
 libcmp+crypto  32.98s user 5.19s system 84% cpu 44.919 total
          null  0.06s user 0.01s system 75% cpu 0.090 total
           tst  0.13s user 0.04s system 83% cpu 0.201 total
           big  0.56s user 0.07s system 94% cpu 0.667 total
   nodump+null  3.49s user 0.26s system 96% cpu 3.884 total
    nodump+tst  3.67s user 0.23s system 97% cpu 3.993 total
    nodump+big  4.10s user 0.26s system 99% cpu 4.397 total

sbcl 0.9.17 =>  166.15s user 7.02s system 88% cpu 3:16.38 total
           all  167.07s user 3.69s system 89% cpu 3:11.81 total
           cmp  44.53s user 5.18s system 86% cpu 57.284 total
       cmp+all  41.49s user 1.78s system 87% cpu 49.572 total
        libcmp  39.20s user 4.42s system 93% cpu 46.871 total
    libcmp+all  34.71s user 1.28s system 85% cpu 42.148 total
        bigtst  0.46s user 0.04s system 82% cpu 0.610 total

allegro 5.0 =>  442.23s user 4.65s system 91% cpu 8:08.50 total
        allscr  350.74s user 1.74s system 89% cpu 6:31.84 total
Note: first tests are loading all files on a cryptoloop reiserfs, using targets all and allscr;
  cmp and cmp+all are the targets while compiling all files on tmpfs
  libcmp and libcmp+all are the targets while compiling styles only on tmpfs.
  libcmp+crypto is the same test on cryptoloop reiserfs,
  demonstrating that disk I/O was not the problem.
  Constantly re-compiling style files was taking 83% of the time!
  My style files seem to have become many times more complex to compile since 2006-05-01(!)

CMUCL 19c seems to have a bug in TRANSLATE-PATHNAME (!)
Error in function LISP::DIDNT-MATCH-ERROR:
   Pathname components from Source and From args to TRANSLATE-PATHNAME
did not match:
  #P"/dev/shm/tmp/bastiat/en/index.html" #P"/dev/shm/tmp/bastiat/**/*.*"


2006-05-01:
touch webs/bastiat/bo-style.scr ; time make -C webs/bastiat
clisp 2.38  =>  70.26s user 8.22s system 71% cpu 1:50.24 total
cmucl 19c   =>  69.66s user 9.25s system 70% cpu 1:51.54 total
sbcl 0.9.13 =>  378.18s user 15.84s system 74% cpu 8:48.25 total
sbcl+eval   =>  373.30s user 15.82s system 75% cpu 8:35.07 total
allegro 5.0 =>  380.37s user 3.07s system 47% cpu 13:28.23 total

------>8------>8------>8------>8------>8------>8------>8------>8------>8------

Share and enjoy!

------>8------>8------>8------>8------>8------>8------>8------>8------>8------