Documentation / Manual.shelf

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 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 inconsistencies1. Documents are added simply by placing them within the directory structure.

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

Running Bookshelf without arguments results in the following message which shows the complete usage:

usage: bookshelf [options] <source>
  [-b,--bib <bibliography file>]    Path to bibliography file
  [--csl <CSL file>]                Path to CSL style file
  [-c,--css <CSS file>]             Path or URL to CSS style sheet
  [-m,--mathjax <MathJax.js file>]  URL to MathJax.js file (use "" to get the default URL)
  [--mathml]                        Use MathML for math rendering
  <source>                          Root directory of bookshelf to be generated

If no CSS style sheet is provided, 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 or MathML 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, and the extensions supported by Pandoc (the converter used internally by Bookshelf) are described here.

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. In addition to this manual, it contains a sub-directory Test with some example files in it.

Operation

Bookshelf performs two main operations in a given directory:

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 removed2, and then possibly regenerated, so one should be careful not to have ordinary documents with such names.

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” 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 installed. To install Bookshelf directly from Hackage, run:

cabal install Bookshelf

Alternatively, fetch the repository

darcs get http://hub.darcs.net/emax/Bookshelf

and run

cabal install

inside the Bookshelf directory.

Issues

Any issues can be reported here.

Credits

See this list.


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

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