Re: docstrings and elisp reference

[Etienne Prud’homme]

I want to make it clear I’m not questionning the usefulness of Texinfo,
nor I am criticizing the Emacs documentation system.

> Not sure I understand what is it that you allude to.  We always used
> different Texinfo commands for different kinds of symbols: @defmac for
> macros, @defvar for variables, @defun for functions, "@deffn Command"
> for commands, @defspec for special forms, etc.

That’s great and I hope we continue to use this system.

> We _are_ in an Emacs forum, where the Emacs way of doing things is the
> "normal" way.  And I definitely wouldn't say that the Emacs help
> system is "insane" by any measure.  E.g., it offers hyperlinks that
> everyone is accustomed to.

Far from me to say that the Emacs way is insane!  Forgive me father Eli.
I’m only pointing out that Emacs normal way of doing things is pretty
different from editors like Atom or many new (hackable) editors used.
I’m only talking about documentation here.  Whether Emacs way is better,
I’m probably too biased to tell, but people coming from those editors
are not used to _some_ of the documentation interface we provide.

That being said, I can bodly say that the Elisp printed manual is much
better than any other text-editors or program API I know.

The original subject of this thread was “docstrings and elisp
reference” i.e. JavaDoc comments style.  I’m thinking about ways we
could add relevant semantic information in either source.  We already
have support for some of that in docstrings i.e. ‘\\[]’ or ‘\\<>’.

I’m sorry if it looked like I was addressing other points.

> I still feel I don't understand the nature of that difficulty.

Looking at the source of the generated HTML documents, I think I might
have confused porting other GNU documentations.  I once tried to make
the Autoconf documentation available on Zeal at almost the same time as
I tried with Elisp.

Jean-Christophe seems to be right about using more the HTML conversion
templates.  Some of the semantic tagging is lost in the HTML conversion
and that’s where the difficulty was.

--
Etienne