[LV2] LV2 Plugin Documentation

[Mark McCurry]

On Mon, May 21, 2018 at 6:25 AM, David Robillard <d at drobilla.net> wrote:
> 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 :)

Unless I'm mistaken it did also look like you spent some time writing the basic
literate programming code -> asciidoc transformer, so I imagine writing example
plugins and the source transformer was more fun than just writing old
fashioned docs.

> That said, I do think the code parts in such a thing should remain
> directly associated with real, actual, functioning code.  ...
> So I'm wondering if we can do some generator glue magic to make this
> happen.

Well, the original (and reworked) docs are in asciidoc and I've done exactly
what you're describing when making one set of docs for rtosc.
What you're looking for is tagged include directives:

https://asciidoctor.org/docs/user-manual/#include-directive

These "insert snippets of source code (so your examples are kept
up-to-date with the latest source files),"

> 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).

Yep, either that or an embedded box which shows ~10 lines + a scrollbar.
There might be a case for showing something closer to the full source for the
first example, but for the remaining examples I'd definitely stick
with your suggestion.

> 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.

Yep.
The code comments work fairly well when you're actually reading code
in a code editor,
so using snippets from the real code along with reasonable prose could
be the best of both worlds.

--Mark