[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: docstrings and elisp reference

From: Eli Zaretskii
Subject: Re: docstrings and elisp reference
Date: Thu, 08 Jun 2017 22:14:57 +0300

> From: Etienne Prud’homme <address@hidden>
> Cc: address@hidden,  address@hidden,  address@hidden
> Date: Thu, 08 Jun 2017 14:10:13 -0400
> > What's more, at least the docs it has for Bash and ELisp are exactly
> > the respective Texinfo manuals, with the same text and the same node
> > structure.  What is the advantage of using a different browser for the
> > exact same text?
> That’s my point.  I must confess that the available documentation for
> Elisp has better support now for choosing whether we search for a macro,
> command, function, etc.  It used to index every symbols in the same
> entry type (variable entry).

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.

> Furthermore, we could support much more indexation capabilities given
> the list of supported entry types[1].

If Texinfo lacks some of these, they could easily be added as the
language continues to evolve and being developed.  I see no
fundamental problems here, just something to code.

> What I meant was really the uniform search interface it provides.  For
> advanced Emacs users, it’s not a problem looking what we want from Emacs
> itself (or Info entries), but for a newcomers, it might look insane.

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.

> People are now used to search engines when looking at documentation.

Did you try giving a list of keywords to the Emacs apropos commands?
That feature was added in Emacs 23, I think.

IOW, Emacs uses search-engine techniques as well, always did.  You
cannot find your way through hundreds of pages of manuals without some
reasonably smart indexing and searching facilities.

> > This should be discussed on the Texinfo list, not here.  The current
> > Texinfo translator is highly customizable, so it could be that it can
> > be adapted to these needs much better.
> Since we were talking about Emacs, I thought this thread was more
> appropriate.  I was refferring to the difficulty of porting GNU Emacs
> Lisp documentation to the Dash docset format.

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

reply via email to

[Prev in Thread] Current Thread [Next in Thread]