The reference manual at SWI-Prolog -- Status and releases is quite clear, in section 1.2, that
This manual describes version 8.1.19 of SWI-Prolog.
This has as a consequence that on any point where things have changed, users of older versions (including the current stable version) of SWI-Prolog don’t have a reference manual on the web. They can run the documentation server locally, but that is likely to appeal only to a few users.
Would it be (a) a good idea and (b) feasible to allow the reference manual to describe the current version of SWI-Prolog with occasional notes on important differences from earlier versions? As someone who installs new versions of software as seldom as I can get away with it, following the motto “if it ain’t broke, don’t fix it”, that would feel helpful to me.
For example, the other day I was bewildered for an hour or two by the statement in section 2.2 that the user’s initialization file should be called init.pl, since when I put initialization code in the file described it did not execute, but it did execute if I put it in ~/.swiplrc. I am now aware that this has changed recently, and that version 8.0.3 and version 8.1.19 differ on this point. I think the discussion in section 2.2 could usefully include a remark along the lines of
Note: the current behavior was introduced in version 8.1.17 (October 2019); in earlier versions, the user initialization file was named
.swiplrc(swipl.inion Windows), and the system initialization file was … (whatever it was).
As an example of useful documentation which covers multiple versions of the program, one could cite the documentation of the XQuery database system BaseX (BaseX Documentation). Each page has a Changelog which mentions major changes to the functionality described (and because they use wiki software to maintain the documentation, it is always possible to go back to the reference manual for an earlier version, if one needs to). One might follow their example by putting notes on differences among versions of SWI-Prolog always at the bottom of a page and always under the heading Change log.
Obviously it’s not feasible to go through the entire reference manual inserting a history of ways in which SWI-Prolog has changed since its first release. But when user-visible changes are made, it might be worth while retaining some description of how things work in the current stable version of the code. (And in the future, one might adopt either the rule that the manual does not talk about any versions more than n years old, or perhaps anything older than the current stable version.)
If this is thought to be a good idea, I will probably suggest patches for things like section 2.2 and other things I come across. If it is thought to be a bad idea, then I will refrain from submitting those patches.
What do people think?