[Top][All Lists]

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

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

From: David Kastrup
Subject: Re: On being web-friendly and why info must die
Date: Fri, 05 Dec 2014 14:34:31 +0100
User-agent: Gnus/5.13 (Gnus v5.13) Emacs/25.0.50 (gnu/linux)

"Eric S. Raymond" <address@hidden> writes:

> The positioning problem is that info/Texinfo makes us look like a
> steam-powered archaic joke to younger developers.

Uh, this is the Emacs developer list.  Emacs' _principal_ appeal is to
the steampunk culture of information technology.

> Text-only presentation with obtrusive links and a complex command set
> for a viewer that's *not a web browser*?  In 2014?  Really?

Can it be that you lost contact with Texinfo some time ago already?
Here is how my info page for the current LilyPond manual looks in Emacs:

PNG image

The HTML variant looks like

Guess which variant is much much much more responsive to use when using
a standard HTML browser on the HTML variant (installed locally, of
course) as compared to using Emacs on the info version.

Guess which variant is integrated into the normal workflow much better.
Try searching the index in HTML.  That's so much worse it is not even
funny.  And the LilyPond manual is actually rather good for an HTML
based manual.

> The capability problem is that the younger developers are objectively
> right to laugh.  Because these resources are not rendered to Web,

Texinfo has an HTML backend.  The LilyPond manuals are generated in that
manner.  Pretty much every GNU project offering its Texinfo based
documentation online also offers an HTML version, typically both as a
single-file HTML version as well as a distributed version.

For about the last 20 years or so.

Here is the Emacs version:

If you compare it to the LilyPond version, you'll find that the Emacs
a) does not make use of a lot of images (any at all?)
b) looks rather bland

Both are (obviously) not shortcomings of Texinfo as such, but of the
default workflows, styles and tools.

For example: why can't I dump menu structures and buffers and example
frames suitable for Texinfo graphics right from within Emacs?

> The EmacsWiki is a valiant stab at fixing part of the problem, but its
> utility is severely damaged by the fact that it can't readily link
> inwards to the stuff carried in the distribution.

Of course you can link to the Emacs info manuals in HTML form.

> The solution must be partly a change in mechanism and partly a change
> in policy and attitude.  The change in technology is the simple part;
> info and Texinfo must die.  They must be replaced with a common format
> for documentation masters that is Web-friendly, and by Web
> presentation.

You are confusing the documentation source (Texinfo) with one target
format (HTML).  HTML is not a reasonable format for authoring
documentation, just like Info isn't.  Texinfo, in contrast, is.  And
writing Texinfo is well-supported in Emacs.  I actually don't know any
other structured high-level documentation format that can reasonably be
edited in plain text form and converted into HTML using free tools.
Even if you care only for the HTML backend, you won't magically be able
to cater for it without having some human-writable frontend.  And there
is nothing wrong with using Texinfo for that.

> I have discussed this with RMS and, pending my ability to actually
> write proper translation tools, we have agreed on asciidoc as a new
> master format.

This is actually an awful idea as no reliable and maintained toolchains,
definitions, and Emacs editing modes for it exist and it is quite less
expressive than Texinfo.

> This is what should replace Texinfo and the gallimaufry of ad-hoc text
> files like /etc/CONTRIBUTE and the admin/notes stuff.

Files like /etc/CONTRIBUTE, if needed in multiple formats, can be
produced from Texinfo files using the ASCII backend.

AUCTeX does that for files like README, INSTALL, PROBLEMS and others
that are, in the fully marked-up version, included in the Texinfo
manuals as well.

> The policy part of the job will in some ways be more difficult because
> the requirements are harder to define.  We need to change the way we
> think about Emacs's documentation; we need to concieve and organize it
> as a single, coherent, richly linked hypertext that renders to HTML as
> its major target.  This may mean giving up on some features supporting
> rendering to print manuals; I'm not sure yet. If so, it's time to bite
> that bullet.

I disagree.  Really.  Take a look at the documentation of LilyPond,
<URL:http://lilypond.org/doc/v2.19/Documentation/web/>> possibly
installing the full Info version as well and experiment with it.  You
can, of course, browse the web-based documentation also.

Every single bit of it, including _all_ the web pages (not just the
manuals) and their translations, is written and maintained in Texinfo.

> I'm willing to take on the tools end, but I can't do it all.  Someone
> needs to take ownership of the policy/organization end of the
> documentation problem. Will any of the people righly complaining about
> this step up?

I don't see that you'll magically get more people involved than those
maintaining Texinfo, and your basic proposal is not even in any way
related to HTML (which is available already) but rather to replacing the
source format of Texinfo with AsciiDoc, a format that does not
distinguish logical and physical markup, is its own plain-text output
format and thus is unsuitable for providing all the information that may
be relevant for _any_ of the backends you are likely to use with it.

It't not even "more hip" or "less steampunk" than Texinfo: its only
major use known to me is as the documentation system of Git.

And you need particular versions of its toolchain to even compile all
the documentation of Git last time I looked.

So before panicking into some purportedly newfangled direction, it would
make proper sense making better use of our existing tools.

David Kastrup

reply via email to

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