Build and install more documentation formats

Hi,

I have patched QEMU's "configure" script and its main makefile: Now
QEMU's documentation is also created in PDF format (using "texi2pdf"),
and the targets "install-all-doc" / "install-all" install
documentation in INFO and PDF format, too. May be others find this
feature useful.

Dirk

For response please CC me since I am no "qemu-devel" subscriber (yet).

Dirk Ullrich schrieb:
> Hi,
>
> I have patched QEMU's "configure" script and its main makefile: Now
> QEMU's documentation is also created in PDF format (using "texi2pdf"),
> and the targets "install-all-doc" / "install-all" install
> documentation in INFO and PDF format, too. May be others find this
> feature useful.
>
> Dirk
>
> For response please CC me since I am no "qemu-devel" subscriber (yet).
>
> diff --git a/Makefile b/Makefile
> index 3848627..641fdbd 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -21,7 +21,8 @@ endif
> Makefile: ;
> configure: ;
>
> -.PHONY: all clean cscope distclean dvi html info install install-doc \
> +.PHONY: all clean cscope distclean dvi pdf html info install
> install-all \
> + install-nodoc install-doc install-all-doc \
> recurse-all speed tar tarbin test build-all
>
> $(call set-vpath, $(SRC_PATH):$(SRC_PATH)/hw)
> @@ -34,6 +35,12 @@ else
> DOCS=
> endif
>
> +ifdef BUILD_DOCS
> +MORE_DOCS=qemu-doc.pdf qemu-tech.pdf qemu-doc.info qemu-tech.info
> +else
> +MORE_DOCS=
> +endif
> +
> SUBDIR_MAKEFLAGS=$(if $(V),,--no-print-directory)
> SUBDIR_DEVICES_MAK=$(patsubst %, %/config-devices.mak, $(TARGET_DIRS))
>
> @@ -65,7 +72,7 @@ defconfig:
>
> -include config-all-devices.mak
>
> -build-all: $(DOCS) $(TOOLS) recurse-all
> +build-all: $(DOCS) $(MORE_DOCS) $(TOOLS) recurse-all
>
> config-host.h: config-host.h-timestamp
> config-host.h-timestamp: config-host.mak
> @@ -160,7 +167,7 @@ distclean: clean
> rm -f config-host.mak config-host.h* config-host.ld $(DOCS)
> qemu-options.texi qemu-img-cmds.texi qemu-monitor.texi
> rm -f config-all-devices.mak
> rm -f roms/seabios/config.mak roms/vgabios/config.mak
> - rm -f qemu-{doc,tech}.{info,aux,cp,dvi,fn,info,ky,log,pg,toc,tp,vr}
> + rm -f qemu-{doc,tech}.{info,aux,cp,dvi,pdf,fn,info,ky,log,pg,toc,tp,vr}
> for d in $(TARGET_DIRS) libhw32 libhw64 libuser; do \
> rm -rf $$d || exit 1 ; \
> done
> @@ -191,7 +198,19 @@ ifdef CONFIG_POSIX
> $(INSTALL_DATA) qemu-nbd.8 "$(DESTDIR)$(mandir)/man8"
> endif
>
> -install: all $(if $(BUILD_DOCS),install-doc)
> +install-all-doc: $(MORE_DOCS) install-doc
> + $(INSTALL_DIR) "$(DESTDIR)$(docdir)"
> + $(INSTALL_DATA) qemu-doc.pdf qemu-tech.pdf "$(DESTDIR)$(docdir)"
> +ifdef CONFIG_POSIX
> + $(INSTALL_DIR) "$(DESTDIR)$(infodir)"
> + $(INSTALL_DATA) qemu-doc.info qemu-tech.info "$(DESTDIR)$(infodir)"
> + install-info --info-dir="$(DESTDIR)$(infodir)" \
> + "$(DESTDIR)$(infodir)/qemu-doc.info"
> + install-info --info-dir="$(DESTDIR)$(infodir)" \
> + "$(DESTDIR)$(infodir)/qemu-tech.info"
> +endif
> +
> +install-nodoc: all
> $(INSTALL_DIR) "$(DESTDIR)$(bindir)"
> ifneq ($(TOOLS),)
> $(INSTALL_PROG) $(STRIP_OPT) $(TOOLS) "$(DESTDIR)$(bindir)"
> @@ -207,9 +226,13 @@ endif
> $(INSTALL_DATA) $(SRC_PATH)/pc-bios/keymaps/$$x
> "$(DESTDIR)$(datadir)/keymaps"; \
> done
> for d in $(TARGET_DIRS); do \
> - $(MAKE) -C $$d $@ || exit 1 ; \
> + $(MAKE) -C $$d install || exit 1 ; \
> done
>
> +install: install-nodoc $(if $(BUILD_DOCS),install-doc)
> +
> +install-all: install-nodoc $(if $(BUILD_DOCS),install-all-doc)
> +
> # various test targets
> test speed: all
> $(MAKE) -C tests $@
> @@ -233,6 +256,9 @@ cscope:
> %.dvi: %.texi
> $(call quiet-command,texi2dvi -I . $<," GEN $@")
>
> +%.pdf: %.texi
> + $(call quiet-command,texi2pdf -I . $<," GEN $@")
> +
> qemu-options.texi: $(SRC_PATH)/qemu-options.hx
> $(call quiet-command,sh $(SRC_PATH)/hxtool -t < $< > $@," GEN $@")
>
> @@ -266,7 +292,9 @@ dvi: qemu-doc.dvi qemu-tech.dvi
>
> html: qemu-doc.html qemu-tech.html
>
> -qemu-doc.dvi qemu-doc.html qemu-doc.info: qemu-img.texi qemu-nbd.texi
> qemu-options.texi qemu-monitor.texi qemu-img-cmds.texi
> +pdf: qemu-doc.pdf qemu-tech.pdf
> +
> +qemu-doc.dvi qemu-doc.html qemu-doc.info qemu-doc.pdf: qemu-img.texi
> qemu-nbd.texi qemu-options.texi qemu-monitor.texi qemu-img-cmds.texi
>
> VERSION ?= $(shell cat VERSION)
> FILE = qemu-$(VERSION)
> diff --git a/configure b/configure
> index 42ef628..27f9a75 100755
> --- a/configure
> +++ b/configure
> @@ -1872,6 +1872,7 @@ if test "$mingw32" = "yes" ; then
> prefix="c:/Program Files/Qemu"
> fi
> mansuffix=""
> + infosuffix=""
> datasuffix=""
> confsuffix=""
> docsuffix=""
> @@ -1884,6 +1885,7 @@ else
> prefix="/usr/local"
> fi
> mansuffix="/share/man"
> + infosuffix="/share/info"
> datasuffix="/share/qemu"
> docsuffix="/share/doc/qemu"
> binsuffix="/bin"
> @@ -1897,6 +1899,7 @@ echo "BIOS directory $prefix$datasuffix"
> echo "binary directory $prefix$binsuffix"
> if test "$mingw32" = "no" ; then
> echo "Manual directory $prefix$mansuffix"
> +echo "Info directory $prefix$infosuffix"
> echo "ELF interp prefix $interp_prefix"
> fi
> echo "Source path $source_path"
> @@ -2215,6 +2218,7 @@ echo "ROMS=$roms" >> $config_host_mak
> echo "prefix=$prefix" >> $config_host_mak
> echo "bindir=\${prefix}$binsuffix" >> $config_host_mak
> echo "mandir=\${prefix}$mansuffix" >> $config_host_mak
> +echo "infodir=\${prefix}$infosuffix" >> $config_host_mak
> echo "datadir=\${prefix}$datasuffix" >> $config_host_mak
> echo "sysconfdir=$sysconfdir" >> $config_host_mak
> echo "docdir=\${prefix}$docsuffix" >> $config_host_mak
> diff --git a/qemu-doc.texi b/qemu-doc.texi
> index 2fb5c0b..eba6437 100644
> --- a/qemu-doc.texi
> +++ b/qemu-doc.texi
> @@ -6,6 +6,12 @@
> @paragraphindent 0
> @c %**end of header
>
> +@ifinfo
> +@direntry
> +* QEMU: (qemu-doc). The QEMU Emulator User Documentation.
> +@end direntry
> +@end ifinfo
> +
> @iftex
> @titlepage
> @sp 7
> diff --git a/qemu-tech.texi b/qemu-tech.texi
> index 97d8dea..52560dc 100644
> --- a/qemu-tech.texi
> +++ b/qemu-tech.texi
> @@ -6,6 +6,12 @@
> @paragraphindent 0
> @c %**end of header
>
> +@ifinfo
> +@direntry
> +* QEMU Internals: (qemu-tech). The QEMU Emulator Internals.
> +@end direntry
> +@end ifinfo
> +
> @iftex
> @titlepage
> @sp 7
>

Hi Dirk,

there is already a patch which adds pdf support:
http://lists.gnu.org/archive/html/qemu-devel/2010-01/msg02076.html
is waiting for a commit. This former patch is less noisy
by default when pdf (or dvi) files are build.

The @direntry part of your patch for qemu-*.texi is new.
If you want to get it included in the official qemu,
you should send it as a signed git patch (works best
with git send-email).

I don't know whether extended install targets are needed.
Personally, I did not miss them because I never use any
of the existing install targets.

Regards,
Stefan

Hi Stefan,

2010/2/1 Stefan Weil <weil@mail.berlios.de>:
> Dirk Ullrich schrieb:
>> Hi,
>>
>> I have patched QEMU's "configure" script and its main makefile: Now
>> QEMU's documentation is also created in PDF format (using "texi2pdf"),
>> and the targets "install-all-doc" / "install-all" install
>> documentation in INFO and PDF format, too. May be others find this
>> feature useful.
>>
>> Dirk
>>
>> For response please CC me since I am no "qemu-devel" subscriber (yet).
[...]
> Hi Dirk,
>
> there is already a patch which adds pdf support:
> http://lists.gnu.org/archive/html/qemu-devel/2010-01/msg02076.html
> is waiting for a commit. This former patch is less noisy
> by default when pdf (or dvi) files are build.
Sorry, I did not note that. Comparing with your patch the part of mine
that generates the PDF is more like a quick hack.
> The @direntry part of your patch for qemu-*.texi is new.
> If you want to get it included in the official qemu,
> you should send it as a signed git patch (works best
> with git send-email).
Yes, I will do this (at least).
>
> I don't know whether extended install targets are needed.
> Personally, I did not miss them because I never use any
> of the existing install targets.
But I missed them a lot, since I like INFO format (very convenient
from within Emacs) and (hyperlinked) PDF format (often nicer to read
than HTML - especially when creted by TeX) for documentation a lot. So
I want those formats automatically installed if available, and do not
like to copy those files by hand. But since there may be reasons not
to automatically install INFO or PDF (not to use INFO files, no TeX
installed to create the PDF, ...) documentation I've created the
additional install targets for make.
>
> Regards,
> Stefan
>
Dirk