[LV2] LV2 Plugin Documentation

[David Robillard]

On Sun, 2018-05-20 at 12:39 -0400, Mark D. McCurry wrote:
> What might this look like?
> 
> http://fundamental-code.com/tmp/lv2book.html is my (very very rough)
> stab at shifting the organization, complexity, and tone.

This is clearly much better, but of course it is.  The reason the book
is compiled from examples is because we need examples anyway and I did
not have time to actually write a book :)

That said, I do think the code parts in such a thing should remain
directly associated with real, actual, functioning code.  For a few
reasons:

 * Prevent things from rotting over time (code in documentation that
   doesn't work is a build error, as is changing the code in a way that
   breaks the book)

 * Address the many people who actively want code examples, and not a
   tutorial, with the same effort.

So I'm wondering if we can do some generator glue magic to make this
happen.  So each example/chapter is human-written prose like you've
done here, but it can refer to snippets in the code which would be
displayed inline (i.e., same output that you have here, but without the
copy/paste and inevitable rot problem).  Maybe something like, from
your first example (borrowing some Doxygen syntax because why not):

/**
  @name PortIndexDefinition
  @{
*/

typedef enum {
    AMP_GAIN,
    AMP_INPUT,
    AMP_OUTPUT
} PortIndex;

/** @} */

and the ability in the prose to do things like:

We can define a short enum to keep track of them:

<snippet:amp.c#PortIndexDefinition>

(or whatever syntax makes sense, nothing existing for this comes
immediately to mind)

?

It's a wee bit of noise in the code itself, but not enough to be
terribly problematic, I think.  Each chapter, at the end, could of
course link straight to the sources (not inline).

The general idea being, have the book written like a coherent document
as you've done here (rather than literate code), but keep the
advantages of the code being real.

-- 
dr