Re: [Qemu-devel] [PATCH v2 03/22] maint: Allow for EXAMPLES in texi2pod
On 1/4/19 5:45 PM, Eric Blake wrote: > On 12/18/18 7:46 AM, Vladimir Sementsov-Ogievskiy wrote: >> 15.12.2018 16:53, Eric Blake wrote: >>> The next commit will add an EXAMPLES section to qemu-nbd.8; >>> for that to work, we need to recognize EXAMPLES in texi2pod, >>> and we need to make all man pages be regenerated since the >>> output of texi2pod can be different. >>> >>> Signed-off-by: Eric Blake >>> > >>> +qemu.1: qemu-doc.texi qemu-options.texi qemu-monitor.texi \ >>> + qemu-monitor-info.texi scripts/texi2pod.pl >>> +qemu.1: qemu-option-trace.texi scripts/texi2pod.pl >> >> I think, no needs to add scripts/texi2pod.pl to both qemu.1: lines, as they >> should be >> merged anyway. And if you want to add line breaking anyway, it looks better >> to use one qemu.1: >> dependency line. > > Easy to fix. > >> >> On the other hand, it may be better to add MANS variable as subset of DOCS >> to combine all man page targets, >> and than do like $(MANS): scripts/texi2pod.pl.. (and recombine DOCS, using >> MANS ofcourse) Even easier (although it took me a while digging through 'info man' to learn it): $(filter %.1 %.7 %.8,$(DOCS)): scripts/texi2pod.pl although the dependency must be listed AFTER any more specific rule (since rules.mak has a %.1: pattern rule which expands $< to the first dependency, and we do not want scripts/texi2pod.pl to be treated as our first dependency). >> Hm, and I don't see here docs/interop/qemu-ga-ref.7 and >> docs/interop/qemu-qmp-ref.7, >> which exist in DOCS. They are there, just harder to see (hence why my v2 missed them). Of course, doing the generic dependency is better than editing every single man file listing. > > Oh, good point. The .txt files should also have the dependency Or not. The .txt output files depend on the .texi source, not on the generated .1 page; only the files that used scripts/texi2pod.pl need to depend on that, and based on rules.mk, that is only the 3 man page categories. -- Eric Blake, Principal Software Engineer Red Hat, Inc. +1-919-301-3226 Virtualization: qemu.org | libvirt.org signature.asc Description: OpenPGP digital signature
Re: [Qemu-devel] [PATCH v2 03/22] maint: Allow for EXAMPLES in texi2pod
On 12/18/18 7:46 AM, Vladimir Sementsov-Ogievskiy wrote: > 15.12.2018 16:53, Eric Blake wrote: >> The next commit will add an EXAMPLES section to qemu-nbd.8; >> for that to work, we need to recognize EXAMPLES in texi2pod, >> and we need to make all man pages be regenerated since the >> output of texi2pod can be different. >> >> Signed-off-by: Eric Blake >> >> +qemu.1: qemu-doc.texi qemu-options.texi qemu-monitor.texi \ >> +qemu-monitor-info.texi scripts/texi2pod.pl >> +qemu.1: qemu-option-trace.texi scripts/texi2pod.pl > > I think, no needs to add scripts/texi2pod.pl to both qemu.1: lines, as they > should be > merged anyway. And if you want to add line breaking anyway, it looks better > to use one qemu.1: > dependency line. Easy to fix. > > On the other hand, it may be better to add MANS variable as subset of DOCS to > combine all man page targets, > and than do like $(MANS): scripts/texi2pod.pl.. (and recombine DOCS, using > MANS ofcourse) > Hm, and I don't see here docs/interop/qemu-ga-ref.7 and > docs/interop/qemu-qmp-ref.7, > which exist in DOCS. Oh, good point. The .txt files should also have the dependency - in general, ALL generated documentation should depend on the generator, not just the man pages. I'll have to think about respinning this patch. -- Eric Blake, Principal Software Engineer Red Hat, Inc. +1-919-301-3226 Virtualization: qemu.org | libvirt.org signature.asc Description: OpenPGP digital signature
Re: [Qemu-devel] [PATCH v2 03/22] maint: Allow for EXAMPLES in texi2pod
15.12.2018 16:53, Eric Blake wrote:
> The next commit will add an EXAMPLES section to qemu-nbd.8;
> for that to work, we need to recognize EXAMPLES in texi2pod,
> and we need to make all man pages be regenerated since the
> output of texi2pod can be different.
>
> Signed-off-by: Eric Blake
>
> ---
> v2: new patch
> ---
> Makefile| 18 ++
> scripts/texi2pod.pl | 2 +-
> 2 files changed, 11 insertions(+), 9 deletions(-)
>
> diff --git a/Makefile b/Makefile
> index c8b9efdad4b..0bd204eff8a 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -824,14 +824,16 @@ docs/interop/qemu-qmp-qapi.texi: qapi/qapi-doc.texi
> docs/interop/qemu-ga-qapi.texi: qga/qapi-generated/qga-qapi-doc.texi
> @cp -p $< $@
>
> -qemu.1: qemu-doc.texi qemu-options.texi qemu-monitor.texi
> qemu-monitor-info.texi
> -qemu.1: qemu-option-trace.texi
> -qemu-img.1: qemu-img.texi qemu-option-trace.texi qemu-img-cmds.texi
> -fsdev/virtfs-proxy-helper.1: fsdev/virtfs-proxy-helper.texi
> -qemu-nbd.8: qemu-nbd.texi qemu-option-trace.texi
> -qemu-ga.8: qemu-ga.texi
> -docs/qemu-block-drivers.7: docs/qemu-block-drivers.texi
> -docs/qemu-cpu-models.7: docs/qemu-cpu-models.texi
> +qemu.1: qemu-doc.texi qemu-options.texi qemu-monitor.texi \
> + qemu-monitor-info.texi scripts/texi2pod.pl
> +qemu.1: qemu-option-trace.texi scripts/texi2pod.pl
I think, no needs to add scripts/texi2pod.pl to both qemu.1: lines, as they
should be
merged anyway. And if you want to add line breaking anyway, it looks better to
use one qemu.1:
dependency line.
On the other hand, it may be better to add MANS variable as subset of DOCS to
combine all man page targets,
and than do like $(MANS): scripts/texi2pod.pl.. (and recombine DOCS, using MANS
ofcourse)
Hm, and I don't see here docs/interop/qemu-ga-ref.7 and
docs/interop/qemu-qmp-ref.7,
which exist in DOCS.
On the third hand, I'm unsure about how all this work, where are rules for
these targets,
and should not we add this dependency for all DOCS targets :)
> +qemu-img.1: qemu-img.texi qemu-option-trace.texi qemu-img-cmds.texi \
> + scripts/texi2pod.pl
> +fsdev/virtfs-proxy-helper.1: fsdev/virtfs-proxy-helper.texi
> scripts/texi2pod.pl
> +qemu-nbd.8: qemu-nbd.texi qemu-option-trace.texi scripts/texi2pod.pl
> +qemu-ga.8: qemu-ga.texi scripts/texi2pod.pl
> +docs/qemu-block-drivers.7: docs/qemu-block-drivers.texi scripts/texi2pod.pl
> +docs/qemu-cpu-models.7: docs/qemu-cpu-models.texi scripts/texi2pod.pl
>
> html: qemu-doc.html docs/interop/qemu-qmp-ref.html
> docs/interop/qemu-ga-ref.html
> info: qemu-doc.info docs/interop/qemu-qmp-ref.info
> docs/interop/qemu-ga-ref.info
> diff --git a/scripts/texi2pod.pl b/scripts/texi2pod.pl
> index 39ce584a322..839b7917cf7 100755
> --- a/scripts/texi2pod.pl
> +++ b/scripts/texi2pod.pl
> @@ -398,7 +398,7 @@ $sects{NAME} = "$fn \- $tl\n";
> $sects{FOOTNOTES} .= "=back\n" if exists $sects{FOOTNOTES};
>
> for $sect (qw(NAME SYNOPSIS DESCRIPTION OPTIONS ENVIRONMENT FILES
> - BUGS NOTES FOOTNOTES SEEALSO AUTHOR COPYRIGHT)) {
> + BUGS NOTES FOOTNOTES EXAMPLES SEEALSO AUTHOR COPYRIGHT)) {
> if(exists $sects{$sect}) {
> $head = $sect;
> $head =~ s/SEEALSO/SEE ALSO/;
>
--
Best regards,
Vladimir
Re: [Qemu-devel] [PATCH v2 03/22] maint: Allow for EXAMPLES in texi2pod
On Sat, Dec 15, 2018 at 07:53:05AM -0600, Eric Blake wrote:
> The next commit will add an EXAMPLES section to qemu-nbd.8;
> for that to work, we need to recognize EXAMPLES in texi2pod,
> and we need to make all man pages be regenerated since the
> output of texi2pod can be different.
>
> Signed-off-by: Eric Blake
>
> ---
> v2: new patch
> ---
> Makefile| 18 ++
> scripts/texi2pod.pl | 2 +-
> 2 files changed, 11 insertions(+), 9 deletions(-)
>
> diff --git a/Makefile b/Makefile
> index c8b9efdad4b..0bd204eff8a 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -824,14 +824,16 @@ docs/interop/qemu-qmp-qapi.texi: qapi/qapi-doc.texi
> docs/interop/qemu-ga-qapi.texi: qga/qapi-generated/qga-qapi-doc.texi
> @cp -p $< $@
>
> -qemu.1: qemu-doc.texi qemu-options.texi qemu-monitor.texi
> qemu-monitor-info.texi
> -qemu.1: qemu-option-trace.texi
> -qemu-img.1: qemu-img.texi qemu-option-trace.texi qemu-img-cmds.texi
> -fsdev/virtfs-proxy-helper.1: fsdev/virtfs-proxy-helper.texi
> -qemu-nbd.8: qemu-nbd.texi qemu-option-trace.texi
> -qemu-ga.8: qemu-ga.texi
> -docs/qemu-block-drivers.7: docs/qemu-block-drivers.texi
> -docs/qemu-cpu-models.7: docs/qemu-cpu-models.texi
> +qemu.1: qemu-doc.texi qemu-options.texi qemu-monitor.texi \
> + qemu-monitor-info.texi scripts/texi2pod.pl
> +qemu.1: qemu-option-trace.texi scripts/texi2pod.pl
> +qemu-img.1: qemu-img.texi qemu-option-trace.texi qemu-img-cmds.texi \
> + scripts/texi2pod.pl
> +fsdev/virtfs-proxy-helper.1: fsdev/virtfs-proxy-helper.texi
> scripts/texi2pod.pl
> +qemu-nbd.8: qemu-nbd.texi qemu-option-trace.texi scripts/texi2pod.pl
> +qemu-ga.8: qemu-ga.texi scripts/texi2pod.pl
> +docs/qemu-block-drivers.7: docs/qemu-block-drivers.texi scripts/texi2pod.pl
> +docs/qemu-cpu-models.7: docs/qemu-cpu-models.texi scripts/texi2pod.pl
>
> html: qemu-doc.html docs/interop/qemu-qmp-ref.html
> docs/interop/qemu-ga-ref.html
> info: qemu-doc.info docs/interop/qemu-qmp-ref.info
> docs/interop/qemu-ga-ref.info
> diff --git a/scripts/texi2pod.pl b/scripts/texi2pod.pl
> index 39ce584a322..839b7917cf7 100755
> --- a/scripts/texi2pod.pl
> +++ b/scripts/texi2pod.pl
> @@ -398,7 +398,7 @@ $sects{NAME} = "$fn \- $tl\n";
> $sects{FOOTNOTES} .= "=back\n" if exists $sects{FOOTNOTES};
>
> for $sect (qw(NAME SYNOPSIS DESCRIPTION OPTIONS ENVIRONMENT FILES
> - BUGS NOTES FOOTNOTES SEEALSO AUTHOR COPYRIGHT)) {
> + BUGS NOTES FOOTNOTES EXAMPLES SEEALSO AUTHOR COPYRIGHT)) {
> if(exists $sects{$sect}) {
> $head = $sect;
> $head =~ s/SEEALSO/SEE ALSO/;
> --
> 2.17.2
Reviewed-by: Richard W.M. Jones
Rich.
--
Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones
Read my programming and virtualization blog: http://rwmj.wordpress.com
libguestfs lets you edit virtual machines. Supports shell scripting,
bindings from many languages. http://libguestfs.org
