Voyager Support

From NikiWiki
Jump to: navigation, search

Voyager is a very complex project and it can only be successful when everyone contributes as good as possible. To make it easier for you to join the project, we defined some jobs where you might be able to help.

Documentation

Good documentation is an important part of Voyager. For various reasons we decided to do the documentation in DocBook. This is an XML based format used for many publications. O'reilly books are done with that too. Many other open source projects use this format as a base. It allows us to create any kind of output out of it, like HTML or PDF but also more in the future.

The drawback is that it takes some time to get into DocBook, in the beginning it is easier to use a WYSIWYG application like OpenOffice.org to create the document. Currently two Voyager developers write their documentation in OpenOffice.org.

So, one help would be to keep The Design of Voyager up to date with the OpenOffice.org documents of the two developers. Besides this, one might also work on an 'Easy way to use DocBook on eCS'.


DocBook Editors

At this time of writing, the following options are available to edit DocBook in an easier way:

  • Eclipse with the Vex and XMLBuddy plugin. Vex is open source and XMLBuddy is free in the entry version which is enough for our needs. Unfortunately we do not have an Eclipse port for eCS yet so this requires to work on one of the supported Eclipse platforms right now.
  • XMLmind, a standalone Java based XML Editor which seems to support DocBook as well. According to the requirements this should work on eCS but we did not test that yet. It would be nice to set up a package that can be easily installed on eCS.


At Warpstock Europe 2005 there was also a presentation about DocBook on eCS by Jarda Kačer and Jirka Kosek. It would be a good idea to work together with those guys to get that up and running on eCS as well.

DocBook Syntax

The best way to learn DocBook is to have a look at the current book, most of the needed tags are probably already used once. Besides this, one should have a look at DocBook: The Definitive Guide, which is available online or as HTML download.

Some remarks:

  • Use xref whenever possible to create a reference to another part of the document. This makes reading the book much more interactive.
  • For images one should use PNG versions for the web release and PDF for the PDF edition of the book. See the mediaobject example in Chapter 3. Please make sure that the PNG versions use a size that makes sense for web publishing. We did not do many tests on PDF yet. We have to see how this works regarding scaling.
  • We use Subversion to keep a history of the document, this also means that the structure of the document should not change unless there is new content. Because of its XML nature, every editor will use its own indenting for the file. The only valid format to commit to Subversion is the indenting of Vex. So, in case your editor changes the layout, please make sure that Vex did format it before it gets committed, otherwise we get very big changesets!
  • There is an additional DOCTYPE declaration in each chapter, the XSLT for transforming it does not like that because it is also defined in book.xml. To create the HTML and the PDF version of the book this line gets stripped out automatically by the build process before the document is transformed.
  • Do not worry about the online versions, they are done by some scripts. Just make sure your own copy builds correctly in HTML before you commit it.
  • Do not forget to commit images as well to the Subversion, in case you added some.

Building DOV on OS/2

Fix me :-)


ToDo

This is a list of documents that need maintenance.

The Design of Voyager

Netlabs Object Model

Desktop

Triton

Object-Oriented Interface Design (CUA)

This is the book written by IBM back in the early nineties, the original title was

  • Object-Oriented Interface Design - IBM Common User Access Guidelines ISBN 1-56529-170-0

We never found a PDF version of this book, just a very poor online HTML version. With the help of some scripts we assembled a standalone version of this book. Unfortunately the HTML syntax is very poor and the book lacks the images. Good for you because you can help us with that ;-)

  • Get the recent version of this book in our Subversion
  • Install NVU and open the xhtml file.
  • Start to clean it up. The syntax should look like in the beginning, very simple but clean XHTML code, as few br as possible, h1, h2 for topic formating and p for paragraphs.
  • Kill all table of contents and such things in the XHTML version. We will transform the XHTML to DocBook in a second step and DocBook will take care of that.
  • And if you are brave enough to try to reproduce the images, at least those that make sense. This book is still available second hand, use that as a reference. It would greatly help us if someone finds a PDF version of the original document (in case that exists). It might get pretty tricky to reproduce some of the images because IBM created some sample applications for it, use what makes sense to you. For sure the images should be taken from a recent OS/2 or eCS system.