Re: docstrings and elisp reference

[Jean-Christophe Helary <jean.christophe.helary@gmail.com>]

> On Jun 10, 2017, at 4:24, Etienne Prud’homme <e.e.f.prudhomme@gmail.com> 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