[mapserver-dev] Versioned MapServer Docs?
Seth G
sethg at geographika.co.uk
Fri Mar 19 03:05:43 PDT 2021
Hi all,
It seems like the consensus is to keep a single set of docs, so I'm wondering how we deal with removed keywords rather than deprecated. For deprecated keywords we have the following tag:
.. deprecated:: 5.0
For new keywords we have:
.. versionadded:: 6.2
We don't currently have a similar removed keyword (and there is no Sphinx directive [1]). LABEL ENCODING [2] uses:
.. deprecated:: 7.0
Removed. UTF-8 is now the encoding used by MapServer, and
data set encodings are handled using :ref:`LAYER` `ENCODING`.
But then it is unclear what version it was deprecated and what version it was removed. Perhaps simply adding "Removed in 7.6" would be sufficient, or alternatively create a custom directive?
I think we should still have a cut-off point for removing keywords from the docs completely. Maybe 6.0 (released in 2011)? Anything removed in 8.0 would still be removed in a 10.0 release?
Anyone using MapServer versions earlier than 6.0 are unlikely to be updating Mapfiles.
Seth
[1] https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html
[2] https://mapserver.org/mapfile/label.html#mapfile-label-encoding
--
web:http://geographika.co.uk
twitter: @geographika
On Fri, Mar 19, 2021, at 8:59 AM, Yves Jacolin wrote:
> Hello,
>
> From my point of view, I agree mostly with Jeff. Having both deprecated and added version is interesting even if we are using an older (or later) version of MS. I understand Even position though and may be we should remove too old deprecated version 4.x and 5.x are so old. 6.x release are probably still widely used.
>
> Thank you all!
>
> Y.
>
> Le ven. 19 mars 2021 à 00:31, Jeff McKenna <jmckenna at gatewaygeomatics.com> a écrit :
>> The user also wants to see ALL possibilities, not necessarily just for a
>> specific version. I know, software devs think a user just needs to know
>> what is available for that version that the user has installed, but
>> actually the user wants to know what is possible, and when it was added,
>> and then adjust the installation method if needed.
>>
>> I just see this as a typical difference in how software developers think
>> versus how a user thinks, and I don't mean this in a bad way, I just
>> think, from my experience, this is the constant challenge in managing
>> software (and why the person writing the code should never be the one
>> who documents it).
>>
>> -jeff
>>
>>
>>
>>
>>
>> On 2021-03-18 8:25 p.m., Jeff McKenna wrote:
>> > I also think here we have a difference between how a core developer
>> > works (on main, building from source) and then how a typical software
>> > user works (using a binary/package built by someone else, often a much
>> > older MapServer version), so those one-line notes of version added
>> > (which is absolutely irrelevant to a core developer who uses the latest
>> > source each day) become what I would call a total "lifeline" to a user,
>> > so they can know what parameters work with their old installed package.
>> >
>> > -jeff
>> >
>> >
>> >
>> > On 2021-03-18 8:18 p.m., Jeff McKenna wrote:
>> >> As a user I'm constantly relying on those 'added in 5.0' notes, this
>> >> is the information that a user needs and craves in the actual user
>> >> document (not separate deep in an RFC document). I see these version
>> >> notes (a single line that is nicely color coded often) as always
>> >> relevant, as users need to know when a parameter was added (and
>> >> especially those ones that aren't always fresh & mentioned, such as
>> >> old 5.0 ones etc).
>> >>
>> >> -jeff
>> >>
>> >>
>> >>
>> >>
>> >>
>> >> On 2021-03-18 7:23 p.m., Even Rouault wrote:
>> >>> My point was too much (no longer relevant) information kills
>> >>> information. For the user of Mapserver 7.6, what's the point in
>> >>> seeing some feature was added in 4.0 or removed in 5.2 ? That just
>> >>> adds to the cognitive load. It might be useful though to see that
>> >>> something was added / removed recently and you don't benefit yet from
>> >>> it or are dependent on it.
>> >>>
>> >>> Le 18/03/2021 à 23:17, Richard Greenwood a écrit :
>> >>>> As a guy who has been reading the mapserv docs for 20+ years I'll
>> >>>> say that I love the format of the docs in general and specifically
>> >>>> the version added, version deprecated, etc. Thanks Jeff and all the
>> >>>> other contributors. Hopefully I'll be reading the docs for another
>> >>>> 20 years.
>> >>>>
>> >>>> Rich
>> >>>>
>> >>>>
>> >>>> On Thu, Mar 18, 2021 at 3:18 PM Jeff McKenna
>> >>>> <jmckenna at gatewaygeomatics.com
>> >>>> <mailto:jmckenna at gatewaygeomatics.com>> wrote:
>> >>>>
>> >>>> Ah ok Even, your words sunk into me more now, good points.
>> >>>> Although I
>> >>>> differ in that I think keeping all of the 'versionadded'
>> >>>> references are
>> >>>> very important, as this is the rich information that is so
>> >>>> priceless
>> >>>> (knowing when exactly something was added) for both the users and
>> >>>> maintainers of the software/docs. I personally have been making
>> >>>> sure to
>> >>>> add those 'versionadded' and 'deprecated since' and 'since version'
>> >>>> notes into the docs, as this information is so useful to users,
>> >>>> even in
>> >>>> the case of it being added in 5.0 etc. And as you said, I have
>> >>>> to go
>> >>>> get that information in the RFC, which users won't know to
>> >>>> check, so
>> >>>> I've been adding those 'since version' references that you
>> >>>> mention, to
>> >>>> help users.
>> >>>>
>> >>>> -jeff
>> >>>>
>> >>>>
>> >>>>
>> >>>> On 2021-03-18 5:39 p.m., Even Rouault wrote:
>> >>>> > If we keep a single version for simplicity, we could however
>> >>>> decide to
>> >>>> > clean up a bit the doc content to remove mentions of outdated
>> >>>> versions
>> >>>> > to avoid cluttering it. There is little point in mentioning any
>> >>>> version
>> >>>> > older than let's say 5? years ago. I've done that a bit in the
>> >>>> GDAL docs
>> >>>> > a few months ago, removing any mention of GDAL < 2, considering
>> >>>> that all
>> >>>> > people looking at the docs would have at least GDAL 2.x something
>> >>>> > available, or if they use antiquated stuff, too bad for them.
>> >>>> >
>> >>>> > Looking a bit at download artifacts, for MapServer we could
>> >>>> decide for
>> >>>> > example that the baseline is MapServer 6.4 (or possibly even 7.0
>> >>>> for
>> >>>> > simplicity), and remove any mention of that or older versions
>> >>>> (except in
>> >>>> > RFCs that are reflective of history)
>> >>>> >
>> >>>> > "grep -r versionadded en" in the doc repository shows a number
>> >>>> of things
>> >>>> > of the 4.x, 5.x or early 6.x eras. 'grep -ri "since version"
>> >>>> en' shows
>> >>>> > also a number of potential cleanups.
>> >>>> >
>> >>>> > Even
>> >>>> >
>> >>>> > Le 18/03/2021 à 21:15, Jeff McKenna a écrit :
>> >>>> >> My preference has always been for Option#1, as it is much
>> >>>> easier to
>> >>>> >> maintain in my experience, as it is stated clearly as
>> >>>> deprecated at
>> >>>> >> the parameter level in the document.
>> >>>> >>
>> >>>> >> Speaking openly here, if I was paid fulltime to manage the docs
>> >>>> and
>> >>>> >> all the different build versions of the docs, and publishing
>> >>>> them
>> >>>> >> online, I could see how that would be possible; but as we are
>> >>>> made up
>> >>>> >> of volunteers, I would prefer to keep the single version
>> >>>> updated with
>> >>>> >> references to when the feature was added (what MapServer
>> >>>> version), and
>> >>>> >> if it is deprecated. I remember recently spending much effort
>> >>>> on that
>> >>>> >> in-line versioning improvements, I think that is working nicely
>> >>>> now.
>> >>>> >>
>> >>>> >> -jeff
>> >>>> >>
>> >>>> >>
>> >>>> >>
>> >>>> >>
>> >>>>
>> >>>>
>> >>>> -- Jeff McKenna
>> >>>> GatewayGeo: Developers of MS4W, MapServer Consulting and Training
>> >>>> co-founder of FOSS4G
>> >>>> http://gatewaygeo.com/ <http://gatewaygeo.com/>
>> >>>> _______________________________________________
>> >>>> mapserver-dev mailing list
>> >>>> mapserver-dev at lists.osgeo.org
>> >>>> <mailto:mapserver-dev at lists.osgeo.org>
>> >>>> https://lists.osgeo.org/mailman/listinfo/mapserver-dev
>> >>>> <https://lists.osgeo.org/mailman/listinfo/mapserver-dev>
>> >>>>
>> >>>>
>> >>>>
>> >>>> --
>> >>>> Richard W. Greenwood, PLS
>> >>>> www.greenwoodmap.com <http://www.greenwoodmap.com>
>> >>>>
>> >>>> _______________________________________________
>> >>>> mapserver-dev mailing list
>> >>>> mapserver-dev at lists.osgeo.org
>> >>>> https://lists.osgeo.org/mailman/listinfo/mapserver-dev
>> >>>
>> >>> --
>> >>> http://www.spatialys.com
>> >>> My software is free, but my time generally not.
>> >>>
>> >>>
>> >>> _______________________________________________
>> >>> mapserver-dev mailing list
>> >>> mapserver-dev at lists.osgeo.org
>> >>> https://lists.osgeo.org/mailman/listinfo/mapserver-dev
>> >>>
>> >>
>> >>
>> >
>> >
>>
>>
>> --
>> Jeff McKenna
>> GatewayGeo: Developers of MS4W, MapServer Consulting and Training
>> co-founder of FOSS4G
>> http://gatewaygeo.com/
>> _______________________________________________
>> mapserver-dev mailing list
>> mapserver-dev at lists.osgeo.org
>> https://lists.osgeo.org/mailman/listinfo/mapserver-dev
>
>
> --
> Yves Jacolin
> Training and support manager - Team Manager
> Camptocamp
>
> Tel (France) : +33 4 58 48 20 43
> Tel (Switzerland) : +41 21 619 10 43
> Mob. : +33 6 18 75 42 21
>
> email : yves.jacolin at camptocamp.com
> http://www.camptocamp.com
> _______________________________________________
> mapserver-dev mailing list
> mapserver-dev at lists.osgeo.org <mailto:mapserver-dev%40lists.osgeo.org>
> https://lists.osgeo.org/mailman/listinfo/mapserver-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/mapserver-dev/attachments/20210319/b5dab765/attachment-0001.html>
More information about the mapserver-dev
mailing list