Re: On being web-friendly and why info must die

[Eli Zaretskii]

> From: address@hidden (Phillip Lord)
> Cc: <address@hidden>,  <address@hidden>,  <address@hidden>,  <address@hidden>
> Date: Mon, 08 Dec 2014 12:33:38 +0000
> 
> Eli Zaretskii <address@hidden> writes:
> 
> >> > But a lot of this is cosmetic.  We could improve Texinfo to look much
> >> > better probably (and that would positively affect a lot of existing GNU
> >> > projects).
> >> 
> >> But it would still be Texinfo, still be an essentially pointless
> >> barrier to learning how to contribute.
> >
> > Nonsense.  What evidence do you have to back that up?
> 
> I think it is intrinsically hard to get evidence for why people do NOT
> do something.

What I had in mind was some evidence, even anecdotal one, that people
considered contributing a chunk of docs, but decided against that
because of Texinfo.

> I did try and learn texinfo once, but stopped. I could never understand
> why it had all the menu stuff in it. Running occur gives me this...
> 
> 4 matches for "List Processing" in buffer: emacs-lisp-intro.texi
>     238:* List Processing::             What is Lisp?
>     277:List Processing
>     998:@node List Processing
>     999:@chapter List Processing
> 
> Can it really be the case that the same text appears four times?

Yes.

> If I use latex, I just do "\tableofcontents".

I think you are misinterpreting what you see.

The first and the second "List Processing" hits will be produced
automatically by a suitable command of Texinfo mode -- that's the
moral equivalent of your "\tableofcontents".  The 4th one could be a
different string (there's no requirement that a node and its
chapter/section have the same name, and more often than not they
don't), but the author decided to use the same text for both in this
case.  The 3rd one is the only one you need to write by hand.

> Texinfo seems to totally conflate document structure and
> navigation. I just want to maintain one of these.

Not sure what you mean by that, please clarify.  A Texinfo document's
structure is a graph of nodes, each node is a
chapter/section/subsection.  (Usually, the graph is actually a tree,
but that's not a requirement, and at least one popular manual I know
of does not present a tree.)

You can navigate a Texinfo document in any way you want, either via
next/prev/up/down links or any other way.  Following the links takes
you in the same order as you'd read a book, should the document be
printed.

> Texinfo seems to have all the complexity of latex with less of the
> advantages.

The advantage is that it is simpler and easier to learn.  Of course,
if you are already a TeX/LaTeX user, this is not a real advantage, but
it is definitely an advantage when you ask code developers, which
mostly don't use LaTeX, to provide documentation for their code.

> Everything that has been said about the indexing in info is entirely
> true. Like everyone else, I navigate extensively with indexing;
> although, perhaps this is partly because info doesn't do inline
> hyperlinks. Imagine:
> 
>     "At any time, one window is the "selected window". On a graphical
>     display, the selected window shows a more prominent cursor (usually
>     solid and blinking)
> 
> like:
> 
>     "At any time, one window (see Windows) is the "selected window" (see
>     selected-window). On a graphical display (see Graphical Display),
>     the selected window (see selected-window) shows a more prominent
>     cursor (set Cursor) (usually solid and blinking (see set-cursor-color)"
>
> Unreadable right? Now, if info used wiki style hyperlinks, maybe I would
> never use the index explicitly.

What you show above aren't index links, they are direct hyperlinks to
other places in text.  Indexing is not visible in the formatted
document (except in the Index node, which is auto-generated), only in
the Texinfo source.

And Info does support such "inline hyperlinks".  Here's an example (in
Texinfo; you need to format it and view in Emacs to see the results):

    "At any time, one @ref{Windows, window} is the
    "@ref{selected-window, selected window}". On a @ref{Graphical
    Display, graphical display}, the selected window shows a more
    prominent @ref{Cursor, cursor} (usually solid and blinking,
    @pxref{set-cursor-color}).
  
(The node names are not visible when you read the Info document in
Emacs, so only the hyperlinks remain.)  Okay?

> As it stands, though, if I were starting a new project, I cannot see
> why I would start off with texinfo.

We are not starting a new project; that would be a whole different
ball game.

> Does this make it worth changing from? That's a much harder question.

Well, that's the question discussed here.  Texinfo is well known to
people who work on Emacs documentation, and it has excellent support
in Emacs (Texinfo mode) that alleviates many aspects of Texinfo people
consider to be disadvantages.