Thanks, looks good. I think we should keep the first "Version of the package." sentence and add your text after. I'll work that in and push on the stable branch.

oops, that doesn't build.  What is the right way to xref m-files from within package.texi?

I will do a patch.

I read "get_description" comments: it specifically mentions "2.1.0+"; maybe that is (or "should be") the recommended "dev" label for Octave-Forge packages: in particular, compare_versions isn't compatible with https://www.python.org/dev/peps/pep-0440 for things like "0.7.0-dev".  I could propose this in a different issue for Octave Forge.

Just re-confirmed that the Octave pkg "Version" field may contain any characters in a specified character set. They do not have to be dotted digits at all.

The character set was chosen to be identical to the Debian Version character set, which is alphanumberic characters (in the "C" locale), ".", "+", "-", and "~".

This is fully documented in scripts/pkg/private/get_description.m, and should be documented in doc/interpreter/package.txi the same way, that will resolve this bug.

I think it would be fair to say something like "A package version typically contains digits separated by dots, but may contain any characters in the set …" This is completely separate from whatever the Octave Forge package policy may be.

TL;DR:

How would you feel about changing [1] to say:

 Version

-     Version of the package. A package version must be 3 numbers separated by dots.
+     Version of the package. A package version is usually 3 numbers separated by dots.

[1] https://octave.org/doc/v5.1.0/The-DESCRIPTION-File.html:

- - - - - -

It's always bothered me that DESCRIPTION doesn't seem to allow versions like "0.7.0-dev".


I just tried using "0.7.0-dev".  Nothing horrible happened:

Package Name        | Version   | Installation directory
--------------------+-----------+-----------------------
             bsltl  |     1.1.1 | /home/cbm/octave/bsltl-1.1.1
           control  |     3.1.0 | /home/cbm/octave/control-3.1.0
           doctest *| 0.7.0-dev | /home/cbm/octave/doctest-0.7.0-dev
           general  |     2.1.0 | /home/cbm/octave/general-2.1.0

A quick look at the code of pkg.m suggests it uses "compare_versions", which does something with such strings:

octave:18> compare_versions ('0.7.0-dev', '0.7.0', '>')
ans = 1
octave:19> compare_versions ('0.7.0', '0.7.0-dev', '<=')
ans = 1
octave:20> compare_versions ('0.7.1', '0.7.0-dev', '>')
ans = 1

I personally prefer the semantics that 0.7.0-dev comes before 0.7.0 but I could certainly live with the above.

Benefits:

  - users would be able to try a dev version and later upgrade automatically when the package release came.
  - devs would be able to trust "pkg list" output in bug reports.