[eeps] EEP XXX: Documentation storage and format

[Loïc Hoguin]

On 01/06/2018 12:19 PM, José Valim wrote:> For translations, we could 
accommodate a similar change. We could
> introduce a map
> where the key is the language and the value is the documentation:
> 
>     Doc :: none | hidden | binary() | %{binary() => binary()}
> 
> 
> The above attempts to be backwards compatible but it is worth noting the 
> whole
> documentation tuple is versioned. If push comes to shove, we should 
> be able to bump
> the tuple version.
> 
> I am completely OK with changing the proposal to use a map to store the 
> documentation
> in order to support translations. Although I would like to hear others 
> on the balance
> between supporting it upfront vs. adding it later on when necessary.

Considering the number of projects that currently come with translations 
(close to zero) I think it shouldn't be a problem to postpone it.

It's also not as simple as it may sound. It would probably involve 
language tags which are already well defined and also have a language 
selection algorithm that's well defined (if user wants "en-GB" but only 
"en" and "fr" are available it will select "en"). What's not defined 
however is how the Erlang tools know which language the user prefers in 
a portable way (on Linux we have the LANG environment variable, but on 
Windows?).

So this needs a bit of research and experiment before something viable 
can be done in a consistent manner.

That said perhaps the first version of the EEP can change binary() to 
#{binary() => binary()} as this part is unlikely to change, and require 
that the map contains at least one element where the key is <<"en">>. 
That way tools can experiment with translations in a backward compatible 
manner.

Cheers,

-- 
Loïc Hoguin
https://ninenines.eu