AutoCAD Dimscale 0 - What's really happening

As of AutoCAD 2017, the AutoCAD help is wrong in its description of 0 values for dimscale.  Here's what's really going on from what I can tell.

AutoCAD Help

Help says:

Dimscale
0.0
A reasonable default value is computed based on the scaling between the current model space viewport and paper space. If you are in paper space or model space and not using the paper space feature, the scale factor is 1.0.

Use DIMSCALE to control the overall scale of dimensions. However, if the current dimension style is annotative, DIMSCALE is automatically set to zero and the dimension scale is controlled by the CANNOSCALE system variable. DIMSCALE cannot be set to a non-zero value when using annotative dimensions. 

The help description is not bad, but sometimes when dimscale is acting like 0, it is reported as 1 (see below).

What is really happening

Annotative dimension style current

Choose an Annotation Scale from the list: Cannoscalevalue is set to 1/scale and Dimscale is set to 1 (at least it says it's 1).

Try to set dimscale to 1: you get an error

Dimension style is annotative.
Cannot set DIMSCALE to that value.

Try to set dimscale to 0: no error.  But if you then ask what the value of dimscale is using DIMSCALE, (getvar "dimscale") or SETVAR DIMSCALE, you will see a value of 1.  Very strange 

Non-Annotative dimension style current

Choose an Annotation Scale from the list: Cannoscalevalue is set to 1/scale and Dimscale is set to 1/cannoscalevalue.

You can also explicitly set dimscale to 0 or 1 or any positive value.  Setting dimscale to 0 has the same effect as having a dimension style with Annotative Scaling; viewport scale (cannoscalevalue=1/viewport scale) is used for scaling when in model space of a layout tab, 1 is used in paper space (cannoscalevalue=1), and 1/cannoscale is used in the model tab.

Switching dimension styles

Switching to an Annotative dimension style leaves dimscale acting like 0, but reporting 1 (help says 0, but AutoCAD says 1).

Switching to a non-Annotative dimension style leaves dimscale at whatever the style says.  If the style says to "Scale Dimensions to Layout", its dimscale is 0.

Takeaway

For using AutoCAD

If you want to use AutoCAD in the standard modern way, don't ever set dimscale or scale viewports with the zoom command; use the annotation scale selector.  If you want to set dimscale, set it to 0 (or select "Scale Dimensions to Layout" for your dimension style).  Think of 0 as "Don't use dimscale, use cannoscalevalue from the Annotation scale selection".

If you want to use dimscale in the legacy way, you need to have a non-Annotative style current.

For programming AutoCAD

If dimscale is 0 or current dimstyle is annotative (= (GETVAR "dimanno") 1), use 1/cannoscalevalue for scaling.  Otherwise, ignore cannoscalevalue.