Re: info documentation with images?

[John Mandereau]

Le jeudi 31 janvier 2008 à 17:59 +0100, Jan Nieuwenhuizen a écrit : 
> David Kastrup writes:
> 
> > Actually, current documentation.  I think it is close to impossible for
> > the average developer/user to guess that he is supposed to say
> > 
> > make doc info out=www
> >
> > I don't think I am alone in being completely flustered by this
> > non-information: the standard Debian info packages don't come with
> > images, either.

Info docs miss images in Lily 2.10.33 Fedora 8 RPM too.

When installing info docs with images with "make web-install" with /usr
or /usr/local as a configure prefix, info files and images are written
in /usr/[local/]share/info/lilypond/.  The dir entries
(lilypond/lilypond, lilypond/music-glossary, etc.) are correct, but
cross-references between different LilyPond Info documents don't work,
because both Emacs and Info standalone expect to open
usr/[local/]share/info/lilypond-foo.info when reading a cross-reference
"*note (lilypond-foo)Node_xyz::.".

We could fix this with conditional macro definitions in macros.itexi
with "@ifset info-images"/"@ifclear info-images" blocks, and call
makeinfo with a flag "-dinfo-images", but that's quite messy.

I rather suggest putting .info* files in /usr/[local/]share/info/, and
images in a lilypond/ subdirectory.  This requires changing
lilypond-book a little, so it says

@image{lilypond/lily-354d7a5697,,,[image of music],}

instead of

@image{lily-354d7a5697,,,[image of music],}

Maybe "lilypond/" should be defined with a "--info-images-subdir"
lp-book command line option.

The latter approach has an important advantage: the Info files would
always be installed in the same location, whether they have images or
not.  May I go ahead with this?


> Yes, the whole doc/info/web out=www targets and options have always been
> a bit of a mess.  It has not gotten any easier now with online and
> offline web doc building.
>
> I have made `make help' now print:
> 
>   ..
>   doc         update all documentation (without images)
>   cvs-clean   also remove out directories and generated files
>   info        update info docs (without images)
>   info out=www  update info docs with images
> 
> but I guess that a some other new targets (offline, online web)
> are missing too.  We may want to add this to a more prominent
> place in INSTALL.

I documented offline and online web targets in INSTALL.

BTW it would be very cool to distribute Info docs with GUB, and add
support in the installation script for installing them and other stuff
like Emacs and Vim modes and HTML/PDF docs in standard locations
(/usr[/local]/... or /home/...).  I may have a look at this, but not
immediately, I'm already too busy.

Cheers,
John