[gdal-dev] About -oo -lco -dsco in docs

[Even Rouault]

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 at lists.osgeo.org
> https://lists.osgeo.org/mailman/listinfo/gdal-dev

-- 
http://www.spatialys.com
My software is free, but my time generally not.