Re: [Gnu-arch-users] Re: "Newbie-ized help"

[Stephen J. Turnbull]

>>>>> "Miles" == Miles Bader <address@hidden> writes:

    Miles> Hmm, well Tom was advocating for a gdb-style interactive
    Miles> help system in tla... (actually not a bad idea -- it's

Really?  Unlike gdb, tla is not normally an interactive program.

    Miles> often easier to write "documentation" of this sort, where
    Miles> you can keep the doc strings close to the source, and
    Miles> organize them programmatically, than it is to write real
    Miles> manuals)

But "programmatic organization" can be done in batch just as well as
interactively.  With proper indexing and xref'ing, a "tla CMD --info"
command that invokes "info tla CMD", where the CMD node is
autogenerated from the same doccomment that the corresponding "tla CMD
-H" string is, but also leaves you in an info browser after displaying
the node, and provides xrefs and footnotes, seems to me a better
(== cheaper and faster to implement) idea than homegrown interactive
doc facilities.  Especially given how bad gdb's online help sucks.

Info isn't perfect, but it's a much better help authoring and browsing
system than HTML, at least with current HTML bowsers.  The two big
advantages of HTML up to now (multimedia and noob-fiendly-ness) are
both disappearing, and fairly rapidly AFAICT, with the addition of
image support to Texinfo and toolbars etc to many standalone and
Emacsen-based info browsers.  And if you really must have HTML[1],
there are several Texinfo-to-HTML converters that do a reasonable job,
whereas HTML-to-Texinfo converters invariably leave a lot to be
desired (eg, disbanding the W3C comes immediately to mind ;-).

Missing-Rs-are-all-deliberate-ly y'rs


Footnotes: 
[1]  Actually, yes, I think it's necessary for the Arch home page
and/or wiki.

-- 
Institute of Policy and Planning Sciences     http://turnbull.sk.tsukuba.ac.jp
University of Tsukuba                    Tennodai 1-1-1 Tsukuba 305-8573 JAPAN
               Ask not how you can "do" free software business;
              ask what your business can "do for" free software.