Feed-back and questions about documentation

[Mark Maker]

Hi,

When I do documentation of my own projects, I sometimes wish I had more feed-back, especially by greenhorns, capturing their so very important "first impressions". So here I am being a greenhorn in meson, and I'm trying to give that feed-back.

But first let me tell you that 95% of the doc is already outstanding, so what I'm trying here, is merely contributing on top of all that, in what modest way I can, as a greenhorn, by definition.

1. When reading through the Manual sequentially, to learn from scratch, I was completely crashed by the Cross and Native File reference and Persistent native environments sections. Suddenly a new syntax? I can only guess that they come way too early and lack a proper intro, for why and where you would need them, and why they use the .ini syntax. Now knowing more, I also wondered why they aren't just general-purpose response files, so one could simply save sets of meaningful/recommended meson command-line options, like e.g. one per supported build-type.
   
2. Unless I missed something, the subdir() function is never properly introduced.
3. Do I need to use subdir() if I don't like its strange lack of scope? Or can I do everything from the top, using relative paths? Is there a difference in the way things are then built or installed? Downsides I should know?
   
4. It would be nice to have a more in-depth example come earlier, with header files, libs, perhaps one installed, one not. The one here is not bad, but ideally it would also explain the non-installed headers/libs.
   
5. I was completely unsure if you had to add header files to the targets, to detect build dependencies. Turns out this is handled automatically by Ninja (and I assume by the other back-ends as well). This should be mentioned early (took me hours to find that particular FAQ). This is somewhat similar as an end-user benefit to globs (that aren't supported), so it should be mentioned, that it does work with headers.
   
6. I'm still wondering how default-options can be made built-type specific. For instance, I would like to make b_lto only active (by default) in release builds.
   

Hope this is helpful.

_Mark