Patchwork [2/2] Run pod2man with --utf8 option to enable utf8 in manpages

login
register
mail settings
Submitter Michael Tokarev
Date Feb. 2, 2012, 2:16 p.m.
Message ID <1328192202-23450-2-git-send-email-mjt@msgid.tls.msk.ru>
Download mbox | patch
Permalink /patch/139145/
State New
Headers show

Comments

Michael Tokarev - Feb. 2, 2012, 2:16 p.m.
This option makes no difference for manpages which contains only
ascii chars.  But for manpages with actual UTF8 characters (qemu
docs contains these), this change allows to see real characters
instead of mojibakes or substitutes.

Signed-off-By: Michael Tokarev <mjt@tls.msk.ru>
---
 Makefile |    9 +++++----
 1 files changed, 5 insertions(+), 4 deletions(-)
Peter Maydell - Feb. 2, 2012, 2:32 p.m.
On 2 February 2012 14:16, Michael Tokarev <mjt@tls.msk.ru> wrote:
> +POD2MAN = pod2man --utf8
>  qemu.1: qemu-doc.texi qemu-options.texi qemu-monitor.texi
>        $(call quiet-command, \
>          perl -Ww -- $(SRC_PATH)/scripts/texi2pod.pl $< qemu.pod && \
> -         pod2man --section=1 --center=" " --release=" " qemu.pod > $@, \
> +         $(POD2MAN) --section=1 --center=" " --release=" " qemu.pod > $@, \
>          "  GEN   $@")
>
>  qemu-img.1: qemu-img.texi qemu-img-cmds.texi
>        $(call quiet-command, \
>          perl -Ww -- $(SRC_PATH)/scripts/texi2pod.pl $< qemu-img.pod && \
> -         pod2man --section=1 --center=" " --release=" " qemu-img.pod > $@, \
> +         $(POD2MAN) --section=1 --center=" " --release=" " qemu-img.pod > $@, \
>          "  GEN   $@")
>
>  fsdev/virtfs-proxy-helper.1: fsdev/virtfs-proxy-helper.texi
>        $(call quiet-command, \
>          perl -Ww -- $(SRC_PATH)/scripts/texi2pod.pl $< fsdev/virtfs-proxy-helper.pod && \
> -         pod2man --section=1 --center=" " --release=" " fsdev/virtfs-proxy-helper.pod > $@, \
> +         $(POD2MAN) --section=1 --center=" " --release=" " fsdev/virtfs-proxy-helper.pod > $@, \
>          "  GEN   $@")
>
>  qemu-nbd.8: qemu-nbd.texi
>        $(call quiet-command, \
>          perl -Ww -- $(SRC_PATH)/scripts/texi2pod.pl $< qemu-nbd.pod && \
> -         pod2man --section=8 --center=" " --release=" " qemu-nbd.pod > $@, \
> +         $(POD2MAN) --section=8 --center=" " --release=" " qemu-nbd.pod > $@, \
>          "  GEN   $@")

So why does '--utf8' qualify as a common option that we specify just once in
the POD2MAN variable, but --center=" " and --release=" " don't?

Maybe we could reduce the duplication here with a makefile function?

-- PMM
Michael Tokarev - Feb. 2, 2012, 2:46 p.m.
On 02.02.2012 18:32, Peter Maydell wrote:
> On 2 February 2012 14:16, Michael Tokarev <mjt@tls.msk.ru> wrote:
>> +POD2MAN = pod2man --utf8
>>  qemu.1: qemu-doc.texi qemu-options.texi qemu-monitor.texi
>>        $(call quiet-command, \
>>          perl -Ww -- $(SRC_PATH)/scripts/texi2pod.pl $< qemu.pod && \
>> -         pod2man --section=1 --center=" " --release=" " qemu.pod > $@, \
>> +         $(POD2MAN) --section=1 --center=" " --release=" " qemu.pod > $@, \
[]
> So why does '--utf8' qualify as a common option that we specify just once in
> the POD2MAN variable, but --center=" " and --release=" " don't?

Maybe --release is ok here, but I don't think --center is.  Because, well,
--release is the same for every manpage (it corresponds to qemu release
number of something of this kind), but --center may actually be used one
day with different values for different manpages.

Besides, this is a task for another patch, since this one "only" thing
this patch does is addresses the --utf8 issue.  Maybe it is so trivial
that adding --release here actually does fit nicely too.  I don't care
either way, what matters is to fix the mojibake which currently exists
in qemu.1 manpage.

> Maybe we could reduce the duplication here with a makefile function?

I'm not sure it is worth the extra complexity.  The way it is now is
more visible than a function.  Just IMHO anyway.

Thanks,

/mjt
Peter Maydell - Feb. 2, 2012, 2:49 p.m.
On 2 February 2012 14:46, Michael Tokarev <mjt@tls.msk.ru> wrote:
> Besides, this is a task for another patch, since this one "only" thing
> this patch does is addresses the --utf8 issue.  Maybe it is so trivial
> that adding --release here actually does fit nicely too.  I don't care
> either way, what matters is to fix the mojibake which currently exists
> in qemu.1 manpage.

If you don't care about fixing the duplication (which I understand)
you could just add --utf8 to all the pod2man command lines.

-- PMM
Michael Tokarev - Feb. 2, 2012, 2:54 p.m.
On 02.02.2012 18:49, Peter Maydell wrote:
> On 2 February 2012 14:46, Michael Tokarev <mjt@tls.msk.ru> wrote:
>> Besides, this is a task for another patch, since this one "only" thing
>> this patch does is addresses the --utf8 issue.  Maybe it is so trivial
>> that adding --release here actually does fit nicely too.  I don't care
>> either way, what matters is to fix the mojibake which currently exists
>> in qemu.1 manpage.
> 
> If you don't care about fixing the duplication (which I understand)
> you could just add --utf8 to all the pod2man command lines.

The good side-effect of doing it like this is an ability to override
POD2MAN on command line, just in case --utf8 does not work somehow.

Thanks,

/mjt
Michael Tokarev - March 11, 2012, 9:57 a.m.
Ping?  It's been more than a month since this patch has been posted.

Maybe it is a good candidate for -trivial queue?

Thanks,

/mjt

On 02.02.2012 18:16, Michael Tokarev wrote:
> This option makes no difference for manpages which contains only
> ascii chars.  But for manpages with actual UTF8 characters (qemu
> docs contains these), this change allows to see real characters
> instead of mojibakes or substitutes.
> 
> Signed-off-By: Michael Tokarev <mjt@tls.msk.ru>
> ---
>  Makefile |    9 +++++----
>  1 files changed, 5 insertions(+), 4 deletions(-)
> 
> diff --git a/Makefile b/Makefile
> index 2560b59..737cda2 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -337,28 +337,29 @@ QMP/qmp-commands.txt: $(SRC_PATH)/qmp-commands.hx
>  qemu-img-cmds.texi: $(SRC_PATH)/qemu-img-cmds.hx
>  	$(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -t < $< > $@,"  GEN   $@")
>  
> +POD2MAN = pod2man --utf8
>  qemu.1: qemu-doc.texi qemu-options.texi qemu-monitor.texi
>  	$(call quiet-command, \
>  	  perl -Ww -- $(SRC_PATH)/scripts/texi2pod.pl $< qemu.pod && \
> -	  pod2man --section=1 --center=" " --release=" " qemu.pod > $@, \
> +	  $(POD2MAN) --section=1 --center=" " --release=" " qemu.pod > $@, \
>  	  "  GEN   $@")
>  
>  qemu-img.1: qemu-img.texi qemu-img-cmds.texi
>  	$(call quiet-command, \
>  	  perl -Ww -- $(SRC_PATH)/scripts/texi2pod.pl $< qemu-img.pod && \
> -	  pod2man --section=1 --center=" " --release=" " qemu-img.pod > $@, \
> +	  $(POD2MAN) --section=1 --center=" " --release=" " qemu-img.pod > $@, \
>  	  "  GEN   $@")
>  
>  fsdev/virtfs-proxy-helper.1: fsdev/virtfs-proxy-helper.texi
>  	$(call quiet-command, \
>  	  perl -Ww -- $(SRC_PATH)/scripts/texi2pod.pl $< fsdev/virtfs-proxy-helper.pod && \
> -	  pod2man --section=1 --center=" " --release=" " fsdev/virtfs-proxy-helper.pod > $@, \
> +	  $(POD2MAN) --section=1 --center=" " --release=" " fsdev/virtfs-proxy-helper.pod > $@, \
>  	  "  GEN   $@")
>  
>  qemu-nbd.8: qemu-nbd.texi
>  	$(call quiet-command, \
>  	  perl -Ww -- $(SRC_PATH)/scripts/texi2pod.pl $< qemu-nbd.pod && \
> -	  pod2man --section=8 --center=" " --release=" " qemu-nbd.pod > $@, \
> +	  $(POD2MAN) --section=8 --center=" " --release=" " qemu-nbd.pod > $@, \
>  	  "  GEN   $@")
>  
>  dvi: qemu-doc.dvi qemu-tech.dvi

Patch

diff --git a/Makefile b/Makefile
index 2560b59..737cda2 100644
--- a/Makefile
+++ b/Makefile
@@ -337,28 +337,29 @@  QMP/qmp-commands.txt: $(SRC_PATH)/qmp-commands.hx
 qemu-img-cmds.texi: $(SRC_PATH)/qemu-img-cmds.hx
 	$(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -t < $< > $@,"  GEN   $@")
 
+POD2MAN = pod2man --utf8
 qemu.1: qemu-doc.texi qemu-options.texi qemu-monitor.texi
 	$(call quiet-command, \
 	  perl -Ww -- $(SRC_PATH)/scripts/texi2pod.pl $< qemu.pod && \
-	  pod2man --section=1 --center=" " --release=" " qemu.pod > $@, \
+	  $(POD2MAN) --section=1 --center=" " --release=" " qemu.pod > $@, \
 	  "  GEN   $@")
 
 qemu-img.1: qemu-img.texi qemu-img-cmds.texi
 	$(call quiet-command, \
 	  perl -Ww -- $(SRC_PATH)/scripts/texi2pod.pl $< qemu-img.pod && \
-	  pod2man --section=1 --center=" " --release=" " qemu-img.pod > $@, \
+	  $(POD2MAN) --section=1 --center=" " --release=" " qemu-img.pod > $@, \
 	  "  GEN   $@")
 
 fsdev/virtfs-proxy-helper.1: fsdev/virtfs-proxy-helper.texi
 	$(call quiet-command, \
 	  perl -Ww -- $(SRC_PATH)/scripts/texi2pod.pl $< fsdev/virtfs-proxy-helper.pod && \
-	  pod2man --section=1 --center=" " --release=" " fsdev/virtfs-proxy-helper.pod > $@, \
+	  $(POD2MAN) --section=1 --center=" " --release=" " fsdev/virtfs-proxy-helper.pod > $@, \
 	  "  GEN   $@")
 
 qemu-nbd.8: qemu-nbd.texi
 	$(call quiet-command, \
 	  perl -Ww -- $(SRC_PATH)/scripts/texi2pod.pl $< qemu-nbd.pod && \
-	  pod2man --section=8 --center=" " --release=" " qemu-nbd.pod > $@, \
+	  $(POD2MAN) --section=8 --center=" " --release=" " qemu-nbd.pod > $@, \
 	  "  GEN   $@")
 
 dvi: qemu-doc.dvi qemu-tech.dvi