highlight the flex output in the manual

[etienneJr]

Hi! Here is my feedback on my discovery of osm2pgsql a few weeks ago. Someone told me it would suit for my project, so I came along and followed the manual.

Before chapter 6, there is no mention that pgsql output is deprecated. There are a few mentions of flex output, but it appears to be a complicated option for experts. In fact I hadn't even understood what an output was, as the explanation doesn't come until part 5.7. (English isn't my mother tongue, which may explain why I missed some of the information)

My progress has been as follows:

• I followed part 3 to prepare the database,
• I quickly read part 4 (perhaps too quickly, as I didn't see much point in it for a beginner),
• I hurried to run the commands indicated in part 5.1
• to be able to look at the structure of the tables to understand how the data was organised
• I looked up how to customise, and in part 5.7 I only saw the line in the table which describes the -S option without mentioning the flex output
• From then on I didn't use the manual (so I did not read parts 6 and 7). I just used the default.style file, and it doesn't mention the flex output either...

Given this progression, I was convinced that the pgsql output (which I didn't know was called as such) was the only possible output, and that all the customisation possibilities were in the .style file. I'd seen the warning in the log, but in those conditions I didn't understand what it was about.

So I think the manual should be rewritten to give much more emphasis to flex output:

• on part 5.1
  • add of a warning about the future depreciation of pgsql output (of the same type as those in parts 6 and 7)
  • give command line examples both with pgsql output and flex output.
  • explain that the pgsql command line examples are for initial testing only, and that you then need to move on to flex output.
• move part 5.4 to the beginning of part 5 so that people understand what middle and output are before running their first command. (and that there are 2 possible output modes).
• add a paragraph about flex output in the default.style and empty.style files to tell that it will allow much more flexibility.
• on part 5.7, in the table line -S, talk about flex output, explain that you can pass a .style or a .lua file

Today I'm convinced that I would have saved a lot of time if I'd understood the benefits and possibilities of flex output from the beginning. I find that the manual doesn't emphasise it enough. Without saying today that pgsql output is depreciated, the manual should at least give as much weight to flex output as to pgsql output.