[mapserver-dev] Versioned MapServer Docs?

[Jeff McKenna]

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/



On 2021-03-18 5:01 p.m., Seth G wrote:
> Hi all,
> 
> Several Mapfile keywords are proposed to be removed as part of [RFC 133](https://mapserver.org/development/rfc/ms-rfc-133.html).
> 
> If the docs will also have these keywords removed then it could lead to users on older versions of MapServer without documentation for keywords they are using. With regards to removed keywords I can think of two options:
> 
> 1. Keep the legacy keywords in the docs and mark them as deprecated for a specific version.
> 2. Remove the keywords from the documentation, but have older versions of the MapServer docs available.
> 
> My preference would be for option 2 as this reduces "clutter" in the docs for the latest version. It is also how the majority of online docs now work at ReadTheDocs e.g. https://shapely.readthedocs.io/en/latest/ or https://shapely.readthedocs.io/en/maint-1.6/
> So the MapServer homepage would have something like:
> 
> - https://mapserver.org/en/latest/
> - https://mapserver.org/en/7.6/
> 
> There are however complications as the MapServer docs also incorporate MapCache and TinyOWS which have different versions and release cycles. Not sure how this could be handled without a deeper folder hierarchy.
> 
> With the backports setup perhaps they could be pointed to deploy to a subfolder. Are deployments currently manual or automated? The scripts seem to be commented out at:
> 
> https://github.com/MapServer/MapServer-documentation/blob/1cd0b81865c636b04f9efb68f450db8f900b7714/.travis.yml#L35
> 
> 
> Seth
> 
>