[mapserver-dev] MapServer docs and index updates

[Jeff McKenna]

Hi Seth,

Linux linefeeds are recommended for the docs.  I had used a commandline 
setting to default to that, I believe it was:

   git config --global core.autocrlf input

and also

   git config --global core.autocrlf false

(but those settings may have changed since)

-jeff




On 2020-05-11 11:35 a.m., Seth G wrote:
> Hi Jeff,
> 
> I'll make all the future index directives updates to the 7-6 branch.
> I'll be updating the files with a script. I've noticed there is a mix of Windows and Linux linefeeds (both CRLF and LF) in the mapfile pages. If I rewrite the files with a script then it would be easiest if I can use a single style of line endings.
> Is there a preference/default for line endings for the docs?
> 
> Seth
> 
> --
> web:http://geographika.co.uk
> twitter: @geographika
> 
> On Mon, May 11, 2020, at 1:07 PM, Jeff McKenna wrote:
>> No problem to include.  Please make your doc PR to branch-7-6.
>>
>> (you'll also notice my recent many commits to the docs, which now
>> require a minimum of Sphinx 3.0, and updated our documentation guide
>> accordingly for that requirement)
>>
>> thanks!
>>
>> -jeff
>>
>>
>>
>> -- 
>> Jeff McKenna
>> MapServer Consulting and Training Services
>> http://gatewaygeo.com/
>>
>>
>> On 2020-05-10 6:58 p.m., Seth G wrote:
>>> Hi list,
>>>
>>> I have added a pull request at https://github.com/mapserver/docs/pull/324 and would appreciate any feedback or objections to proceeding with adding a `:name:` to all the Mapfile index directives. I've included the text from the pull request below.
>>>
>>> In summary all index directives would be updated from:
>>>
>>> ```
>>> .. index::
>>>       pair: CLASS; BACKGROUNDCOLOR
>>> ```
>>>
>>> to:
>>>
>>> ```
>>> .. index::
>>>       pair: CLASS; BACKGROUNDCOLOR
>>>       :name: mapfile-class-background
>>> ```
>>>
>>> Links in the index will then change from https://mapserver.org/mapfile/class.html#index-1 which can change to a fixed URL - https://mapserver.org/mapfile/class.html#mapfile-class-background
>>>
>>> This would form part of the updates to the MapScript API documentation updates - see [here](https://github.com/mapserver/mapserver/pull/5870). Named index options allow an HTML link to be added from the MapScript docs to the relevant Mapfile keyword.
>>>
>>> I've asked a [question on StackOverflow](https://stackoverflow.com/questions/61666809/parse-and-write-rst-using-docutils) to see if it is possible to automate it with docutils, but otherwise it will be a manual/parse/regex approach.
>>>
>>> I added the `:name:` option to Sphinx as part of the version 3.0 release with [this pull request](https://github.com/sphinx-doc/sphinx/pull/7087), mainly for this use case. The docs for the option [are here](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-option-index-name).
>>>
>>> I've created the pull request against master, but can make it against 7.6 if appropriate, and update the remaining Mapfile index directives.
>>>
>> _______________________________________________
>> mapserver-dev mailing list
>> mapserver-dev at lists.osgeo.org
>> https://lists.osgeo.org/mailman/listinfo/mapserver-dev
> _______________________________________________
> mapserver-dev mailing list
> mapserver-dev at lists.osgeo.org
> https://lists.osgeo.org/mailman/listinfo/mapserver-dev
> 


-- 
Jeff McKenna
MapServer Consulting and Training Services
http://gatewaygeo.com/