Re: Why is it _still_ so freaking hard to get info with images?

[David Kastrup]

Jan Nieuwenhuizen <address@hidden> writes:

> Op zaterdag 14-03-2009 om 15:31 uur [tijdzone +0100], schreef David
> Kastrup:
>
>> If compiling Lilypond from source with default
>> settings means not getting the full docs, this is what all major
>> distributions will distribute
>
> So what we need to change is for
>
>     make [all|default]
>
> to also make web.

I don't think that is really necessary.  It is quite common to have
top-level targets

all install
doc install-doc
info install-info

and people get along with that.  What does not work is having a target
unfathomably called "web" for creating actually the standard docs (even
though they happen to be in HTML format), and which incidentally create
info documentation in some unfathomable subdirectory as a side-effect.

That will annoy both people who wanted to create info documentation, as
well as those who only care for the "standard" HTML docs.  I don't think
it is necessary to have the {doc,info}* targets included in all/install.
But hiding the targets away with inscrutable names is also not a good
idea, and likely fixed with just few lines of code.

The recent changes were already a good step in the right direction.

> Your point about README/INSTALL is more difficult to tackle.  While
> I agree it would be nice to have those file available at toplevel--
> just as they are in the distributed tarballs--it is a pain (not to
> say stupid) to have generated files in GIT.
>
> What we possibly could do, is have README and INSTALL be symlinks in GIT
> to the readme/install texi sources.

One reasonable thing would be to have autogen.sh hardwired to use
${MAKEINFO:-makeinfo} to generate README and INSTALL from the texi
sources: most version control users are used to use autogen.sh for
autopiloting the start.

It is also possible to place a README.git or README.development into the
top git-controlled directory which gives this information, but is not
packaged into the tarballs.

In AUCTeX, we actually have targets for producing the initial startup in
doc/Makefile.in, and doc/Makefile.in is written in a way that _those_
targets even work from doc/Makefile.in rather than requiring doc/Makefile.

#!/bin/sh

# Bootstrap script for AUCTeX

# Maintainer: address@hidden

# Copyright (C) 2003, 2004, 2005, 2006 Free Software Foundation, Inc.

# This file is part of AUCTeX.

# AUCTeX is free software; you can redistribute it and/or modify it
# under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 3, or (at your option)
# any later version.

# AUCTeX is distributed in the hope that it will be useful, but
# WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
# General Public License for more details.

# You should have received a copy of the GNU General Public License
# along with AUCTeX; see the file COPYING.  If not, write to the Free
# Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
# MA 02110-1301, USA.

test "x${AUTOCONF}" != x || AUTOCONF=autoconf
test "x${MAKEINFO}" != x || MAKEINFO=makeinfo
test "x${PDFTEX}" != x || PDFTEX=pdftex
test "x${PERL}" != x || PERL=perl
test "x${MAKE}" != x || MAKE=make
${AUTOCONF} || { echo "Error running ${AUTOCONF} in ." >&2 ; exit 1; }
cd preview
${AUTOCONF} -I.. || { echo "Error running ${AUTOCONF} in preview" >&2 ; exit 1; 
}
cd ..
rm -rf autom4te.cache preview/autom4te.cache
if test "x${AUCTEXDATE}" = x
then
    AUCTEXDATE=`sed -n '1s/^\([-0-9][-0-9]*\).*/\1/p' ChangeLog`
    test "X${AUCTEXDATE}" != X || { echo "Can't find date in ChangeLog" >&2 ; 
exit 1; }
fi

if test "x${AUCTEXVERSION}" = x
then
    AUCTEXVERSION=`sed -n '2,/^[0-9]/s/.*Version \(.*\) released\..*/\1/p' 
ChangeLog`
    test "X${AUCTEXVERSION}" != X || AUCTEXVERSION=${AUCTEXDATE}
fi

cd doc
rm -f version.texi
${MAKE} -f Makefile.in MAKEINFO="${MAKEINFO}" PDFTEX="${PDFTEX}" PERL="$PERL" 
AUCTEXDATE="$AUCTEXDATE" AUCTEXVERSION="$AUCTEXVERSION" dist || { echo "Error 
running ${MAKE} in doc" >&2 ; exit 1; }
cd ..


If you want more info about that scheme, holler.

> The problems with fixing a build system is that it is a major time
> sink without any obvious benefits,

Well, one need not replace the innards.  However, adapting the names of
the basic targets and what they do should be reasonably easy.

-- 
David Kastrup