[mapserver-dev] Versioned MapServer Docs?
Basques, Bob (CI-StPaul)
bob.basques at ci.stpaul.mn.us
Fri Mar 19 06:19:11 PDT 2021
Hmm, probably not contributing in the spirit here (reducing effort . . .) but has anyone ever thought about a MapFile parser service, would be cool to have something that told the user what versions of Mapserver their MapFile would work for as well as finding problems related to old/deprecated features. Hmm, even linking to the docs where appropriate . . . New features and test parsing would be a slick add. Test you install before updating? Would promote upgrading too I think over the long run. I know I have some work to do on this front with my own installs.
Bobb
From: mapserver-dev <mapserver-dev-bounces at lists.osgeo.org> on behalf of "Rahkonen Jukka (MML)" <jukka.rahkonen at maanmittauslaitos.fi>
Date: Friday, March 19, 2021 at 5:58 AM
To: Seth G <sethg at geographika.co.uk>, "mapserver-dev at lists.osgeo.org" <mapserver-dev at lists.osgeo.org>
Subject: Re: [mapserver-dev] Versioned MapServer Docs?
Think Before You Click: This email originated outside our organization.
Hi,
People probably do not use Mapserver 5.x much but new Mapserver users need some mapfile to start with and mapfiles they find from the web. Use of DUMP TRUE will not stop the day after the Mapserver documents are updated. Hits like this may appear surprisingly high on the list http://www.contingencias.mendoza.gov.ar/desarrollo/maplab-2.2.1/htdocs/mapedit/docs/wms-client-howto.html.
I think that the removed keywords should be documented for quite a long time for helping users to understand why a mapfile found from some old tutorial does not work. Maybe there could be an own section for those keywords.
-Jukka Rahkonen-
Lähettäjä: mapserver-dev <mapserver-dev-bounces at lists.osgeo.org> Puolesta Seth G
Lähetetty: perjantai 19. maaliskuuta 2021 12.06
Vastaanottaja: mapserver-dev at lists.osgeo.org
Aihe: Re: [mapserver-dev] Versioned MapServer Docs?
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<mailto: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>
>>>> <mailto: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>
>>>> <mailto: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> <http://www.greenwoodmap.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
>>>
>>> --
>>> http://www.spatialys.com
>>> My software is free, but my time generally not.
>>>
>>>
>>> _______________________________________________
>>> 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
>>>
>>
>>
>
>
--
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<mailto: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<mailto: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/4f7ddefe/attachment-0001.html>
More information about the mapserver-dev
mailing list