<div dir="ltr"><div>That's a very good point. We did not consider translations when writing the proposal.<br></div><div>However, we did consider the possibility of keeping the documentation in a separate<br></div><div>file, so I will start with that.</div><div><br></div><div>Today the documentation entry has the following type:</div><div><br></div><blockquote style="margin:0px 0px 0px 40px;border:none;padding:0px"><div><font face="monospace, monospace">Doc :: binary() | none | hidden</font></div></blockquote><div><br></div><div>If you want to keep the documentation in a separate file, we could support a new type,</div><div>such as:</div><div><br></div><blockquote style="margin:0px 0px 0px 40px;border:none;padding:0px"><div><span style="font-family:monospace,monospace">Doc :: binary() | none | hidden | {path, binary()}</span></div></blockquote><div><br></div><div>Where the binary() is a relative path to the application that contains the .beam file with</div><div>the documentation contents.</div><div><br></div><div>This could be useful for OTP, since part of the documentation is stored in XML files.</div><div>But for OTP the path tuple would not be enough since we would also need to be</div><div>capable of extracting each entry from the XML files. This would require some sort of</div><div>dispatching mechanism. Since it is unclear how this feature would be used, I decided</div><div>to postpone it until requested.</div><div><br></div><div>For translations, we could accommodate a similar change. We could introduce a map</div><div>where the key is the language and the value is the documentation:</div><div><br></div><blockquote style="margin:0px 0px 0px 40px;border:none;padding:0px"><div><span style="font-family:monospace,monospace">Doc :: none | hidden | binary() | </span><span style="font-family:monospace,monospace">%{binary() => binary()}</span></div></blockquote><font face="monospace, monospace"><div><br></div></font><div>The above attempts to be backwards compatible but it is worth noting the whole</div><div>documentation tuple is versioned. If push comes to shove, we should be able to bump</div><div>the tuple version.</div><div><br></div><div>I am completely OK with changing the proposal to use a map to store the documentation</div><div>in order to support translations. Although I would like to hear others on the balance</div><div>between supporting it upfront vs. adding it later on when necessary.</div><div><br></div><div>> <span style="font-size:12.8px">Finally, when it comes to metadata, I would definitely look at the Dublin Core.</span></div><div><span style="font-size:12.8px"><br></span></div><div><span style="font-size:12.8px">Thanks for the reference. I believe we currently do not conflict with Dublin Core.</span></div><div><span style="font-size:12.8px">The language is not a metadata key but an entry in the tuple. It is named exclusively</span></div><div><span style="font-size:12.8px">in </span><span style="font-size:12.8px">the type specification. If desired, we can update it to mean ProgLanguage to </span><span style="font-size:12.8px">avoid</span></div><div><span style="font-size:12.8px">any confusion.</span></div><div><span style="font-size:12.8px"><br></span></div><div><span style="font-size:12.8px">The other keys we use are "cross_references", which would be equivalent to</span></div><div><span style="font-size:12.8px">"references", but they have different values. The EEP lists "authors" and DC<br></span></div><div><span style="font-size:12.8px">only has "creator". "since" and "deprecated" do not seem to have equivalents.</span></div><div><br></div><div>Thank you Richard for the feedback.<br></div></div><div class="gmail_extra"><br clear="all"><div><div class="gmail_signature" data-smartmail="gmail_signature"><div dir="ltr"><div><div><br></div><div><br></div><span style="font-family:arial,sans-serif;font-size:13px;border-collapse:collapse"><b><span style="border-collapse:separate;font-family:arial;font-weight:normal"><div><span style="font-family:arial,sans-serif;font-size:13px;border-collapse:collapse"><b>José Valim</b></span></div><div><span style="font-family:arial,sans-serif;font-size:13px;border-collapse:collapse"><div><span style="font-family:verdana,sans-serif;font-size:x-small"><a href="http://www.plataformatec.com.br/" style="color:rgb(42,93,176)" target="_blank">www.plataformatec.com.br</a></span></div><div><span style="font-family:verdana,sans-serif;font-size:x-small">Founder and </span><b><span style="border-collapse:separate;font-family:arial;font-weight:normal"><div style="display:inline!important"><span style="font-family:verdana,sans-serif;font-size:x-small">Director of R&D</span></div></span></b></div></span></div></span></b></span></div></div></div></div>
<br><div class="gmail_quote">On Sat, Jan 6, 2018 at 10:20 AM, Richard O'Keefe <span dir="ltr"><<a href="mailto:raoknz@gmail.com" target="_blank">raoknz@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr">I note that there is no provision for translations of documentation yet.<div>I'm not sure you need to support that, but I do think it should be discussed briefly.</div><div><br></div><div>I don't see any way for someone to say "I'll keep my documentation where I want it</div><div>how I want it but I'll co-operate to the extent of providing a wrapper in your form in</div><div>your place that *points* to the documentation.</div><div><br></div><div>Again, I'm not sure you need to support that, but I do think it should be discussed,</div><div>if only to reject the idea.</div><div><br></div><div>Finally, when it comes to metadata, I would definitely look at the Dublin Core.</div><div>At a minimum, I would want to make sure that my keys (like 'language'),</div><div>either signified what you'd expect from DC or at least failed to clash with it</div><div>(as I think 'language' does). It would be useful to make the process of</div><div>mapping documentation to RDF or other Web forms straightforward.</div><div><br></div></div><div class="gmail_extra"><br><div class="gmail_quote"><div><div class="h5">On 5 January 2018 at 10:59, José Valim <span dir="ltr"><<a href="mailto:jose.valim@gmail.com" target="_blank">jose.valim@gmail.com</a>></span> wrote:<br></div></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div><div class="h5"><div dir="ltr"><div>This EEP proposes an official API documentation storage to be used by</div><div>by BEAM languages. By standardizing how API documentation is stored,</div><div>it will be possible to write tools that work across languages.</div><div><br></div><div>I want to thank Eric and Radek, who co-authored the proposal, as well as</div><div>Kenneth, Fred, Tristan and Loïc for their feedback.</div><div><br></div><div>See the attached document.</div><span class="m_5319216007282470737HOEnZb"><font color="#888888"><div><div class="m_5319216007282470737m_-4662346332464450849gmail_signature"><div dir="ltr"><div><div><br></div><span style="font-family:arial,sans-serif;font-size:13px;border-collapse:collapse"><b><span style="border-collapse:separate;font-family:arial;font-weight:normal"><div><span style="font-family:arial,sans-serif;font-size:13px;border-collapse:collapse"><b>José Valim</b></span></div><div><span style="font-family:arial,sans-serif;font-size:13px;border-collapse:collapse"><div><span style="font-family:verdana,sans-serif;font-size:x-small"><a href="http://www.plataformatec.com.br/" style="color:rgb(42,93,176)" target="_blank">www.plataformatec.com.br</a></span></div><div><span style="font-family:verdana,sans-serif;font-size:x-small">Founder and </span><b><span style="border-collapse:separate;font-family:arial;font-weight:normal"><div style="display:inline"><span style="font-family:verdana,sans-serif;font-size:x-small">Director of R&D</span></div></span></b></div></span></div></span></b></span></div></div></div></div>
</font></span></div>
<br></div></div>______________________________<wbr>_________________<br>
eeps mailing list<br>
<a href="mailto:eeps@erlang.org" target="_blank">eeps@erlang.org</a><br>
<a href="http://erlang.org/mailman/listinfo/eeps" rel="noreferrer" target="_blank">http://erlang.org/mailman/list<wbr>info/eeps</a><br>
<br></blockquote></div><br></div>
</blockquote></div><br></div>