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

[Daniel Baston]

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 at 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 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.
>
> _______________________________________________
> gdal-dev mailing list
> gdal-dev at lists.osgeo.org
> https://lists.osgeo.org/mailman/listinfo/gdal-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/gdal-dev/attachments/20240327/6f1b26dd/attachment.htm>