[mapserver-dev] Versioned MapServer Docs?
Jeff McKenna
jmckenna at gatewaygeomatics.com
Fri Mar 19 05:12:39 PDT 2021
I personally feel that we should never remove parameters from the
documentation, instead to clearly label them as removed-at-specific-version.
Again, this feedback is as a user.
-jeff
On 2021-03-19 7:58 a.m., Rahkonen Jukka (MML) wrote:
> 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
> <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
> <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html>
>
> [2] https://mapserver.org/mapfile/label.html#mapfile-label-encoding
> <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/>
> <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>
>
> >>>>
> <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 <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
> <https://lists.osgeo.org/mailman/listinfo/mapserver-dev>
>
> >>>
>
> >>> --
>
> >>> http://www.spatialys.com <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
> <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/ <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>
>
> --
>
> 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 <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
> <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
GatewayGeo: Developers of MS4W, MapServer Consulting and Training
co-founder of FOSS4G
http://gatewaygeo.com/
More information about the mapserver-dev
mailing list