Introduction¶

This documentation describes how to install, configure and use MirrorBrain.

It may be useful to consult the Release Notes/Change History for changes.

The detailed history of changes in the documentation itself could be looked at here.

How to improve this documentation¶

Working on the documentation is easy. This section explains how it is done.

Sources¶

The documentation sources are maintained in the docs subdirectory of the MirrorBrain Subversion repository. The source is formatted in reStructuredText. reStructuredText is simple to learn, and resembling Wiki markup which is quick to edit. Every page of the online documentation has a link named “Source” on top of the page which displays the corresponding source file in the subversion repository. You can use this to look at the source and get a feeling for the way the format works.

HTML is generated using the Sphinx Python Documentation Generator. Every change in the git repository becomes visible at http://mirrorbrain.org/docs/, through a post-commit hook running the generator.

Check out a working copy of the source with this command:

git clone https://github.com/poeml/mirrorbrain.git

The reStructuredText Primer is a helpful resource.

Submitting changes¶

To submit changes, there are several options:

sending patches to the mirrorbrain@mirrorbrain.org mailing list
requesting write access to the subversion repository (do so by writing to the mailing list)
of course, it is fully appropriate (and appreciated) if you simply send plain mail, pointing out deficiencies, or giving suggestions.

Testing documentation locally before committing¶

It is useful to test changes by generating HTML locally before committing. To be able to do this, you need to install the Sphinx Python Documentation Generator. It is available readily packaged on most platforms, named python-sphinx, py25-sphinx or similarly.

Generating the documentation is as easy as:

cd docs
make html

Then just open _build/html/index.html in your web browser. Simply rerun the make command after changes, watch its output for errors or warnings, and reload your browser window.

Implementation and design notes¶

Database hash store¶

Since 2.13.0, all hashes are stored in the database. Before, they were kept in files in the file system. The old store was suitable only for generation of old-style Metalinks.

Inside the database, the hashes are stored as compart binary blobs. For transfer, they are converted to hexadecimal. This is due to the following design decision: Storage is binary in so-called bytea columns. PostgreSQL automatically escapes binary (bytea) data on output in its own way. But this encoding is not very efficient in space. Hex encoding is more efficient (it results in shorter strings, and thus less data to transfer over the wire, and it’s also faster). The escape format is kind phased out, and it doesn’t make sense to use it in a new application (which we are). On the other hand, storage in bytea is as compact as it can be, which is good. So we store the data in binary, and provide a database view which converts to hex on the fly. The hex encoding function in PostgreSQL seems to be fast.