Re: info reference syntax

[Xah Lee <xahlee@gmail.com>]

On Jan 9, 1:12 pm, Dan Davison <davi...@stats.ox.ac.uk> wrote:
> On Fri, Jan 09, 2009 at 08:27:40PM +0100, Lennart Borgman wrote:
> > On Fri, Jan 9, 2009 at 8:22 PM, Dan Davison <davi...@stats.ox.ac.uk> wrote:
> > > What does this syntax mean?
>
> > > ,----
> > > | See Info node `(viper)Top'.
> > > `----
>
> > > Is there some way of using it to immediately access the info node
> > > referred to?
>
> > M-: (info "(viper) Top")
>
> Great, thanks. That is useful to know.
>
> "(viper) Top" still seems like a pretty weird syntax. Just out of
> curiosity, is there some explanation? I see that the shell version is
> 'info filename nodename'. And according to wikipedia info was written
> for GNU/linux. So it's a post-linux emacs design? Wouldn't
>
> (info filename &optional nodename)
>
> have been more natural?

it'd be much better if emacs adopted html as its standard doc format.

It would than just be:

http://gnu.org/doc/emacs/viper/top.html

in this format, every programer understand what it is.  In “(info
"(viper)Top")” or “(viper)Top”, maybe 0.001% of programers knew what
it is.
If we count among emacs users who used emacs for no more than 2 years,
the percentage is perhaps 10%.

Personally, i use emacs daily, staying in emacs most of the time when
using computer, since 1998, and have been using text terminal based
emacs exclusively from 1998 to 2005. I didn't know what is “(info
"...")” until 2005 or so thru chatting in freenode's emacs irc.

Adopting html as standard doc format is easy to do, in fact mostly
just a political gesture. Texinfo can already convert to html, and
most if not all GNU's doc are already presented in html format on
GNU's site.

with adoption of html, people will naturally citing doc by url instead
of “info xyz”. This will help understanding and consequently spread
emacs. For example, if in a discussion in some programing forum,
someone might mention “look (info xyz) in emacs”. Vast majority of
readers wouldn't understand what that is will simply ignore it. But if
html doc is official, then the citing would be “http://gnu.org/doc/
xyz.html”, and those who saw this are very likely to click it.

this wouldn't effect emacs much since emacs can and should still use
info doc in emacs as a integrated system. But down the road, say in 5
years, emacs will need to deprecate texinfo eventually. The HTML/XHTML/
CSS/JavaScript world is literally with few million more users and
developers. Their tools, technical power, extensibility, adoption...
in every area, are few order of magnitude better than textinfo. In
fact, i wouldn't be surprised that modern browser such as Firefox
actually load html doc faster than a comparative info file.

By adopting html now, it can pave the way for emacs transition to
using html/xhtml as integrated doc component. For example, currently
there's w3m for reading html. However, it's some 5 times slower than
Firefox, and some 5 times slower than info reading texinfo. However,
this can be improved. One could have html/xml parser buildin elisp as
c code (or borrowing the rendering engine from firefox), so that
reading html docs in emacs is acceptably fast as current reading in
info.

the integrated nature of info in emacs is really joy to use,
especially programing in elisp. You can lookup any function or keyword
in the lang so easily. However, if the lang is not elisp but perl,
python, php, etc, then it's not so easy because you often have to
download and install a info version of their doc (if it exist at all),
and depending whether the guy who implemented your lang's mode took
the fancy to implement info doc lookup features. (10 years ago, some
mode would still support info doc. Today, as far as i know, nobody
bothered with info version of docs.)

When emacs accepted more html docs, it would mean the integrated doc
feature automatically apply to all langs, such as java, perl, python,
ruby, php, javascript... since their official doc are all html.

  Xah
∑ http://xahlee.org/

☄