User:Patri/SeasteadBookCollaboration

The next edition of the seastead book will be produced collaboratively, by at least Patri & Will, possibly additional authors. This requires a software environment that supports us. Several people have offered to help with development, and several solutions have been proposed.

Requirements

• Collaboration. Easy for each author to work on the book, and combine the changes. No emailing Word files back and forth. Doesn't get in the way of writing.
• Flexible structure. Must be easy to modify the hierarchy by adding new sections (at any level) and rearranging/promoting/demoting existing sections.
• Markup which is good for publishing / typesetting, but doesn't get in the way of writing.
• Can export to HTML and PDF (for printing).

Things that would be nice to have (in rough order):

• Offline access.
• Solution exists, minimal extra coding.
• Edit in text editor of choice, ideally one that understand the markup language
• Can start right away - we have a limited amount of Will's time, and the sooner we can be writing in some system (even if it doesn't have all the features we want yet), the better.
• Import Markdown and/or HTML, as the current book is written in those formats.
• Version tracking. Can see previous versions and revert to them.
• Easy reviewer commenting on drafts.

Solutions

Markup Language

This will partly be driven by the environment, but...

• TeX or something that can be turned into TeX seems ideal. If Donald Knuth has solved a problem, we should probably use that solution.
• HTML is another option. The book is currently in HTML. It makes publishing to the web easier, but print harder, and print is our main goal for this edition. HTML can be translated to LaTeX (the beta version of the book is Markdown -> HTML -> LaTeX -> PDF) but it is somewhat messy.
• DocBook is a common format, but don't have any particular reason to use it.

Environment

Two main systems have been proposed:

Web based

The two examples are using the wiki or using Thiblo. These options get you:

• Central repository and change tracking (since they are accessed through a website to a database)
• Ease of publishing HTML version (since you are essentially developing on live webpages). However, not sure if you can customize the HTML with forward / next frames like you can when the HTML version is output by a script as in here
• Ease of commenting, for co-authors, reviewers, etc. (Wiki includes discussion pages, Thiblo includes sentence-by-sentence commenting)
• No simultaneous editing of the same page.
• Can edit from any computer with no setup, since it is browser-based.
• Flexible structure - we can control the structure through a master index page.
• Wiki can be customized to use Markdown. Thiblo seems to use some HTML tags, including some custom tags.
• A custom script could export LaTex or a PDF from a Wiki. Thiblo plans to add LaTex export as well.
• No offline access, AFAIK, so also no using a text editor. Have to use a browser, which adds one more layer of instability / abstraction / borders.
• Solution exists - Somewhat, requires some extra coding for our needs. Existing developer community for Thiblo, including people interested in seasteading who would be excited to modify it for our needs.

Version Control based

In this system, the book consists of a file for each section, located in a VCS such as svn or git. The files are written in a markup language like Markdown or TeX. Authors can edit independently, and sync / merge their changes. The book's order is controlled by a master index file listing the hierarchy of the files.

• Collaboration - yes, very easy, including simultaneous editing & later merging.
• Version tracking - yes.
• Flexible structure - yes. Can even do GUI by using OmniOutliner and XML export. Need a script to read it.
• Markup - whatever we want. Markdown, TeX, up to us.
• Export - Need to write scripts to do it, but can export to anything, incl. multiple targets
• Commenting - Nope, not unless we somehow export to Thiblo.
• Offline access - Yes, version control works great with offline access.
• Text editor - Yes, can use any text editor, and there are many that support Markdown and LaTeX.
• Solution exists - Somewhat (VCS exist, markup languages exist), but will require some extra coding for our needs.
• Have to set up environment on each computer that will be working on the book (install VCS, etc.)

Thoughts

Summary

Thiblo: Thiblo is currently the most developed, but does not seem as suited for our needs. It supports strongest commenting features, and has an existing developer community. Downsides are that HTML, rather than TeX is the native language, it has no merging, and because it is web-based there is no offline access and a browser must be used to edit rather than a text editor.

VCS: Since our focus is on collaborative writing of a book for print, rather than annotation or publishing HTML, this system seems closer to our desired goals and workflow. It is the most flexible since our text files can be in any format we want, and we can write custom scripts to parse markup languages and generate multiple output formats. We can get started just writing into text files right away, but it will require some coding to produce any complete documents (combining sections and with markup processed). It also fails to make use of an existing developer community which is sympathetic to seasteading.

Patri's thoughts

Personally I find using git, TeX, and custom scripts the most attractive, because I like offline access and being able to use a text editor instead of a browser for editing (one less layer of abstraction). As Will pointed out, the fundamental goal of this book edition is to be a printed book (TeX -> PDF), not a commentable webpage. Maybe export to Thiblo when getting feedback from reviewers.

Workflow

Thiblo: Just fire up the web browser, go to the journal, find the article you want to edit, and edit it in the browser. Give feedback on co-author's writing via annotations. Save when done. Automatically available on website. Not sure how we get other versions like PDF - run a custom script, presumably.

VCS: Sync local copy of book, merging any changes. Edit whatever articles in a text editor which understands the markup language. When happy with result, submit it to the repository. There is a copy of the repository which is watched by scripts, whenever there is a checkin, they generate a new version of a page-per-section version of the document, with headers/footers that link to indices and next/last pages (like the past HTML versions of the book), as well as generating new LaTeX/PDF versions of the full book.

Developers

Several people offered to help on Patri's LJ posts: [1] and [2]:

• jon_leonard, especially if it is LaTeX based.
• proctologiste
• nots2good
• sanityjihad
• hodja - thiblo developer
• baldvin - thiblo developer