% 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)). We can also supply some optional parameters: bookshelf --css bookshelf.css --editor gedit Shelf The first parameter tells Bookshelf which style sheet to use for the generated pages. The recommended style sheet for Bookshelf is [`bookshelf.css`](http://www.cse.chalmers.se/~emax/bookshelf.css). The second parameter tells what editor to use when editing the source files. This command will appear in an edit/regenerate script at the end of each generated page. Running Bookshelf without arguments results in the following message which shows the complete usage: bookshelf [options] [-c,--css ] Path or URL to CSS style sheet [-e,--editor ] Command used for editing source files [-m,--mathjax ] Path or URL to MathJax.js file [-n,--no-script] Do not display the edit/regenerate script Root directory of bookshelf to be generated An optional parameter is provided to indicate a link where to find [MathJax](http://www.mathjax.org/) javascript file, to use it for math rendering with Pandoc. 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). 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. For convenience, each generated HTML file displays a "script" for editing/regenerating the source file at the end. This can be turned off by providing the `--no-script` flag. 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#title-blocks) 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. This information will then be used when listing the ordinary document. Demonstration ============= The contents in [Documentation](.) has been generated by Bookshelf. In addition to the current manual, it contains a sub-directory [Test](Test/) with some example files in it. The source of the documentation directory can be found [here](http://projects.haskell.org/Bookshelf/Documentation/). 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/cgi-bin/hackage-scripts/package/Bookshelf), run: cabal install Bookshelf Alternatively, fetch the [repository](http://projects.haskell.org/Bookshelf) darcs get http://projects.haskell.org/Bookshelf and run cabal install inside the `Bookshelf` directory. Credits ======= See [this list](Credits.shelf).