[LV2] Lost due to no documentation on writing LV2 hosts

[Mark D. McCurry]

On 05-06, Juan Linietsky wrote:
>   In any case, again, my point is to humbly request documentation about
> this.  I'm sure someone experiencedcan put something together in an hour
> and it would save me and future host implementers a huge amount of time.

As I stated in IRC the other day I'm very very skeptical that the sort
of documentation that you're requesting would take an hour.
I think something much more realistic would be 15-40 hours including the
writing, adjustment of examples, editing, getting feedback, and more
revisions.

On 05-06, Harry van Haaren wrote:
> I understand nobody has infinite time - but if you're really under time
> pressure think about if LV2 is really the right thing to ramp-up and learn
> about.

That ramp up time is the core issue here as it doesn't really need to
exist if a single document is written. (IMO at least)

On 05-06, Juan Linietsky wrote:
> it's still not enough for me to "connect the dots".  I know it works
> great for copying and pasting some code and getting something to work even
> if the full API is not clear. Unfortunately for hosts this won't do.

LV2 has documentation as well as the libraries needed to use LV2 from
the host and plugin perspective.
The key issue here is that there isn't good documentation stitching all
the details together for newcomers.
That issue does create a challenge for adoption as Juan stated via

>you are just making people not even considering spending time with it.

So, what sort of documentation am I talking about?
I think there should be 1 article/guide which walks through the creation
of a LV2 host basically dissecting existing example hosts along the way.

The guide should:
- Introduce the libraries needed to use LV2.
- Introduce the core concepts of LV2 plugins specifically *at the level
  of abstraction the host sees*.
- Provide many links to the specifications when relevant as well as
  example hosts
- Introduce the structure of a LV2 host in a layer-by-layer process
  introducing the LV2 core concepts in a well reasoned ordered sequence.
- Provide executable code examples which build up to something between
  lv2file/lv2apply and jalv at the end of the guide
- Establish how people should obtain all LV2 dependencies on common
  platforms (even if this seems simple)
- Introduce the concept of extensions, but not delve too deeply.
- Tie together the available resources into a cohesive story


The guide needs to make someone who has never made a plugin host for any
API comfortable with loading and running *basic* LV2 plugins including
the example plugins included within the lv2plug.in URI namespace.
This sort of document would be as much of a marketing tool to developers
as a general guide and could help adoption IMO.
At the end the reader should have a reasonable grasp of what the core
concepts of LV2 are which will enable them to make use of other already
written resources.

I'll reiterate and say that LV2 does have documentation, but the
existing documentation is much more usable once you have a general feel
for the ecosystem and core concepts down.
Example hosts are great, but context can improve their usefulness to
other devs a ton.

Rather than just throwing that out there and leaving, here's a very
rough skeleton of how I'd expect such a document to feel like:
http://fundamental-code.com/tmp/lv2-host-perspecitive.html

--Mark
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 455 bytes
Desc: not available
URL: <http://lists.lv2plug.in/pipermail/devel-lv2plug.in/attachments/20180506/501b6e95/attachment-0001.sig>