Perhaps a Sphinx substitution could be made with the relevant text and added to https://github.com/OSGeo/gdal/blob/master/doc/source/substitutions.rst
Dan On Wed, Mar 27, 2024 at 5:01 PM Even Rouault via gdal-dev < gdal-dev@lists.osgeo.org> wrote: > 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 >
_______________________________________________ gdal-dev mailing list gdal-dev@lists.osgeo.org https://lists.osgeo.org/mailman/listinfo/gdal-dev
