[eeps] EEP XXX: Documentation storage and format

[José Valim]

That's a very good point. We did not consider translations when writing the
proposal.
However, we did consider the possibility of keeping the documentation in a
separate
file, so I will start with that.

Today the documentation entry has the following type:

Doc :: binary() | none | hidden


If you want to keep the documentation in a separate file, we could support
a new type,
such as:

Doc :: binary() | none | hidden | {path, binary()}


Where the binary() is a relative path to the application that contains the
.beam file with
the documentation contents.

This could be useful for OTP, since part of the documentation is stored in
XML files.
But for OTP the path tuple would not be enough since we would also need to
be
capable of extracting each entry from the XML files. This would require
some sort of
dispatching mechanism. Since it is unclear how this feature would be used,
I decided
to postpone it until requested.

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.

> Finally, when it comes to metadata, I would definitely look at the Dublin
Core.

Thanks for the reference. I believe we currently do not conflict with
Dublin Core.
The language is not a metadata key but an entry in the tuple. It is named
exclusively
in the type specification. If desired, we can update it to mean
ProgLanguage to avoid
any confusion.

The other keys we use are "cross_references", which would be equivalent to
"references", but they have different values. The EEP lists "authors" and DC
only has "creator". "since" and "deprecated" do not seem to have
equivalents.

Thank you Richard for the feedback.



*José Valimwww.plataformatec.com.br
<http://www.plataformatec.com.br/>Founder and Director of R&D*

On Sat, Jan 6, 2018 at 10:20 AM, Richard O'Keefe <raoknz@REDACTED> wrote:

> I note that there is no provision for translations of documentation yet.
> I'm not sure you need to support that, but I do think it should be
> discussed briefly.
>
> I don't see any way for someone to say "I'll keep my documentation where I
> want it
> how I want it but I'll co-operate to the extent of providing a wrapper in
> your form in
> your place that *points* to the documentation.
>
> Again, I'm not sure you need to support that, but I do think it should be
> discussed,
> if only to reject the idea.
>
> Finally, when it comes to metadata, I would definitely look at the Dublin
> Core.
> At a minimum, I would want to make sure that my keys (like 'language'),
> either signified what you'd expect from DC or at least failed to clash
> with it
> (as I think 'language' does).  It would be useful to make the process of
> mapping documentation to RDF or other Web forms straightforward.
>
>
> On 5 January 2018 at 10:59, José Valim <jose.valim@REDACTED> wrote:
>
>> This EEP proposes an official API documentation storage to be used by
>> by BEAM languages.  By standardizing how API documentation is stored,
>> it will be possible to write tools that work across languages.
>>
>> I want to thank Eric and Radek, who co-authored the proposal, as well as
>> Kenneth, Fred, Tristan and Loïc for their feedback.
>>
>> See the attached document.
>>
>> *José Valimwww.plataformatec.com.br
>> <http://www.plataformatec.com.br/>Founder and Director of R&D*
>>
>> _______________________________________________
>> eeps mailing list
>> eeps@REDACTED
>> http://erlang.org/mailman/listinfo/eeps
>>
>>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://erlang.org/pipermail/eeps/attachments/20180106/0ab33906/attachment.htm>