RFR: Add jextract guide [v6]

[Maurizio Cimadamore]

On Mon, 15 Apr 2024 15:26:59 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> IMHO is not about moving "half sections", but about writing a section that is correct for the purpose and context in which it appears in the document. We seem to have two requirements for users getting started with jextract:
>> * explain that the header on which it is run matters (this can literally be one sentence)
>> * explain that libraries must be loaded (I think here we can get away by providing something that works in the 80% use cases, plus some comment on LD_LIBRARY_PATH, and refer everything else to a more specialized section. E.g. I don't think here we should be talking about different lookups, in which orders symbols are looked up etc.).
>> 
>> This way you can have a document that serves both "green" developers and more experienced one (the latter will want to keep going after the section illustrating how to use bindings). At least, IMHO.
>
> I gave this a try in the latest version. Still not sure which one is better, but I don't mind either way. I put all the sections after the examples in an 'Advanced' section as well.

I personally like the new changes a lot! I find the "running jextract" section very informative, providing all the major info w/o overstaying its welcome. Also it points to several other sections in the doc, so it acts a bit as a mental map, which is good.

I have some reservation about "unsupported features" being down in "Advanced" - should that be the last section in "Using jextract bindings" instead? (e.g. first we show what works, and then if the reader was expecting something else, we have a section for that too). Or, maybe pull it more "up front". Right now it seems kind of buried in other stuff, even thought it seems generally useful.

-------------

PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1565996431