[LV2] LV2 Plugin Documentation

[David Robillard]

On Mon, 2018-05-21 at 09:32 -0400, Mark McCurry wrote:
> 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 100 line Python script is hardly rocket science.  Few hours work,
maybe.

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

I prefer Markdown, really, less ugly, more supported, and everybody
knows it, but asciidoc was convenient for some reasons.

>  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),"

This would work, but specifying line ranges would be ultra fragile and
break constantly.  That's more than bad enough of a long term problem
to justify a custom preprocessor for this if we really need one, IMO.

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

Blech.  Flat page or bust.

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

Whatever works, really.  Personally I think embedding complete source
code seems pretty contradictory to the sort of documentation you seem
to be shooting for, particularly when you can link to it to be shown in
something that would do a much better job (with syntax highlighting and
whatnot) anyway.

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

I'd strip the literate style comments from the source if this actually
happens, and just leave more typical sparse comments.

-- 
dr