RFR: Add jextract guide [v6]

[Maurizio Cimadamore]

On Mon, 15 Apr 2024 13:52:07 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> doc/GUIDE.md line 79:
>> 
>>> 77: [libclang](https://clang.llvm.org/docs/LibClang.html) native library in order to parse C sources).
>>> 78: 
>>> 79: ### Preprocessor Definitions
>> 
>> IMHO both this and the following section is not important enough to appear so early in the document. If we went straight to "Using The Code Generated By Jextract" we would not lose anything - then after that section, we can provide more details about various aspects/options.
>
> Not sure... I know what you mean, but knowing how to run the generated code seems fairly important. It seems that that is something someone might want to try out after the first example. Unfortunately, this requires understanding library loading, which is fairly complex.
> 
> Also, the comment about feeding jextract the right header file seems pretty important since user may run into errors when running jextract otherwise (we've seen many questions about that, e.g. when someone tries to extract some arbitrary Windows header instead of `Windows.h`).
> 
> But also, I realized that this guide may not just be used by first-time readers, but also as a reference by more experienced users, in which case it seems nice to have info about command line flags mostly in one place.

While it's true that knowing which header to extract is important, I think having a whole section on "preprocessor definitions" feels like having a very cornery section in a place where in reality you want something more general. E.g. extracting windows.h is tricky, because of order dependencies, but I'm not sure the user needs to be aware of -D here. Just mentioning that headers are complex beasts and can depend on each other in unpredictable ways (and refer to the doc of the library that needs to be extracted) should be good enough guidance at this point.

As for library loading I'm not sure... again, yes, we probably need to say something like "you need to ensure the library you want to call is loaded first" - but I'm not sure we need the full shebang of library loading options. In other places you added references to stuff that is further expanded upon in later sections - e.g. 


Besides these options, it is also possible to filter the output of jextract using one of the --include-XXX options that jextract has. See the section on [filtering](https://github.com/JornVernee/jextract/blob/Guide/doc/GUIDE.md#filtering) for a more detailed overview.


Seems like something similar is required here.

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

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