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------