Re: [PATCH v3 6/9] docs: pdfdocs: One-half spacing for CJK translations

[Akira Yokosawa]

On Mon, 2 Aug 2021 18:56:16 +0900, Akira Yokosawa wrote:
> CJK documents are much easier to read with a wider baseline stretch.
> Applying the onehalfspacing option of "setspace" package looks
> reasonable.
> 
> Note: \usepackage{setspace} needs to be before that of hyperref in the
> preamble.  The 'extrapackages' key (available since Sphinx 2.3) is for
> this purpose.

Sphinx versions < 2.3 ignore 'extrapackages' and generate LaTeX
sources without setspace package.
Obviously, building such LaTeX sources will end up in the error of:

    ! Undefined control sequence.
    \kerneldocCJKoff ...exeCJKinactive \singlespacing

Current requirement to build pdfdocs is Sphinx 2.4.4, but LaTeX
sources generated by 1.7.9 can at least be built prior to this change.

Jon, Mauro, do you think this is a regression?

You can skip 6/9 if you'd like. 

I'll see what can be done for compatibility with Sphinx < 2.3.

        Thanks, Akira

> 
> Signed-off-by: Akira Yokosawa <akiyks@xxxxxxxxx>
> ---
>  Documentation/conf.py                      | 9 +++++++--
>  Documentation/translations/ja_JP/howto.rst | 8 ++++++++
>  Documentation/translations/ko_KR/howto.rst | 8 ++++++++
>  3 files changed, 23 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index 2ccfe4442acc..2e54488e2480 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py
> @@ -341,6 +341,9 @@ latex_elements = {
>          verbatimhintsturnover=false,
>      ''',
>  
> +    # For CJK One-half spacing, need to be in front of hyperref
> +    'extrapackages': r'\usepackage{setspace}',
> +
>      # Additional stuff for the LaTeX preamble.
>      'preamble': '''
>  	% Prevent column squeezing of tabulary.
> @@ -405,8 +408,8 @@ latex_elements['preamble']  += '''
>  	\\newCJKfontfamily[JPsans]\\jpsans{Noto Sans CJK JP}
>  	\\newCJKfontfamily[JPmono]\\jpmono{Noto Sans Mono CJK JP}
>  	% Define custom macros to on/off CJK
> -	\\newcommand{\\kerneldocCJKon}{\\makexeCJKactive}
> -	\\newcommand{\\kerneldocCJKoff}{\\makexeCJKinactive}
> +	\\newcommand{\\kerneldocCJKon}{\\makexeCJKactive\\onehalfspacing}
> +	\\newcommand{\\kerneldocCJKoff}{\\makexeCJKinactive\\singlespacing}
>  	\\newcommand{\\kerneldocBeginSC}{%
>  	    \\begingroup%
>  	    \\scmain%
> @@ -437,6 +440,8 @@ latex_elements['preamble']  += '''
>  	    \\renewcommand{\\CJKttdefault}{JPmono}%
>  	}
>  	\\newcommand{\\kerneldocEndJP}{\\endgroup}
> +	% Single spacing in literal blocks
> +	\\fvset{baselinestretch=1}
>  	% To customize \\sphinxtableofcontents
>  	\\usepackage{etoolbox}
>  	% Inactivate CJK after tableofcontents
> diff --git a/Documentation/translations/ja_JP/howto.rst b/Documentation/translations/ja_JP/howto.rst
> index 73ebdab4ced7..d667f9d8a02a 100644
> --- a/Documentation/translations/ja_JP/howto.rst
> +++ b/Documentation/translations/ja_JP/howto.rst
> @@ -1,3 +1,7 @@
> +.. raw:: latex
> +
> +	\kerneldocCJKoff
> +
>  NOTE:
>  This is a version of Documentation/process/howto.rst translated into Japanese.
>  This document is maintained by Tsugikazu Shibata <tshibata@xxxxxxxxxxxxx>
> @@ -11,6 +15,10 @@ try to update the original English file first.
>  
>  ----------------------------------
>  
> +.. raw:: latex
> +
> +	\kerneldocCJKon
> +
>  この文書は、
>  Documentation/process/howto.rst
>  の和訳です。
> diff --git a/Documentation/translations/ko_KR/howto.rst b/Documentation/translations/ko_KR/howto.rst
> index a2bdd564c907..e3cdf0c84892 100644
> --- a/Documentation/translations/ko_KR/howto.rst
> +++ b/Documentation/translations/ko_KR/howto.rst
> @@ -1,3 +1,7 @@
> +.. raw:: latex
> +
> +	\kerneldocCJKoff
> +
>  NOTE:
>  This is a version of Documentation/process/howto.rst translated into korean
>  This document is maintained by Minchan Kim <minchan@xxxxxxxxxx>
> @@ -11,6 +15,10 @@ try to update the original English file first.
>  
>  ----------------------------------
>  
> +.. raw:: latex
> +
> +	\kerneldocCJKon
> +
>  이 문서는
>  Documentation/process/howto.rst
>  의 한글 번역입니다.
>