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

[Eli Zaretskii <eliz@gnu.org>]

> From: phillip.lord@newcastle.ac.uk (Phillip Lord)
> Date: Wed, 17 Dec 2014 12:03:02 +0000
> Cc: kyle.c.andrews@gmail.com, sb@dod.no, emacs-devel@gnu.org
> 
> >   > I find texinfo a fairly busy format because of all the menus and node
> >   > information.
> >
> > I'm sorry you dislike it, but that information has to be specified
> > in the manual source somehow.
> 
> No, it really doesn't.

I think you only say that because you consider a subset of Texinfo's
capabilities wrt document structuring, and/or assume that such a
subset is all that's needed.  See below.

> Well, Eli says that this is a non-issue because Emacs can put it in
> place with a few keypresses. Okay, well, why does Emacs have to do it?
> Why does texinfo not do the job? 

It does.

> Consider this snippet....
> 
> @node Abbrevs
> @chapter Abbrevs
> 
>   A defined @dfn{abbrev} is a word which @dfn{expands}, if you insert
> it, into some different text. 
> 
> @menu
> * Abbrev Concepts::   Fundamentals of defined abbrevs.
> * Defining Abbrevs::  Defining an abbrev, so it will expand when typed.
> @end menu
> 
> @node Abbrev Concepts
> @section Abbrev Concepts
> 
>   An @dfn{abbrev} is a word that has been defined to @dfn{expand} into
> a specified @dfn{expansion}.
> 
> 
> In org this would be:
> 
> * Abbrevs
> 
> A defined \abbrev\ is a word which \expands\, if you insert it into some
> different text.
> 
> ** Abbrev Concepts
> 
> An \abbrev\ is a word that has been defined to \expand\ into a
> specificed \expansion\.
> 
> 
> Now, I agree that the loss of semantics from @dfn is not good. But org
> (or markdown or asciidoc or latex) can work out the navigation from the
> document structure.

So does 'makeinfo', but I guess you are not aware of that.  I explain
a little bit of that below, but there's more to Texinfo than meets the
eye, so you are encouraged to study it in more detail, because IMO
criticizing Texinfo without detailed knowledge of its features frankly
doesn't feel right.

What you wrote above in Org format defines a chapter and its
subordinate section.  And that's the _only_ structure supported by the
above paradigm: a tree, whereby the child nodes must immediately
follow their parents, in the depth-first order.

By contrast, Texinfo manuals do not have to have a tree structure.
Their structure can be an arbitrary graph.  At least one popular Info
manual (info.info) actually uses this feature: it doesn't present a
tree-like structure, but instead has a cycle or two within it.

_That_ is why there are node pointers in Texinfo.  And what the Emacs
commands I briefly mentioned do is create them automatically on the
assumption that the manual structure is indeed a simple tree.
Moreover, as long as the structure is indeed a tree, and the menus
(see below) are correctly written in each parent node naming its child
nodes, the Prev/Next/Up node pointers are not needed at all, because
'makeinfo' will deduce them automatically, and also validate the
document structure as a nice bonus.

As for menus, they provide one more degree of freedom for arranging a
manual in a non-tree structure: each menu item is a link to another
node, and can in general lead anywhere, including to another manual.

AFAIK, to do that in Org, you need to create a link; the outline-style
document you show above won't cut it.  IOW, Org requires you in that
case to insert links very similar to Texinfo menus.

As with node pointers, the Emacs Texinfo mode commands can
automatically create the menus as well, again on the assumption that
the section nodes immediately following a chapter node are child nodes
of that chapter, recursively.  Thus, in simple tree-like documents,
generating these menus is a keystroke away.

So, as you see, both Org and Texinfo solve the same problems, and they
do that in similar, albeit different, ways.  I see no advantage to Org
methods here, as long as you consider Texinfo together with its Emacs
support.  On the contrary, I see an advantage to Texinfo, because it
can easily express non-tree structured documents, something that in
Org is not so easy, perhaps even not easy at all.