Re: [PATCH] docs: sphinx-pre-install: Reword warning on installing cjk font

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

HI Akira,

Em Fri, 21 May 2021 16:14:19 +0900
Akira Yokosawa <akiyks@gmail.com> escreveu:

> Installing a ckj font as recommended by the warning message causes
> generated latex code to have:
> 
> 	% This is needed for translations
> 	\usepackage{xeCJK}
> 	\setCJKmainfont{Noto Sans CJK SC}
> 
> in its preamble even for an English document.

Yes. The same LaTeX configuration is applied to all documents.

While the standard Sphinx logic allows just one conf.py, there's
a logic on Linux that allows a per-directory configuration.
Perhaps it would be possible to set the font just for translations.

Yet, this can't be easily done per-translation - Italian
translation for instance doesn't need CJK fonts.

> The package "xeCJK" changes wide characters' appearance including
> apostrophe (single quote) and double quotes, and it changes line-break
> behavior with regard to the boundary of narrow and wide characters.
> 
> This greatly degrades readability of English PDFs typeset by xelatex.

Hmm... could you give an example where it looks ugly?

At least on the documents I use to check the PDF output, I was unable
to see any big issue.

Regards,
Mauro

> 
> As a band-aid help, reword the message and let the user at least be
> aware of the degradation.
> 
> Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
> ---
> Hello,
> 
> I'm a newcomer to kernel-doc who started trying sphinx this week.
> I have both sphinx 2.4.4 and 1.7.9 installed.
> For pdfdocs, I use 2.4.4.
> 
> "make htmldocs" was fairly easy, but I struggled a while to get
> PDFs as I expected.
> 
> The culprit turned out to be the "xeCJK" package mentioned above
> in the change log.  It appears in all the generated latex files
> due to the "Noto Sans CJK" font I have installed seeing the warning
> message from sphinx-pre-install.
> 
> By uninstalling the font, I can now build the PDF as I expect.
> 
> The reworded message is just a band-aid help.
> 
> In the long term, I see that rst2pdf tool is your hope to avoid
> LaTeX altogether.  But it would be nice if you can enable xeCJK only
> for the translations document.  Can sphinx permit such language
> choice per subdirectory (or hopefully per .rst file)?
> 
>         Thanks, Akira
> --
>  scripts/sphinx-pre-install | 7 ++++++-
>  1 file changed, 6 insertions(+), 1 deletion(-)
> 
> diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install
> index fe92020d67e3..b3c7da2b8ad2 100755
> --- a/scripts/sphinx-pre-install
> +++ b/scripts/sphinx-pre-install
> @@ -101,7 +101,12 @@ sub check_missing(%)
>  		}
>  
>  		if ($is_optional) {
> -			print "Warning: better to also install \"$prog\".\n";
> +			if ($prog =~ /cjk/ ) {
> +				print "Warning: For translations PDF, better to install \"$prog\".\n";
> +				print "However, doing so will *degrade* English PDF typesetting.\n";
> +			} else {
> +				print "Warning: better to also install \"$prog\".\n";
> +			}
>  		} else {
>  			print "ERROR: please install \"$prog\", otherwise, build won't work.\n";
>  		}



Thanks,
Mauro