About

The Genode project has awesome potential for developers. I believe it would help realize that potential, if some very purpose-oriented programming documentation was created: a hands-on introduction to the API (not just doxygen output, but "friendly overview" style), some full fledged coding tutorials; someone mentionned indexing the Genodians.org contents, so added a placeholder for that as well.

In particular, the 'Genode Book' (thus named as a reference to the famous Be Book) would be especially important to have for an app developer like me, to 'get to grips' with Genode and its API.

This repository is purely my initiative and is not associated with Genode Labs in any way. With that said, I hope it will be of interest and get contributions from those who actually know the API and can fill me in!

Genode Labs does plan on having a 'book'/tutorials in the future. In the meantime, this can serve as experimenting grounds, or at least for me to get my bearings.

Getting started : browse (and edit) contents

• Genode Book API documentation
• Programming tutorials
• Genodians articles indexing

Or browse the whole list of wiki pages.

Cloning

fossil clone https://chiselapp.com/user/ttcoder/repository/genode-book genode-book.fossil
fossil open genode-book.fossil
fossil ui  # opens the user interface in e.g. FireFox

Meta

Why fossil?

Why choose ChiselApp.com and Fossil and its "fossil wiki" format?

I was looking for..

• presentation features (bold, italics..) and hyperlinks
• versioning/SCM, timeline
• easy to export/convert (fossil wiki export) if we ever migrate to something else than fossil
• decent ability to comment : click the "Append" button on any wiki page; or file a ticket; or use the discussion forum

And why not as well..

• editable both off-line... and on-line (not WYSIWYG, but all-in-one edition/rendering so good enough -- no need to juggle between editor/terminal/viewer)

Fossil gives us all that. I might still look into "pkgman search markdown" and such though, later.

However, beware the following "gotcha":

• fossil wiki has no merge conflict detection/handling: if A and B are editing a wiki and commit a new rev, if B commits after A, his changes will overwrite A's changes; if A notices his changes have been clobbered, he can retrieve them from the editing history and restore them, but still a PITA.
• that is, unless we move the data from the "wiki" to the "versioned files"

Why not genode-foundations-18-05.pdf ?

After getting started on this I looked again at the foundational PDF, remembering it includes not only the first high-level/abstract part but also the second "API" part, seemingly generated from doxygen inline comments. Looking at the Nitpicker, Audio, Filesystem ..etc chapters of the PDF I realized that this could be made to look more bebook-ish and cancel the need for this fossil project.. With some (a lot of?) work.

Here's my observations on the PDF, as an app programmer (not a systems developer!) :

• problem: the chapters are missing sample code. Solution: there should be either "links" to sample program to use, or in-line sample code, or both. Page 451 (8.14) is an example of sample code; there needs to be more; maybe not in every single chapter, but ideally at least in all "important" ones.
• problem: each class is described in turn, but you don't know which one is the class which does what you want and is of immediate interest to you; not being sure where to start, you get overwhelmed. Solution: there could be a short introduction at the top of each "group", to orient the reader to a sub-chapter; then there'd be e.g. a sizeable "Introduction" written to the Nitpicker chapter; same for Audio, same for filesystem. If said introduction includes some ready-to-compile sample code, it might even preclude the need to include some sample code in each of the subchapter dedicated to each class. This change would go hand in hand with:
• problem: the chapters of interest to typical programmers, are "buried" in breadth and in depth: Nitpicker is section 8.6.5 -- far down the top, and deep down; same for audio and filesystem. Thread, a base staple of all modern programs, is in 8.13.1 -- even farther down the top, and somewhat deep. The ordering seems to follow complexity, instead of application commonality (with most commonly used APIs at top, lesser used ones at bottom). Solution: re-order sections a bit, to be more along the expectations of app programmers; also dedicate bigger top-level groups of chapters to important topics (audio, files, windows..) rather than make them a single chapter below a parent group. Indeed looking forward to future expansions of the API, there might be e.g. many widgets to document some day, below nitpicker? (again, I'm not saying they will be related to nitpicker implementation-wise, but from the app programmer's standpoint that's where he will go to look for information, in the "graphical interface/nitpicker" chapter group :-)
• problem: some genode specifics are missing: on Genode, a C++ dev must not only know which C++ code to write and build, but also how to configure it with a .run file; there are a few .run snippets throughout the PDF, but not in the API / programmer 'handbook' part. Solution: provide not only C++ sample code, but also .run samples.

Tangeant remarks:

• if the above was implemented via doxygen, that would translate into a really big growth of inline metadata/comment, which would quickly overhwelm the .cc files/codebase; maybe the bulk of the doxygen comments should be moved to separate purpose-tailored .cc files, rather than the actual .cc files ?

• or maybe it makes sense to "outsource" such a high volume of documentation outside the genode tree outright, like is being done here? Wouldn't doxygen be a better candidate than wiki?