From eaa69fe339d8f1b0b5458d22918c937713d635b6 Mon Sep 17 00:00:00 2001 From: John Mandereau Date: Fri, 13 Mar 2009 08:40:09 +0100 Subject: [PATCH] Fix Info documentation with images This patch mainly applies suggestions from David Kastrup and Jan. * fix symlinks creation from prefix/share/info to prefix/share/doc/lilypond, enable it even when installing in nonstandard prefix, and clean it up in the makefiles, * add info and info-install toplevel targets, * improve documentation (make help, stdout prints and Application Usage), * fix flats graphics in Introduction for Info format. (cherry picked from commit 0c9af42587ceac7e72290435164f6a9394250c66) --- Documentation/user/compile.itely | 43 +++++++++++---- Documentation/user/introduction.itely | 4 +- GNUmakefile.in | 11 ++-- scripts/build/relative.py | 2 +- stepmake/stepmake/generic-vars.make | 3 + stepmake/stepmake/texinfo-rules.make | 7 +-- stepmake/stepmake/texinfo-targets.make | 73 ++++++++++++++++--------- stepmake/stepmake/toplevel-targets.make | 2 + 8 files changed, 98 insertions(+), 47 deletions(-) diff --git a/Documentation/user/compile.itely b/Documentation/user/compile.itely index 15227251bd..5ceaa57720 100644 --- a/Documentation/user/compile.itely +++ b/Documentation/user/compile.itely @@ -230,8 +230,8 @@ make web After compilation, the HTML documentation tree is available in @file{out-www/offline-root/}, and can be browsed locally. -The HTML and PDF files can be installed into the standard documentation -path by issuing +The HTML, PDF and if available Info files can be installed into the +standard documentation path by issuing @example make web-install @@ -239,13 +239,34 @@ make web-install @noindent This also installs Info documentation with images if the installation -prefix is properly set; otherwise, instructions for manual installation -of Info documentation are printed on standard output. +prefix is properly set; otherwise, instructions to complete proper +installation of Info documentation are printed on standard output. -It is also possible to build a documentation tree in -@file{out-www/online-root/}, with special processing, so it can be used -on a website with content negotiation for automatic language selection; -this can be achieved by issuing +Compilation of documentation in Info format with images can be done +separately by issuing + +@example +make info +@end example + +@noindent +Separate installation of this documentation is done by issuing + +@example +make info-install +@end example + +@noindent +Note that to get the images in Info documentation, @code{web-install} +target creates symbolic links to HTML and PDF installed documentation +tree in @file{@var{prefix}/share/info}, in order to save disk space, +whereas @code{info-install} copies images in +@file{@var{prefix}/share/info} subdirectories. + +It is possible to build a documentation tree in +@file{out-www/online-root/}, with special processing, so it can be +used on a website with content negotiation for automatic language +selection; this can be achieved by issuing @example make WEB_TARGETS=online web @@ -269,12 +290,14 @@ make help @noindent from every directory in the build tree. Most targets for documentation maintenance are available from @file{Documentation/}; -for more information, see @file{Documentation/user/README.txt} and -@file{Documentation/TRANSLATION}. +@c FIXME: xref to CG +for more information, see the Contributors' Guide, section +@emph{Documentation work}. The makefile variable @code{QUIET_BUILD} may be set to @code{1} for a less verbose build output, just like for building the programs. + @knownissues The most time consuming task for building the documentation is running diff --git a/Documentation/user/introduction.itely b/Documentation/user/introduction.itely index a27db04c10..b031f13ab3 100644 --- a/Documentation/user/introduction.itely +++ b/Documentation/user/introduction.itely @@ -109,8 +109,8 @@ much thicker than lines in the computer edition. @end ifnottex @end ifnotinfo @ifinfo -@image{lilypond/henle-flat-bw,,,png} @image{lilypond/baer-flat-bw,,,png} -@image{lilypond/lily-flat-bw,,,png} +@image{lilypond/henle-flat-bw,,,,png} @image{lilypond/baer-flat-bw,,,,png} +@image{lilypond/lily-flat-bw,,,,png} @end ifinfo @item @tab diff --git a/GNUmakefile.in b/GNUmakefile.in index 1039ff3232..aee8bfe20b 100644 --- a/GNUmakefile.in +++ b/GNUmakefile.in @@ -74,6 +74,12 @@ dist-toplevel-txt-files: do-top-doc doc: $(MAKE) -C Documentation +info: + $(foreach d, $(INFO_DIRECTORIES),$(MAKE) -C $(d) out=www info && ) true + +info-install: info + $(MAKE) out=www COPY_INFO_IMAGES=1 install-info-WWW + install-help2man: $(MAKE) -C scripts man install-help2man $(MAKE) -C lily man install-help2man @@ -85,10 +91,7 @@ install-WWW: rsync -rl --exclude='*.signature' $(outdir)/offline-root/ $(DESTDIR)$(webdir) install-info-WWW: - $(MAKE) -C Documentation/user install-info - $(MAKE) -C input/lsr install-info - (cd $(DESTDIR)$(infodir) && rm -f lilypond && ln -sf $$($(PYTHON) $(buildscript-dir)/relative $(DESTDIR)$(webdir)/Documentation/user) lilypond) - (cd $(DESTDIR)$(infodir) && rm -f lilypond-snippets && ln -sf $$($(PYTHON) $(buildscript-dir)/relative $(DESTDIR)$(webdir)/input/lsr) lilypond-snippets) + $(foreach d, $(INFO_DIRECTORIES),$(MAKE) -C $(d) install-info && ) true web-install: $(MAKE) out=www install-WWW diff --git a/scripts/build/relative.py b/scripts/build/relative.py index cb1da88433..f62e7a80a2 100755 --- a/scripts/build/relative.py +++ b/scripts/build/relative.py @@ -10,7 +10,7 @@ def relative (dir, r=os.getcwd ()): if prefix == len (dir): return './' if prefix > 1: - return '../' * len (r[prefix:].split ('/')) + dir[prefix:] + return '../' * (len (r[prefix:].split ('/')) - 1) + dir[prefix:] return dir if __name__ == '__main__': diff --git a/stepmake/stepmake/generic-vars.make b/stepmake/stepmake/generic-vars.make index 31c81d2018..f4c8436494 100644 --- a/stepmake/stepmake/generic-vars.make +++ b/stepmake/stepmake/generic-vars.make @@ -69,6 +69,9 @@ endif LANG= export LANG + +INFO_DIRECTORIES = Documentation/user input/lsr + # clean file lists: # ERROR_LOG = 2> /dev/null diff --git a/stepmake/stepmake/texinfo-rules.make b/stepmake/stepmake/texinfo-rules.make index 3f605b2a28..351a1cc2d8 100644 --- a/stepmake/stepmake/texinfo-rules.make +++ b/stepmake/stepmake/texinfo-rules.make @@ -34,7 +34,7 @@ $(outdir)/%.html: $(outdir)/%.texi $(XREF_MAPS_DIR)/%.xref-map $(outdir)/version $(TEXI2HTML) --I=$(src-dir) --I=$(outdir) --output=$@ $(TEXI2HTML_INIT) $< cp $(top-src-dir)/Documentation/lilypond*.css $(dir $@) -$(outdir)/%/index.html: $(outdir)/%.texi $(XREF_MAPS_DIR)/%.xref-map $(outdir)/version.itexi +$(outdir)/%/index.html: $(outdir)/%.texi $(XREF_MAPS_DIR)/%.xref-map $(outdir)/version.itexi $(outdir)/%.html.omf mkdir -p $(dir $@) $(TEXI2HTML) --I=$(src-dir) --I=$(outdir) --output=$(dir $@) --prefix=index --split=section $(TEXI2HTML_INIT) $< cp $(top-src-dir)/Documentation/lilypond*.css $(dir $@) @@ -46,10 +46,7 @@ $(outdir)/%.html.omf: %.texi $(outdir)/%.pdf.omf: %.texi $(call GENERATE_OMF,pdf) -$(outdir)/%.ps.gz.omf: %.texi - $(call GENERATE_OMF,ps.gz) - -$(outdir)/%.pdf: $(outdir)/%.texi $(outdir)/version.itexi +$(outdir)/%.pdf: $(outdir)/%.texi $(outdir)/version.itexi $(outdir)/%.pdf.omf cd $(outdir); texi2pdf $(TEXI2PDF_FLAGS) -I $(abs-src-dir) --batch $(TEXINFO_PAPERSIZE_OPTION) $(