Re: docstrings and elisp reference

[Jean-Christophe Helary]

It was really not my intent to raise the temperature of this list to that 
level. Apologies for that. But the discussion is really interesting.

1) I'll read the Doc Strings and Manuals in the GNU Coding Standards.

2) my remark about javadoc was not intended to suggest a replacement of the 
current documentation, but to have a document that has all the docstring 
information (Emacs API) in one place. It would be an alternative to the info 
system, with exactly the same contents. It would be a great tool to find API 
information and also very practical to check if the rules defined in the GNU 
Coding Standards are respected.

3) my remark about duplication was full answered in the discussion and I'll 
have even better insights when I complete 1) above. So I'll just put that aside 
for the moment. My perspective was not exclusively l10n but also ease of access 
to information for beginners, etc.

4) regarding "semantic support" (although I'm not 100% sure what Etienne is 
referring to here) it seems to me that there are a number of not so hard things 
to do on the (some ?) texi conversion templates. I've been working on a CSS for 
the manuals and I found the HTML conversion templates remarkably underused (I'm 
currently discussing this on address@hidden). Even while maintaining legacy 
HTML support, there are plenty of areas where CSS selectors could be added to 
considerably enhance the output. There are even some regressions, for ex, the 
4.8 version I was unknowingly working with until this morning added a 
class="defun" to definitions, and that class information is gone in 6.3 
(replaced by a generic <dl> tag).

I understand I'm going in a lot of directions at the moment, sorry for that.

Jean-Christophe 

> Jun 8, 2017 11:29、Etienne Prud’homme <address@hidden>のメール:
> 
> Drew Adams <address@hidden> writes:
> 
>> And this is not JavaDoc.  The Elisp manual is not purely
>> and simply an API reference manual.
> 
> It’s worth mentioning that JavaDoc documentation style is particularly
> useful for Object-Oriented Programming and strongly typed languages.  I
> think it’s even mandatory with OOP to be readable.
> 
> However, I also think Jean-Christophe makes a good point about
> documentation generation.  Not with duplication, but semantic support.
> While documentation support is awesome in Emacs with GNU libraries, it’s
> not always so with third-party documentation tools.  I’m thinking about
> Zeal (and to a very limited extent Dash that is not free).
> 
> Those tools are highly effective for semantic indexation for newcomers
> since they offer a simple interface for hundred FLOSS libraries.  GNU
> projects are almost nonexistent.
> 
> I’ve been trying in the past to port GNU projects documentation and I
> finally gave up.  I find Texinfo to be very limited when it comes to
> semantic support.  It’s really hard to extract meaningful definitions
> from texi files.
>