[mapserver-dev] Versioned MapServer Docs?

Jeff McKenna jmckenna at gatewaygeomatics.com
Fri Mar 19 08:05:03 PDT 2021


Update: this morning I have been playing with and enabled the new 
'versionremoved' directive in our documents, using the 
'sphinx-removed-in' Sphinx extension, works very well.  So (after you 
locally run 'pip install -r requirements.txt' and get the latest source 
from main branch) the syntax will be:

   PARAMETER
     .. versionremoved:: 8.0
        Use :ref:`XXX` parameter instead.

I've also updated the documentation guide of course.

Have a nice weekekend all,

-jeff



On 2021-03-19 10:19 a.m., Basques, Bob (CI-StPaul) wrote:
> 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 
> <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