Thanks for these helpful issues @Nowosad !

1. Yes, definitely. Haven't had time to do documentation at all, and if moreover, I should start with documenting the code itself first.
2. Good point! What do you think of tm_lp? As you may have guessed, the lp stands for legend position. Do you have other alternatives as tm_legend_position_out is probably a bit too long?
3. No, that is an (understandable) misunderstanding: in the current framework, there is still room for a tm_layout, but a little differently from a developers perspective:
   History: tm_layout existed before there tmap_options, and even before there was a view mode. The idea behind tmap_options was (and still is) that users should be able to set layout settings globally. However, as tmap matured, more and more options were added, including options that were not (directly) related to the layout. I introduced tm_view to set options that were (only) related to the view mode. But even then there were still options that had nothing to do with layout (e.g. max.raster and show.warnings.)
   v4 idea: there will be a tm_options, by which users are able to set any tmap option, so identical with tmap_options. However, tm_options is meant for experienced users, simply because many options are quite complex (and cannot be made easier due to the complexity of the tmap framework). That is exactly the task of user-friedly wrapper functions such as tm_place_legend_left. Also tm_layout will be a wrapper of tm_options. I expect that it will be used the same as in v3, but only with the relevant arguments (regarding titles, panels, background color, frame, etc). The options such as the default palettes (aes.palette) will be deprecated and only available via tm_options (in another form since the whole framework has changed under the hood).
4. In a facet grid, there are rows and colums. A scale can be applied for 1) each facet 2) each row, 3) each column and 4) all facets together. I will elaborate more in this in our video call. Probably this feature will not be used often.
5. Yes, brewer.greens work, but the philosophy behind tmap_pals$pals.brewer$brewer.greens is that users can browse through the palettes using RStudio's auto-completion. I am not completely happy yet with the color system in tmap v4. For instance the palette "Greens" will refer to the hcl one and not the ColorBrewer one. The fact that they use slightly different colors is not a big issue, but the fact that the hcl palettes start with the dark color is a big issue for backwards compatibility. Ideas on this are welcome.
6. inner.margin is between the map and the frame, outer.margin is between the device edges and the plot area. meta.margins are the margins that are used for the "meta data", most importantly the legends.

1 The meta.margins are set automatically based on the occurrence of legends, however not on the content of the legends themselves (which is too complicated). I still have to play around with the default settings. I don't have implemented landscape legends yet (of course I will). The availability of landscape legends will make it possible to use the space more efficiently. For example: if the aspect ratio of the device is larger (so more landscapish) than the bounding box, then place the legends at the bottom. If (in that case) the aspect rations are not very different, use landscape legends (stacked vertically), and otherwise (so if there is much room below the map) use portrait legends stacked horizontally.

2 a) good idea to add ticks. b) will do (once implemented)

Thanks for all of the explanations.

2. Good point! What do you think of `tm_lp`? As you may have guessed, the lp stands for legend position. Do you have other alternatives as `tm_legend_position_out` is probably a bit too long?

tm_legend_in() and tm_legend_out() comes to my mind as possible alternatives...

3. No, that is an (understandable) misunderstanding: in the current framework, there is still room for a `tm_layout`, but a little differently from a developers perspective:
   **History**: `tm_layout` existed before there `tmap_options`, and even before there was a view mode. The idea behind `tmap_options` was (and still is) that users should be able to set layout settings globally. However, as tmap matured, more and more options were added, including options that were not (directly) related to the layout. I introduced `tm_view` to set options that were (only) related to the view mode. But even then there were still options that had nothing to do with layout (e.g. `max.raster` and `show.warnings`.)
   **v4 idea**: there will be a `tm_options`, by which users are able to set any tmap option, so identical with `tmap_options`. However, `tm_options` is meant for experienced users, simply because many options are quite complex (and cannot be made easier due to the complexity of the tmap framework). That is exactly the task of user-friedly wrapper functions such as `tm_place_legend_left`. Also `tm_layout` will be a wrapper of `tm_options`. I expect that it will be used the same as in v3, but only with the relevant arguments (regarding titles, panels, background color, frame, etc). The options such as the default palettes (`aes.palette`) will be deprecated and only available via `tm_options` (in another form since the whole framework has changed under the hood).

It makes a lot of sense. I like this trimming of tm_layout().
Two additional things: (1) why tm_place_legend_left and not tm_place_legend("left"), and (2) are you not afraid that making similar functions, such as tm_lp_inset and tm_place_legend_left could confuse users? Would it be possible, for example, to just have, e.g., tm_legend_in("left") or tm_legend_in("left", "top") which would work similar to both tm_lp_inset and tm_place_legend_left (the latter function could be then removed)?

(using it as placeholder for the vignette)

T.b.c.

I've updated the vignette. Please take a look @Nowosad I made some minor changes, so the code in main.r and main2.r may not work anymore (haven't tested yet).

As a user, I find tm_place_legend_left easier (i.e. faster) to type (using auto-completion) then tm_place_legend("left"). But we can easily change this.

We already have the tm_legend_ functions, which currently include tm_legend_landscape, tm_legend_portrait, tm_legend_hide, and tm_legend_combine, so tm_legend_in and tm_legend_out might be confusing, at least for the legend position argument. We can also decide to put tm_legend_in on a similar level as tm_legend_landscape, but then we'll also need cross-categories, e.g. tm_legend_landscape_in.