As long as lock fields show up in warnings and user error messages, they should be documented in the reference manual

[WolframKahl]

In the reference manual, both on the GF website and on github, I find:

Library writers may occasionally want to have access to the values of linearization types. The way to make it possible is to add an extra construction operation to a module in which the linearization type is available:

 oper MkC : T -> C = \x -> x

I tried this out:

-- A.gf
abstract A = {
  cat A ;
}

---

-- A_S.gf
concrete A_S of A = open Prelude in {
  lincat A = SS ;
  oper
    mkA : SS -> A = \ x -> x ;
}

Both gf-3.10 and gf-3.10.4 (recent github version) produce:

[...]
- compiling A.gf...   write file A.gfo
- compiling A_S.gf... 
A_S.gf:
   A_S.gf:5:
     Happened in operation mkA
      Warning: missing lock field lock_A
  write file A_S.gfo
[...]

My impression is that ignoring GF warnings is dangerous (although I haven't found that mentioned in the documentation yet), so I am worried that a reference manual example produces a warning.

Apart from that, I have frequently been getting error messages complaining about missing lock fields or type mismatches involving lock fields, so I am disappointed that the reference manual, in both versions, only has a single occurrence of the work “lock”, right in the vicinity of the above-quoted passage:

This section is valid for GF 3.0, which abandons the "lock field" discipline of GF 2.8.

I have never tried GF 2.8, but the messages I get seem to suggest that some "lock field" discipline is still present in GF 3.10*.

As long as lock fields show up in the user interface (even if only in warning and error messages), I consider it worth-while that they are documented, so that users have a chance of understanding what these messages mean.

[inariksit]

I agree that lock fields should be better documented. Meanwhile, if you just want to learn more about lock fields, I have a blog post that is aimed for an audience who would rather read a tutorial than reference manual.
I can adapt that explanation into something that can be written on the actual web page.

If someone else wants to take up the task with more urgency, let me know (just comment here), otherwise I'll do it at some point.

[WolframKahl]

Thank you very much for that link --- that is very useful!

This appears to explain at least some of the trouble I am having with refactoring fragments of lincat definitions into opers, where I obtained the impression that “the meaning of type expressions changes in surprising ways” between the two places.

(If you were to declare the reference manual to be work-in-progress, and for topics that are currently (better) explained elsewhere linked to those places from the reference manual, I would not consider this problematic at all, but would actually welcome it.)

[inariksit]

Good to know it was helpful! Yeah I think linking my blog from places on the website would be helpful. I'll take it as a project for myself.