Enable references to refer to pages with '.' or '-'

[jonludlam]

[lubegasimon]

Could someone add some pointers to this because it turns out to be a bit tricky for me to figure out a good design. cc @Drup @jonludlam @aantron

[Julow]

It is currently not possible to write a reference to a page containing a - or a . in its name:

• {!page-cohttp-lwt} the parser thinks that page-cohttp is the "kind" and lwt the name.
  This is due to the module-type or class-type kinds containing a -. A fix might be to disallow kinds containing - or to add a way to escape it.
• {!page-1.7.3} parses as (`Dot (`Dot (`Root (`Page, "1"), "7"), "3"). We need a way to escape the . character too.

It was suggested during the last meeting to allow escaping with quotes: {!page-"cohttp-lwt"}, {!page-"1.7.3"}

[dbuenzli]

Note that when @trefis implemented the .mld support one of the constraints was that the name of mld pages had to follow the convention of module names. I don't know if lifting that constraint may have further implications.

It was suggested during the last meeting to allow escaping with quotes: {!page-"cohttp-lwt"}, {!page-"1.7.3"}

The page- to reference pages always felt weird to me. I suspect @trefis had his reasons but rather than introduce new notations and escapes wouldn't it be possible to reframe that in the context of cross reference disambiguation.

That is introduce page: as a "syntactic class" for making references:

{!page:cohttp-lwt}
{!page:1.7.3} 

That would make a two things less to learn: the weird page- references and how to escape them.

[jonludlam]

The hyphen notation is consistent with the 'new-style' cross-reference disambiguation. The 'colon-style' behaviour doesn't allow us to distinguish between the two types t in the following:

module X : sig type t end
module type X = sig type t end

whereas the newer 'hyphen-style' does: {!module-X.t} vs {!module-type-X.t}. So the page- notation is consistent with that. Additionally, we'd still need to be able to refer to labels in the pages, so we'd either have to introduce a new separator for the page and label, or we'd need escaping, or the quoting that's suggested above.

[trefis]

I agree for the explanation of hyphen vs colon, though for consistency it would make sense to allow {!page:...} as well as {!page-...}.

Now, for the issue discussed here, it seems to me that (if we were to allow it), only pages could contain dashes in their name, modules, types, etc. still won't have them.
So it should be possible to write a parser that understands {!page-foo-bar} as a reference to the page foo-bar.mld, shouldn't it? I don't think we need quoting for that.

It is true that if we want pages with dots in their name we'll need some kind of quoting. But, do we really need those?

[trefis]

I'd also like to point out that with the proposed quoting mechanism, I won't be able to have double quotes in my pages names. 😈

[lubegasimon]

But, do we really need those?

Yes, so as to be able to have something like packages/odoc/v1.0.0/Odoc/index.html for specifically for docs.ocaml.org I think.

Edit: http://hub2.cl.cam.ac.uk/packages/ @trefis . Currently we have sort of http://hub2.cl.cam.ac.uk/packages/abt/0_0_3/index.html

[Julow]

{!page:foo} is already allowed, it is also possible to reference labels in pages {!page-foo.bar}. In theory, it should be possible to reference pages without the "page-" specified but that's not implemented yet.
We may want to reference pages with a parent in the future (eg. {!cohttp.page-"2.5.4"}). Currently in our docs.ocaml.org plans, it is not possible to write references to an exact version of a package in general (it is possible by carefully choosing the search path as long as no two packages have the same version name), so we may want that soon.

We shouldn't parse references to pages differently because we'll need every forms soon.

The parser understands an other kind of escaping: {!(+)}, but the parentheses are taken as part of the name (+) (which also takes whitespaces as they are, there is potentially a bug here).

[dbuenzli]

Reading @trefis' insights and assuming one does want to be able to have pages with - in their name, here are three design proposals:

1. Always mandate pages to be explicitly referenced (page- or page:). In that case all that is needed is to escape .. For which I would rather advocate to simply introduce the escapes \. and \\.
2. Introduce escapes for each of the separators. that is \., \-, \\.
3. Introduce quoted parts and the escapes \" \\ therein.

No strong preference but personally I'd rather lean towards 1. or 2. which I find the easiest to discover and remember ("do not interpret that symbol according to the language"). But 3. is better for readability if one expect these references to be widespread (for . I doubt).

The parser understands an other kind of escaping: {!(+)}, but the parentheses are taken as part of the name (+) (which also takes whitespaces as they are, there is potentially a bug here).

That doesn't look like escaping to me, that's the identifier syntax of OCaml:

# let (+) a b = 3;;
val ( + ) : 'a -> 'b -> int = <fun>
# let ( + ) a b = 3;;
val ( + ) : 'a -> 'b -> int = <fun>

[avsm]

Odoc dev meeting notes: go with number 3 on @dbuenzli's list (introduce quoted parts). It might not be worth adding escapes as quoted " is unusual. However @lpw25 notes that it might be common to have version numbers and good syntax support for dots is essential.