Re: docstrings and elisp reference

[Jean-Christophe Helary]

> On Jun 10, 2017, at 4:24, Etienne Prud’homme <address@hidden> wrote:
> 
> But as I said also in the same post, it looks like Jean-Christophe is
> right in saying we don’t use the exporting templates enough.  The texi
> files seems to have a lot of meaningful “tags” (I call that semantic) we
> could use when exporting the manual documentation to HTML.  Why not even
> use JavaScript to enable searching the manuals and/or
> expanding/collapsing setions.

I'd like to point out that in the 2014 thread that I was referred to earlier, 
RMS asked whether it would be possible to implement some display features 
(display/hide nodes, etc.) with HTML and Stephen Turnbull replied that, well, 
yes it was possible and relatively easy.

https://lists.gnu.org/archive/html/emacs-devel/2014-12/msg01911.html

Reading the whole thread shows that there was already some kind of consensus 
back in 2014 about what we could do with the HTML output (ie much more than 
what we do now) and how we could/should improve it.

So, my personal conclusion for the current thread is that:

1) We need to improve the texinfo export templates for HTML (I have no opinion 
for the other templates, but it could be the same) so that *no* information is 
lost in the conversion process and possible some information is added.

2) the i18n infrastructure that is very slowly emerging will allow for 
extraction of docstrings along with messages, so that we'll eventually be able 
to use that to create a "javadoc" like output for the docstrings with the 
information that Etienne mentioned earlier:

> Emacs Lisp doc strings have support for some of JavaDoc features, but
> cannot compare in many things.  Many things described in doc strings are
> informal and are pretty difficult to extract.  For example, we have no
> formal way of telling:
> 
> - the type of the function return value
> - what exceptions can be thrown from the function
> - does this function has side effects
> - since when it was introduced
> - it’s a hook variable
> - if the comment includes a file system path in the example
> 
> And many other things I don’t have in mind now.

3) When we have 1) and 2) we can have a fully interlinked HTML documentation 
set that could be used as a standard format for Emacs (as was discussed in 
2014) *and* as a base format for all sorts of documentation display 
applications that use HTML as the standard, so that Emacs documentation system 
features are not limited to the Emacs application but are literally all over 
the place.

Jean-Christophe