Re: What's the deal with info documentation images?

[David Kastrup]

Graham Percival <address@hidden> writes:

> On Fri, Aug 28, 2009 at 08:36:33AM +0200, David Kastrup wrote:
>> Graham Percival <address@hidden> writes:
>> 
>> > Well, yes.  FIXMEs generally aren't impressive.  The FIXMEs will
>> > definitely be dealt with.  The images might be dealt with, if
>> > somebody deals with them.
>>
>> But previously (info "(lilypond)") lead to useful top-level information.
>> Currently it leads to a chaotic ensemble of FIXMEs, side remarks only
>> relevant for web pages,
>
> ... and by some odd coincidence, we haven't made a stable release
> with it in such a state.  Imagine that!

Does that mean that one is not supposed to report problems until a
stable release has been made?

> The previous arrangement dumped you into the NR, which is not
> suitable for beginners.

The current arrangement is suitable for beginners?  I again state that
the _project_ webpage is not a suitable starting point for the
user-level documentation of a _single_ version of Lilypond.  Not in
info, not in HTML.

> Unlike most projects, lilypond has extensive documentation.  In order
> to let people navigate through and find the part(s) they want to read,
> we have it split between multiple manuals.  I can't identify any one
> manual (other than the current "general" one) that would make sense
> for a "info lilypond".

It is not a general manual, it is the project home page.  The aims of a
manual are so much different from that of a project home page that
folding the two does not make sense.

For the web page, it makes sense to have links leading to
"Documentation", even of several versions.

For the documentation, it does not make sense.  It is supposed to _be_
the documentation, not lead there.

It would make much more sense to land the user in either the command
line reference (with top-level links to the notation reference) or vice
versa.

> (or rather, if I was *forced* to pick one, I'd go with the AU,
> since that at least has the command-line arguments)

It hasn't.  Let's walk through this, comments in <<<>>>.

File: lilypond.info,  Node: Top,  Next: Introduction,  Up: (dir)
(lilypond)Top

LilyPond... music notation for everyone
***************************************

LilyPond
========

... music notation for everyone

   FIXME: images broken in info

What is LilyPond?
-----------------

LilyPond is an open-source music engraving program, devoted to
producing the highest-quality sheet music possible.  This free software
brings the aesthetics of traditionally engraved music to computer
printouts.

   Read more in our *note Introduction::!

<<<Note: the Introduction is just some basic outline of features without
anything that a normal user could actually try out>>>

   FIXME: process news items like the old web site: select first 4
items to insert here, and generate RSS.

   (*note Old news::)

<<<So the first two sections contained broken images, and a link to
something which does not serve as a manual>>>

Quick links
-----------

Stable
......

*note Download 2.12.3: Download.

   *note Manuals 2.12.3: Manuals.

<<<The next link contains download locations for the stable version and
a link to the Manuals.  How can those manuals be for a different version
than the one installed in info?  Well, follow the links and go to the
manuals to see yourself.  You arrive at:


Notation
========

This book explains all the LilyPond commands which produce notation.

          Note: The Notation assumes that the reader knows basic
          material covered in the Learning and is familiar with the
          English musical terms presented in the Musical Glossary.


And that's it.  The links don't lead to the notation manual, but merely
to a short blurb that tells you what the notation manual would be if you
actually managed to find it.  I mean, wow.  Talk about wow.
>>>

Unstable
........

*note Download 2.13.2: Development.

   *note Manuals 2.13.2: Development.

<<<Well at least this "manuals" link leads us to a more informative info
page, namely one looking like

Manuals
-------

LM: html (lm-html) pdf (lm-pdf)

   MG: html (mg-html) pdf (mg-pdf)

   AE: html (ae-html) pdf (ae-pdf)


   NR: html (nr-html) pdf (nr-pdf)

   ...etc...  SL-link AU-link

   FAQ-link  (? maybe?)  Changes-link IR-link


Need I mention that none of those things actually are an info link?
This is just text.  How very useful.
>>>

* Menu:

* Introduction::     Start here to creating sheet music.
* Download::         Get LilyPond.
* Manuals::          Read The Fine Manuals (RTFM).
* Community::        Contact other users.

<<<And lo and behold, the "Manuals" link here again leads us to a list
of manuals which, when followed, leads us to single paragraph
explanations what kind of manuals we should want.

In fact, the top-level info page can't be used, as far as I can see, to
navigate to any of the manuals.  Just to pages that explain what would
be contained in a manual, would you be able to find one.

> I'd accept a patch that produces an info version of just the
> "Manuals" page.  Or made it so that "info lilypond" started at the
> Manuals page.

So that I can see what the manuals would mean, were I able to figure out
where to find them?

Please try getting at any detailed information yourself with the
existing documentation tree before making fun of me.

I may be stupid, but at one point of time you have to cater even for
stupid people.

-- 
David Kastrup