Re: [Qemu-devel] [PATCH v2 03/22] maint: Allow for EXAMPLES in texi2pod

[Vladimir Sementsov-Ogievskiy]

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 <address@hidden>
> 
> ---
> 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