Salut Thomas,
There's a tension between being clear to users, and also aiming at being
concise / not repeating us too much (we have already one thousand pages
of doc to maintain), and if we need to repeat, find the technical way of
doing it without actually having to copy&paste&maintain the same text.
Probably a solution could be to have under each "Open options"
paragraph, and introduction sentence like
"Consult :ref:`how to specify open options <open_options>` with command
line utilities and the API." that links to a page explaining the concept
and how to use it.
I was wondering if we'd just want to copy&paste that sentence at all
relevant places, or create a custom Sphinx extension for a directive
that would do that. The later is probably overkill. Possibly a one-time
simple Python script could automatically insert that at relevant places
Even
Le 26/03/2024 à 21:25, Thomas Gratier via gdal-dev a écrit :
Hi,
There are implicit rules when you read the OGR/GDAL docs in fact, in
particular when you use `ogr2ogr` or `ogrinfo`
`-oo <NAME>=<VALUE>` like "Open Options"
`-lco <NAME>=<VALUE>` for "Layer Creation Option"
`-dsco <NAME>=<VALUE>` for "DataSet Creation Option"
So, when you read for instance
https://gdal.org/drivers/vector/csv.html, you will see there is a
section "Open options" so you will know that you can use `-oo`. Also,
you will see a "Layer Creation options" block so again, you will know
it mean use `-lco`.
It's documented in "ogr2ogr" but you need to know the rule to make the
link in your mind when reading the doc. Any idea to clarify the doc
about the "tip".
An idea could be about adding in drivers docs "Open options" block a
sentence like "When using the command line, use the flag `-oo
<NAME>=<VALUE>`" and do the same for "Layer creation options" block
"When using the command line, use the flag `-lco <NAME>=<VALUE>`"
Thoughts about the suggestion? Better idea? Not worth?
Regards,
Thomas Gratier
_______________________________________________
gdal-dev mailing list
gdal-dev@lists.osgeo.org
https://lists.osgeo.org/mailman/listinfo/gdal-dev
--
http://www.spatialys.com
My software is free, but my time generally not.
_______________________________________________
gdal-dev mailing list
gdal-dev@lists.osgeo.org
https://lists.osgeo.org/mailman/listinfo/gdal-dev
