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