http://wiki.debian.org/DebianReference

I recommend that you seriously investigate two apps designed for the purpose of creating books. One is SiSU, http://www.jus.uio.no/sisu/ (;) the other has already been mentioned, the Daisy platform. http://cocoondev.org/daisy/index.html (.)

SiSU outputs, among many formats, ODT, LaTeX, PDF, HTML, and structured XML. It is a mature publishing framework for creating lengthy articles and books, using a wiki-like markup in plain ASCII files as input, with the same imput file outputting to multiple formats. Features for academic writing are particularly strong, given SiSU’s origin as a publishing tool for legal texts. However, I’m unsure of its support for mathematical symbols, having never used them in SiSU, so it might be necessary to add them in LaTeX. The SiSU markup is far more mnemonic than most wiki syntaxes, and for me was easier to learn. (I prefer writing in XHTML markup myself.)

SiSU has outstanding support for numbering of all supported object types, e.g., chapter, page, paragraph, line, footnotes. The SiSU site has numerous sample books. It will also automagically generate a concordance for indexing purposes.

Downsides: No WYSIWYG editor, lacks strong management features for documents, versions, and variants. Has Linux/Unix dependencies.

I won’t add much to what’s already been said about Daisy. Daisy does have a WYSIWYG editor and very strong management features for documents, versions, and variants. It also has strong transclusion capabilities, providing a single editing point for recurring content, which IMHO is a critical feature when producing documents with overlapping content.

Supports ODT and several other formats out of the box, but apparently not Docbook. But with the underlying Cocoon componentry framework, adding additional output formats should be fairly trivial. See generally http://cocoon.apache.org/2.1/features.html (.) And with Cocoon as the framework, it should also be feasible in Daisy to use a WebDAV client such as OOo as the “live” input editor.

Creating cross-referencing links in Daisy is particularly easy, with a search dialog built into the link forming system.

Between the two systems, I left SiSU for Daisy because of users’ strong preference for working with a WYSIWYG editor, Daisy’s far stronger document management system, and stronger collaboration features. But that came at the cost of the far more robust document formatting capabilities in SiSU.

The Net Duck

Thanks in advance for any hints/pointers!

Kind regards,

Holger

I was able to find very little on the net about this human-interface
side of “writing a book collaboratively”, and very little support from
current software. (I’d be pleased to hear about any thought on the
topic.) It might be that this is a very new topic, and solutions are
only beginning to be drafted.

I have been setting up a Wiki for collaborative writing and editing of
a tutorial book on Grid Computing ( http://www.egrid.it/doc/gme ); we
use it as an online reference resource, and print copies to hand out
to participants at training events. We also would like participants
at training events to edit the content to clarify points that were
written in initiated jargon, share their view, add their own examples
and experiences — in short, have the text reflect a community
experience.

Here comes the problem. Just putting the text into a Wiki isn’t
sufficient:

1- Every contributor has to learn the markup language used by the
Wiki system.[1]

2- More important, every contributor has to agree to some stylistic
and typographical conventions (how to format computer output and
examples, usage of acronyms, etc.), or you end up with
inconsistently-formatted text.

It is *very important* to keep the effort needed as light as possible,
or you loose contributors, that is, active community members. (In our
case, it’s scientific researchers that perceive the time spent in
learning the details of some computer program as time wasted in not
doing useful research — even if it could save them some later on…)

I believe that item 2 above is the most important one: coherent
typographical rendering is *very* important to novice readers, who
often cannot tell apart the different elements from context alone.[2]
Coherent typographical conventions convey “action” clues (e.g.,
monospaced text is for “type on keyboard exactly as written in text”)
but they *need to stay the same throughout the text*.

In the end, here’s a few technical details on how we are trying to do
it:

– We use reStructuredText for Wiki markup; most reST markup is just
formatting a plain text document for better reading. It helps to
keep the page sources readable even after many edits, and could
reduce the learning time and effort required by prospective
contributors.

– We require authors to comply with some (hopefully simple and
natural) text formatting conventions. Of course, the conventions
are stated on a Wiki page, so they can be discussed and changed -
establishing the conventions is part of book writing itself!

– From time to time, we dump the page *sources*, assemble them, and
produce a PDF booklet (reST -> LaTeX -> PDF), that we can print
and hand out.

.. footnotes:

.. [1] WYSIWYG editors might lighten the effort required here,
although I think that most WYSIWYG editors are harder to use than
well-designed lightweight text markup, for anything other than
casual editing of short text.

.. [2] Think of GNU/Linux novices learning bash command-line usage:
if the book lists an example line reading “bash$ grep ‘myregex’
myfile.txt”, will they know that they should not type the “bash$”
part if it’s not written in a different font or color? will all of
them understand that they should substitute their own values for
“myregex” and “myfile.txt” without any visual clue?

I wrote a book using MediaWiki, for my thesis. I developed software that consolidates MediaWiki pages into a single HTML (Boom! book microformat) page with the images inlined in the book. I found it a breeze to work with MediaWiki and then consolidate the book at any time when anyone wanted a “snapshot” of the work in progress, and it was also easy to generate the final printed output.

http://software-libre.rudd-o.com is the address. MediaBook is the software. Feel free to contact me or have anyone in your staff contact me if you want help on how to use it.