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

[David Kastrup]

Rüdiger Sonderfeld <address@hidden> writes:

> I think Texinfo itself has a few issues as well.  I only started using
> it to write documentation for the 24.4 release.

What I consider the main nuisance right now is indexing.  Texinfo itself
is affected: you'd want to have an index entry for @it that is called
@it (and accessible from M-x info via i @it) but sorted under i (since
otherwise the index will basically just be full of @).

Texinfo 5 might be more amenable to making the indexing more flexible.
It's definitely also a nuisance for LilyPond (where we are talking about
the indexing of things like \relative, namely same indexing problem but
with a backslash as starter).

> I think Cross References (aka links) are a bit confusing.

Copy&paste from the info manual of Texinfo (as rendered by M-x info,
namely info format) is somewhat surreal regarding the mismatch between
the claims in the text and the actual output:

    8.6 '@ref'
    ==========

    '@ref' is nearly the same as '@xref' except that it does not generate a
    'See' in the printed output, just the reference itself.  This makes it
    useful as the last part of a sentence.

    For example,

         For more information, @pxref{This}, and @ref{That}.

    produces in Info:

         For more information, *note This::, and *note That::.

    and in printed output:

         For more information, see Section 1.1 [This], page 1, and Section
         1.2 [That], page 2.

      The '@ref' command can tempt writers to express themselves in a manner
    that is suitable for a printed manual but looks awkward in the Info
    format.  Bear in mind that your audience could be using both the printed
    and the Info format.  For example:

         Sea surges are described in @ref{Hurricanes}.

    looks ok in the printed output:

         Sea surges are described in Section 6.7 [Hurricanes], page 72.

    but is awkward to read in Info, "note" being a verb:

         Sea surges are described in *note Hurricanes::.

> Using a more popular language could lower the entry barrier.

HTML isn't an input language.  And AsciiDoc can hardly be called "more
popular".

> But then again I have a bit of a doubt that a change to a different
> format would really attract more people to writing documentation

More like "different people".

> and on the other hand it would certainly be a hassle for the majority
> of people already writing documentation.

When there are sizable numbers.  There is of course an ephemeral benefit
for this kind of "let's switch to something new" activism if basically
very little new material is being written in the current format, one can
batch-convert to a new input format and the new input format has a few
manyears of enthusiasm in it before the documentation writer base
sizzles out into into the same manpower that the old documentation crew
had at the point of change.

I don't see that AsciiDoc buys us even that.

-- 
David Kastrup