[Qemu-devel] [PATCH] Build and install more documentation formats

[Qemu-devel] [PATCH] Build and install more documentation formats

[Dirk Ullrich]

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

Re: [Qemu-devel] [PATCH] Build and install more documentation formats

[Stefan Weil]

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

Re: [Qemu-devel] [PATCH] Build and install more documentation formats

[Dirk Ullrich]

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