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.
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
@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
@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
@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
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
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
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__':
LANG=
export LANG
+
+INFO_DIRECTORIES = Documentation/user input/lsr
+
# clean file lists:
#
ERROR_LOG = 2> /dev/null
$(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 $@)
$(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) $(<F)
$(outdir)/%.txt: $(outdir)/%.texi $(outdir)/version.itexi
# This builds all .info targets with images, in out-www.
# Viewable with a recent Emacs, doing: C-u C-h i out-www/lilypond.info
+ifneq ($(COPY_INFO_IMAGES),)
+# only Info docs are installed (not HTML nor PDF),
+# so images should be copied
+
+install-info-images:
+# remove $(infodir)/$(INFO_IMAGES_DIR) in case it is a symlink
+ -rm -f $(DESTDIR)$(infodir)/$(INFO_IMAGES_DIR)
+ $(INSTALL) -d $(DESTDIR)$(infodir)/$(INFO_IMAGES_DIR)
+ rsync -r --include '[0-9a-f][0-9a-f]' --include '*.png' --exclude '*' $(outdir)/ $(DESTDIR)$(infodir)/$(INFO_IMAGES_DIR)/
+
+uninstall-info-images:
+ rm -f $(DESTDIR)$(infodir)/$(INFO_IMAGES_DIR) || rm -rf $(DESTDIR)$(infodir)/$(INFO_IMAGES_DIR)
+
+else # if HTML and PDF docs are installed too, symlink image directories
+install-info-images: uninstall-info-images
+ cd $(DESTDIR)$(infodir) && ln -sf $$($(PYTHON) $(buildscript-dir)/relative $(DESTDIR)$(webdir)/$(DEST_INFO_IMAGES_SUBDIR)) $(INFO_IMAGES_DIR)
+
+uninstall-info-images:
+ rm -f $(DESTDIR)$(infodir)/$(INFO_IMAGES_DIR) || rm -rf $(DESTDIR)$(infodir)/$(INFO_IMAGES_DIR)
+endif # copying info images
+
+
ifneq ($(patsubst %/local,%,$(DESTDIR)$(prefix)),/usr)
-## Can not have absolute symlinks because some binary packages build schemes
-## install files in nonstandard root. Best we can do is to notify the
-## builder or packager.
+## install-info can't do all his job for binary packages build systems.
+## Best we can do is to notify the builder or packager.
local-install-info: info
-$(INSTALL) -d $(DESTDIR)$(infodir)
@echo
@echo "***************************************************************"
- @echo "Please add or update the LilyPond direntries, do"
- @echo
- @echo " install-info --info-dir=$(infodir) $(outdir)/$(MAIN_INFO_DOC).info"
- @echo
- @echo "For images in the INFO docs to work, do: "
+ @echo "Please add or update the LilyPond direntries,"
+ @echo "do or add in the postinstall script"
@echo
- @echo " (cd $(infodir) && ln -sfT ../doc/lilypond/html/$(DEST_INFO_IMAGES_SUBDIR) $(INFO_IMAGES_DIR))"
- @echo "or add something like that to the postinstall script."
+ @echo " install-info --info-dir=$(infodir) $(DESTDIR)$(infodir)/$(MAIN_INFO_DOC).info"
@echo
+ $(MAKE) install-info-images
-local-uninstall-info:
+local-uninstall-info: uninstall-info-images
-rmdir $(DESTDIR)$(infodir)
else # installing directly into standard /usr/...
-$(INSTALL) -d $(DESTDIR)$(infodir)
$(foreach f,$(INFO_FILES),install-info --remove --info-dir=$(infodir) $(f) ; )true
install-info --info-dir=$(infodir) $(outdir)/$(MAIN_INFO_DOC).info
- cd $(infodir) && ln -sfT $(webdir)/$(DEST_INFO_IMAGES_SUBDIR) $(INFO_IMAGES_DIR)
+ $(MAKE) install-info-images
-local-uninstall-info:
+local-uninstall-info: uninstall-info-images
$(foreach f,$(INFO_FILES),install-info --remove --info-dir=$(infodir) $(f) ; )true
- rm -f $(infodir)/$(INFO_IMAGES_DIR)
endif # installing directly into standard /usr/...
else # out!=www
ifneq ($(patsubst %/local,%,$(DESTDIR)$(prefix)),/usr)
-## Can not have absolute symlinks because some binary packages build schemes
-## install files in nonstandard root. Best we can do is to notify the
-## builder or packager.
+## install-info can't do all his job for binary packages build systems.
+## Best we can do is to notify the builder or packager.
local-install-info: info
-$(INSTALL) -d $(DESTDIR)$(infodir)
@echo
@echo "***************************************************************"
@echo "Please add or update the LilyPond direntries, do"
@echo
- @echo " install-info --info-dir=$(infodir) out/$(MAIN_INFO_DOC).info"
- @echo
- @echo "For images in the INFO docs to work, do"
+ @echo " install-info --info-dir=$(infodir) $(DESTDIR)$(infodir)/$(MAIN_INFO_DOC).info"
@echo
- @echo " make out=www install-info "
- @echo
- @echo "and read the extra instructions."
+ @echo "To compile Info documentation with images, please read"
+ @echo "Application Usage document, section \"Building documentation\"."
@echo
local-uninstall-info:
install-info --info-dir=$(infodir) $(outdir)/$(MAIN_INFO_DOC).info
@echo
@echo "***************************************************************"
- @echo "For images in the INFO docs to work, do"
+ @echo "To compile Info documentation with images, do from top of the build tree"
+ @echo
+ @echo " make web"
+ @echo
+ @echo "which builds documentation in all formats; to build only Info documentation, do"
+ @echo
+ @echo " make info"
+ @echo
+ @echo "To list all available targets, do"
+ @echo
+ @echo " make help"
@echo
- @echo " make out=www install-info "
+ @echo "For details, please read Application Usage document, section \"Building documentation\"."
@echo
local-uninstall-info:
dist roll tarball: $(depth)/$(outdir)/$(distname).tar.gz\n\
distclean also remove configure output\n\
doc update all documentation (without images)\n\
+ info build Info documentation with images\n\
+ info-install install Info documentation with images\n\
cvs-clean also remove out directories and generated files\n\
maintainerclean also remove distributed generated files\n\
po make new translation Portable Object database\n\