% Bookshelf manual Introduction ============ Bookshelf is a simple wiki-like document organizer for use locally on one machine. Viewing is done through a web browser, and the content is generated statically. There are two types of documents: *shelf documents* which are generated from the convenient [markdown](http://daringfireball.net/projects/markdown/) format and can be viewed directly in the web browser, and *ordinary documents* (for example PDF, HTML, etc.) which the web browser treats in any way it likes. The most important feature of Bookshelf is its simplicity: No web server is needed. There are no global files for configuration/caching/indexing etc. A complete document collection is simply represented as a directory structure containing the relevant documents. Bookshelves are modular in the sense that sub-directories can be moved arbitrarily within or between bookshelves without worrying about inconsistencies[^PossibleInconsistency]. Documents are added simply by placing them within the directory structure. [^PossibleInconsistency]: Links may of course be broken when sub-directories are moved, but this can often be prevented by appropriate use of relative and absolute links. Furthermore, broken local links will be detected when the page is generated. Usage ===== The input to Bookshelf is a directory tree with shelf documents (extension `.shelf`) and ordinary documents (any other file). Running Bookshelf on the directory `Shelf` is done as follows: bookshelf Shelf This will (re-)generate the whole directory contents (see section [Operation](#operation)). Running Bookshelf without arguments results in the following message which shows the complete usage: usage: bookshelf [options] [-b,--bib ] Path to bibliography file [--csl ] Path to CSL style file [-c,--css ] Path or URL to CSS style sheet [-m,--mathjax ] URL to MathJax.js file (use "" to get the default URL) [--mathml] Use MathML for math rendering Root directory of bookshelf to be generated If no CSS style sheet is provided, [bookshelf.css](http://www.cse.chalmers.se/~emax/bookshelf.css) will be used. Pandoc (and hence Bookshelf) supports TeX math. By default, a very simple rendering is used. The `--mathjax` and `--mathml` options result in much improved math rendering, using [MathJax](http://www.mathjax.org) or [MathML](http://www.w3.org/Math) respectively. Note that MathJax requires running a script on a web server, so MathML might be preferred when the generated pages are viewed locally without access to internet or a local a web server. The markdown syntax is described [here](http://daringfireball.net/projects/markdown/syntax), and the extensions supported by [Pandoc](http://johnmacfarlane.net/pandoc/) (the converter used internally by Bookshelf) are described [here](http://johnmacfarlane.net/pandoc/README.html#pandocs-markdown). Demonstration ============= The contents in [Documentation](.) has been generated by running bookshelf --css bookshelf.css --bib Documentation/papers.bib Documentation in the root of the [project directory](http://hub.darcs.net/emax/Bookshelf). In addition to this manual, it contains a sub-directory [Test](Test/) with some example files in it. Operation ========= Bookshelf performs two main operations in a given directory: * Converts each file `name.shelf` to the file `name.shelf.html`. In this process, any links to files of the form `name.shelf` get redirected to `name.shelf.html`. * Places a file `index.html` at each directory node. This file contains links to the directory's sub-directories and documents. The [Meta information](#meta-information) section describes how the document listing can be affected. It is possible to exclude files or directories from being converted and indexed by using "ignore" files. To exclude the file `name`, simply add a file `name.ignore` in the same directory. Warning: Any existing file with the extension `.shelf.html` or the name `index.html` are assumed to have been generated by previous runs of Bookshelf. Such files will first be removed[^RemovedFiles], and then possibly regenerated, so one should be careful not to have ordinary documents with such names. [^RemovedFiles]: This process does not take any `.ignore` files into account, so, for example, the file `name.shelf.html` will be deleted regardless of whether the file `name.shelf.html.ignore` exists. Bookshelf checks that all local links (in shelf documents) are valid, and will issue warnings if this is not the case. Meta information ================ Pandoc's markdown syntax allows the specification of ["title blocks"](http://johnmacfarlane.net/pandoc/README.html) containing information about document title, authors and date. If such information is provided for shelf documents, it will be included in the document listing for each directory. Whenever a shelf document and an ordinary document have the same name, apart from extensions, the shelf document is assumed to contain information about the ordinary document. In this situation, we call the ordinary document the *main document* and the corresponding shelf document the *info document*. An info document will only appear as an "info" link next to its main document in directory listings. Furthermore, the info document may optionally specify meta information about the main document by including a section of the following form at the top of the markdown source: Meta ==== * Title: Title of document * Authors: * Author number 1 * Author number 2 * etc. * Date: Some string indicating date * Comment: Some comment * Keywords: * Keyword 1 * Keyword 2 * etc. (The "Meta" header is also allowed to be a lower-level header.) This information will then be used when listing the ordinary document. Installation ============ First, make sure to have the [Haskell Platform](http://hackage.haskell.org/platform/) installed. To install Bookshelf directly from [Hackage](http://hackage.haskell.org/package/Bookshelf), run: cabal install Bookshelf Alternatively, fetch the [repository](http://hub.darcs.net/emax/Bookshelf) darcs get http://hub.darcs.net/emax/Bookshelf and run cabal install inside the `Bookshelf` directory. Issues ====== Any issues can be reported [here](http://hub.darcs.net/emax/Bookshelf/issues). Credits ======= See [this list](Credits.shelf).