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