[RFC] Inline the nullary/unary/star type abbreviations

[Armael]

I would like to gather comments about whether people think it would be a good idea to inline the nullary/unary/star type abbreviations.

I personally would like this to happen (and would be willing to submit a PR). I believe these abbreviations greatly contribute in the feeling of "types are unreadable" tyxml users may experience; and I believe fixing this is just a matter of inlining them.

• I would argue that the names "nullary", "unary" and "star" only have a chance to make sense for people familiar with compsci. So I wouldn't say that they are self-explanatory.

• When trying out a new library, I usually type the names of functions in utop to get their types, and try to understand how to use them. Typing Tyxml.Html.div in utop and getting a type that uses star is not helpful and a bit frustrating.

  Even now that I know tyxml works, I do not try to decipher the star types; I just learnt to ignore the types and try to follow the common patterns. But sometimes you really need to look at the types, e.g. for img which has extra labeled arguments. It would be much better to be able to directly look at the types and understand how to use the functions.

• Using merlin for following the indirections and expanding the type abbreviations does not really work, as it also expands the variants abbreviations, producing an enormous and even more unreadable type.

Thoughts?

[vasilisp]

I understand your concerns. But at the same time I think types like these are useful for forcing us to do things in a uniform way (and document the uniformity). Possible remedies:

• Root for some kind of "type inlining" annotations that can be read by Ocamldoc, Merlin, the toplevel, etc. Clearly not trivial. Is there any similar proposal?
• Friendlier names. The question is whether a particular combinator accepts zero, one, or (a list of) many children. Put zero/one/many in the names?
• Encourage new users to use the PPX.

[Armael]

I understand your concerns. But at the same time I think types like these are useful for forcing us to do things in a uniform way (and document the uniformity).

Yes, I understand that there is a tradeoff here. But personally I would weight on the side of a slight occasional maintenance burden (adding new html tags should not happen that often?), instead of constant, systematic pain for users.

Encourage new users to use the PPX.

In the current state of things, I do not think it is possible to use the PPX in a non-trivial way without knowing the underlying tyxml functions, and how they are typed.

This constatation (and the present RFC) comes from a recent experience, where I introduced tyxml to a friend. To give a bit of context, this friend is seasoned in front-end development, is motivated, drank the ocaml kool-aid, but at the moment is only an ocaml beginner.

I started by only introducing him to the PPX. The PPX is great for writing large chunks of html, plugging maybe one thing in the middle. On that aspect it works quite well.

However, my friend quickly wanted to move to writing reusable UI components, and build the final page using them — which sounds like a pretty reasonable thing to do. Using the PPX for that wasn't so pleasant.

Say, for example, we define a component that contains an <input>. The component will assign CSS classes for the input, and take an (optional) parameter for other attributes that we may want to assign to it. Using the PPX, we are not able to give these extra attributes using an anti-quotation, while using the PPX syntax for the class attributes. As far as I know, there is no PPX equivalent for input ~a:([a_class ["foo"; "bar"]; attr1] @ extra_attrs) (). Due to a current limitation, it is also not possible to provide extra classes using an anti-quotation.

And even then, these extra attributes given to the component will have to be passed using the tyxml attribute functions a_*; which is a first step in the non-PPX world. Similarly, to pass extra classes, one has to do something like [%html {| <input class="|} ["foo"; "bar"] @ other_classes {|"/> |}] which also requires some knowledge of how the underlying a_class works. Filling the anti-quotations of html tag bodies also somewhat requires to know that an OCaml list should be there, and use the OCaml syntax for lists. Typing errors can only be really be understood knowing the underlying tyxml functions and their types.

Essentially, the PPX syntax is not as powerful as the combinators, and you end up anyway in a situation where the PPX is only used to avoid calling the tyxml function directly, but without avoiding the typing difficulties, and with wayyy uglier syntax.

My conclusion was that the PPX, in its current state at least, is a nice addition to the tyxml combinators, can be useful, but does not spares from knowing the tyxml combinators and understanding their types — hence the present proposition, to hopefully make that a bit easier.

[Drup]

I agree, it's not possible to use only the html syntax at the moment. I have plans to improve that (when I have time to dedicate to tyxml again :p).

That being said, @vasilisp's argument about uniformity is extremely important, so just abandoning the aliases is not a great idea. There are ways to perform the inlining directly in the module system (using tricks with destructive substitution such as include sig ... end with type .. := ...) but they would probably make the code look worse and are usually very ocamldoc-unfriendly.

I'm very favorable to finding better names and improving the documentation, though. So that could be a useful actionable first step before trying out more radical changes.

[Armael]

In this context, https://github.com/ocaml/ocaml/pull/792 seems to be a showstopper for tricks with destructive substitutions.