"First Steps🔗" is missing info how to obtain .opl file

[matkoniecz]

https://docs.osmcode.org/pyosmium/latest/user_manual/01-First-Steps/ - I am assuming that it is for people with general osm knowledge but lacking any experience with pyosmium and osmium

But even after finding https://docs.osmcode.org/pyosmium/latest/user_manual/07-Input-Formats-And-Other-Sources/ and https://osmcode.org/opl-file-format/ linked from it I am still had no idea how to actually obtain .opl file.

It is also unclear for me why it is better. I guess that you can convert .pbf to .opl and guess that overall it is faster than just reading from .pbf? But I am not sure why not simply read .pbf - is it really much faster, enough to deal with extra complexity.

After extra hunting in docs: I guess that https://docs.osmcode.org/pyosmium/latest/user_manual/06-Writing-Data/ example can be inverted to read pbf and output opl?

But maybe in the very first example show it with .pbf file? These are much easier to obtain. Though maybe linking Geofabrik extracts would be still nice.

---

for suggested improvements:

Maybe something like

with osmium.SimpleWriter('luxembourg.opl') as  writer:
    for o in osmium.FileProcessor('luxembourg.pbf'):
        writer.add(o)

should be added as the first part of the introduction (note: I have no idea is it proper way to get opl file)? Or initially read from pbf and then proceed with pbf -> opl conversion and reading from opl?

---

(if that type of issue is unhelpful, please let me know or just ignore it - my intention here was to help with improving docs, but maybe bottleneck is elsewhere and this type of issues does not help at all)

[lonvia]

The opl file in question is part of the example data of the documentation. I shall consider adding an appendix that links the example files. The main advantage of .opl is that it is human readable, after all.

For a beginner it doesn't make a difference if the file is a pbf or opl or xml. It's all "some OSM data". To lift the confusion you see, we'd need a more in-depth description of all the file formats and the differences. Possibly something for the "Input Formats" chapter.