CouchDB: The Definitive Guide

This is the source code repository for a free book about Apache CouchDB.

Introduction

The book is called CouchDB: The Definitive Guide and is published by O’Reilly Media under a free license.

We believe that community software needs community documentation. You can inspect the source code for CouchDB and make improvements to it, and similarly you can inspect the source code for this book and make improvements to it. If you want to contribute, please do so! Fork it, hack on it, and send back your changes! If you want to support the project, you can do so by buying a copy of the book in digital or printed form.

<<<<<<< HEAD

Organisation

The source is organised into the following directories:

draft/

The draft of next edition.

editions/

Published editions of the book.

editions/1

Edition 1 of the book.

editions/1/en

The English version of edition 1 of the book.

The draft of the next edition is a work in progress. Like the trunk of an open source project, we will eventually cut from this and hand it over to our publishers. Once the publishing process is complete, we will take back the XML and convert it into HTML. Like a tag of an open source project, this will be frozen in place as an official edition of the book. Translations are subject to change and may be updated at any time.

Contributions

The book is made available under a Creative Commons Attribution license.

We encourage you to fork our work and make your own improvements under the terms of the license. If you have any changes you want to send back our way, please make a regular pull request via Github. If the authors like your changes, they may integrate them into the official book and give you a credit in the next edition. If you just have an issue to report, please use the regular Github issue system.

Translations

We’d like to encourage people to start translating the book into other languages. If you’d like to start a new translation, please first check to see if one exists in that language. If not, you can get started right away. You’re free to publish a translation under the aforementioned license. Our publishers may be interested in your translation if you think the market would be big enough. Please contact us directly to discuss this.

Please observe the following guidelines:

• Do start your translation from the en/ directory

• Do use the appropriate language tag for your new directory

• Do not translate the draft/ directory, as this is will be a work in progress

• Do not translate from anything other than the en/ directory, as this will introduce errors

• Do not modify the general markup or structure of the documents

• Do not include your own styles or scripts

Here’s an example of how to start a new translation:

cd editions/1
cp -r en de
git add de
git commit -m 'new German translation' de

=======

Dependencies

We edit the book in HTML and accept contributions in HTML.

HTML allows us a lot of freedom as authors, and makes editing much easier. Before going to print we hand the HTML to O’Reilly Media, and they convert this into DocBook. DocBook allows a lot of control over the typesetting and publishing of the book. Once that process is complete, O’Reilly Media hand us back the final DocBook, which now includes any modifications from our editors. We then transform this into HTML, and tidy it up.

You must install the DocBook XSL stylesheets to generate the HTML:

sudo port install docbook-xsl

You must install Tidy to clean the HTML:

sudo port install tidy

You can now generate HTML from the DocBook source.

Instructions

The DocBook source for the book is under:

src/EDITION

So, the first edition of the book can be found at:

src/01/book.xml

And the images used for the first edition of the book can be found at:

src/01/figs

The tools we use to convert this into HTML can be found at:

bin/

You can transform the DocBook to HTML by running:

bin/transform.sh src/EDITION/book.xml

You can tidy the HTML files by running:

bin/tidy.sh ch01.html

The HTML we generate with this process is held in the gh-pages branch.

Building an epub

Build an epub with off-the-shelf docbook-xsl dbtoepub src/01/book.xml. (The script lives in the DOCBOOK_XSL_ROOT/epub/dbtoepub at least as of docbook-xsl version 1.75.2.) >>>>>>> upstream/master

Relax.