linux-kernel.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
* [PATCH v2 0/3] docs: conf.py: Reduce texlive dependency
@ 2022-08-08  8:49 Akira Yokosawa
  2022-08-08  8:51 ` [PATCH v2 1/3] docs/conf.py: Treat mathjax as fallback math renderer Akira Yokosawa
                   ` (2 more replies)
  0 siblings, 3 replies; 10+ messages in thread
From: Akira Yokosawa @ 2022-08-08  8:49 UTC (permalink / raw)
  To: Jonathan Corbet, Mauro Carvalho Chehab
  Cc: linux-doc, Mauro Carvalho Chehab, linux-kernel, Akira Yokosawa

Hi,

This is v2 with the env variable of SPHINX_IMGMATH as suggested by
Mauro.

Changes since v1 [1]:
 - Patch 2/3: Rename LOAD_IMGMATH -> SPHINX_IMGMATH (Mauro).
 - For the series: Acked-bys from Mauro.

This was inspired from the discussion on the expected behavior of
sphinx-pre-install [2].

There was a mismatch between Mauro's intent and my expectation for
the --no-pdf option of sphinx-pre-install.

My thought was if I installed all the packages suggested from
"./scripts/sphinx-pre-install --no-pdf", "make htmldocs" should run
free of complaints of missing commands or packages.

However, I got this warning when I tried the procedure on a debian-
based container image:

    WARNING: LaTeX command 'latex' cannot be run (needed for math display),
    check the imgmath_latex setting

, or:

    WARNING: dvipng command 'dvipng' cannot be run (needed for math display),
    check the imgmath_dvipng setting

Mauro's response to my complaint was this:

> The idea of using --no-pdf is to setup an environment without LaTeX,
> meaning that math tags would only be partially parsed: basically, the
> output would be html with LaTeX-like math expressions (at least last
> time I tried).

The mismatch can be resolved by using "mathjax" for math rendering
and making "make htmldocs" be free of texlive packages.

mathjax is the default math renderer since Sphinx 1.8.  It delegates
math rendering to web browsers.  

As Mauro has pointed out, "make epubdocs" requires imgmath.

So this patch set treats mathjax as a fallback math renderer for html
docs when imgmath requirements are not met.
Existing systems which meet imgmath requirements are not affected by
this change.

Summary of math rendering in html:

         dvipng, browser             before           after
    ==========================  ===============  ================
    dvipng                      imgmath (png)    <--
    no divpng, with javascript  raw math:: code  mathjax
    no dvipng, w/o javascript   raw math:: code  raw mathjax code

Patch 1/3 adds code in conf.py so that for html docs, the imgmath
extension will be loaded only when both latex and dvipng are available.
For epub docs, imgmath will always be loaded (no change).

Patch 2/3 adds code respecting a new env variable "SPHINX_IMGMATH" which
will override the math renderer choice. This variable can be helpful
on distros such as Arch linux, Mageia, etc. whose packaging policy is
coarse-grained.

E.g., to test math rendering by mathjax, run:
    make SPHINX_IMGMATH=no htmldocs

I mentioned in the thread of [2] that imgmath can generate scalable
math images in SVG.

My plan was to implement that option as well.  But during tests under
Fedora/CentOS/openSUSE, I encountered a couple of warnings from dvisvgm.
That would be regressions on existing systems which happen to have
not-working dvisvgm along with working dvipng.  I'm thinking of adding
the SVG option later if I can figure out the minimal requirement for
dvisvgm under imgmath.

Patch 3/3 is an independent change in the LaTeX preamble for pdf docs.
Currently, xeCJK.sty provided for RHEL 9 (and its clones) is broken
due to the lack of new dependency.  As a workaround, treat the absence
of xeCJK.sty as the additional knob for skipping CJK contents.

Note: Generated LaTeX sources will be the same regardless of existence
of the "Noto Sans CJK SC" font and xeCJK.sty.

[1] v1: https://lore.kernel.org/r/12d078f5-6995-b039-7076-bdb1f372a799@gmail.com/
[2]: https://lore.kernel.org/r/3ba5a52e-cab6-05cf-a66e-adc58c467e1f@gmail.com/

        Thanks, Akira

--
Akira Yokosawa (3):
  docs/conf.py: Treat mathjax as fallback math renderer
  docs/conf.py: Respect env variable SPHINX_IMGMATH
  docs: kerneldoc-preamble: Test xeCJK.sty before loading

 Documentation/conf.py                       | 46 ++++++++++++++++++++-
 Documentation/sphinx/kerneldoc-preamble.sty | 22 +++++++---
 2 files changed, 61 insertions(+), 7 deletions(-)


base-commit: 339170d8d3da5685762619080263abb78700ab4c
-- 
2.25.1


^ permalink raw reply	[flat|nested] 10+ messages in thread

* [PATCH v2 1/3] docs/conf.py: Treat mathjax as fallback math renderer
  2022-08-08  8:49 [PATCH v2 0/3] docs: conf.py: Reduce texlive dependency Akira Yokosawa
@ 2022-08-08  8:51 ` Akira Yokosawa
  2022-08-18 17:22   ` Jonathan Corbet
  2022-08-08  8:52 ` [PATCH v2 2/3] docs/conf.py: Respect env variable SPHINX_IMGMATH Akira Yokosawa
  2022-08-08  8:53 ` [PATCH v2 3/3] docs: kerneldoc-preamble: Test xeCJK.sty before loading Akira Yokosawa
  2 siblings, 1 reply; 10+ messages in thread
From: Akira Yokosawa @ 2022-08-08  8:51 UTC (permalink / raw)
  To: Jonathan Corbet, Mauro Carvalho Chehab
  Cc: linux-doc, Mauro Carvalho Chehab, linux-kernel, Akira Yokosawa

Currently, math expressions using the "math::" directive or
the ":math:" role of Sphinx need the imgmath extension for proper
rendering in html and epub builds.
imgmath requires dvipng (and latex).
Otherwise, "make htmldocs" will complain of missing commands.

As a matter of fact, the mathjax extension is loaded by default since
Sphinx v1.8 and it is good enough for html docs without any dependency
on texlive packages.

Stop loading the imgmath extension for html docs unless requirements
for imgmath are met.

For epub docs, keep the same behavior of always loading imgmath.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Acked-by: Mauro Carvalho Chehab <mchehab@kernel.org>
---
Changes sinve v1:
 - Acked-by from Mauro

--
 Documentation/conf.py | 34 +++++++++++++++++++++++++++++++++-
 1 file changed, 33 insertions(+), 1 deletion(-)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 934727e23e0e..3ec1f845c839 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -15,6 +15,23 @@
 import sys
 import os
 import sphinx
+from subprocess import check_output
+
+# helper
+# ------
+
+def have_command(cmd, ver_opt, str_in_ver):
+    """Run ```cmd`` with ``ver_opt`` and see if ``str_in_ver`` is found
+    or not.
+    """
+
+    try:
+        ver_str = check_output([cmd, ver_opt]).decode('utf-8', 'ignore')
+        have_cmd = str_in_ver in ver_str
+    except:
+        have_cmd = False
+
+    return have_cmd
 
 # Get Sphinx version
 major, minor, patch = sphinx.version_info[:3]
@@ -106,7 +123,22 @@ else:
 autosectionlabel_prefix_document = True
 autosectionlabel_maxdepth = 2
 
-extensions.append("sphinx.ext.imgmath")
+# Load math renderer:
+# For html builder, load imgmath only when its dependencies are met.
+# mathjax is the default math renderer since Sphinx 1.8.
+have_latex =  have_command('latex', '--version', 'pdfTeX')
+have_dvipng = have_command('dvipng', '--version', 'dvipng')
+load_imgmath = ((have_latex and have_dvipng)
+                or (major == 1 and minor < 8)
+                or 'epub' in sys.argv)
+
+if load_imgmath:
+    extensions.append("sphinx.ext.imgmath")
+    math_renderer = 'imgmath'
+else:
+    math_renderer = 'mathjax'
+
+sys.stderr.write("math_renderer: %s\n" % math_renderer)
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
-- 
2.25.1



^ permalink raw reply related	[flat|nested] 10+ messages in thread

* [PATCH v2 2/3] docs/conf.py: Respect env variable SPHINX_IMGMATH
  2022-08-08  8:49 [PATCH v2 0/3] docs: conf.py: Reduce texlive dependency Akira Yokosawa
  2022-08-08  8:51 ` [PATCH v2 1/3] docs/conf.py: Treat mathjax as fallback math renderer Akira Yokosawa
@ 2022-08-08  8:52 ` Akira Yokosawa
  2022-08-18 17:24   ` Jonathan Corbet
  2022-08-08  8:53 ` [PATCH v2 3/3] docs: kerneldoc-preamble: Test xeCJK.sty before loading Akira Yokosawa
  2 siblings, 1 reply; 10+ messages in thread
From: Akira Yokosawa @ 2022-08-08  8:52 UTC (permalink / raw)
  To: Jonathan Corbet, Mauro Carvalho Chehab
  Cc: linux-doc, Mauro Carvalho Chehab, linux-kernel, Akira Yokosawa

On some distros with coarse-grained packaging policy, dvipng is
installed along with latex.  In such cases, math rendering will
use imgmath by default.  It is possible to override the choice by
specifying the option string of "-D html_math_renderer='mathjax'"
to sphinx-build (Sphinx >= 1.8).

To provide developers an easier-to-use knob, add code for an env
variable "SPHINX_IMGMATH" which overrides the automatic choice
of math renderer for html docs.

    SPHINX_IMGMATH=yes : Load imgmath even if dvipng is not found
    SPHINX_IMGMATH=no  : Don't load imgmath (fall back to mathjax)

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Acked-by: Mauro Carvalho Chehab <mchehab@kernel.org>
---
Changes since v1:
 - No logical changes.
 - Renames:
     LOAD_IMGMATH -> SPHINX_IMGMATH (Mauro),
     opt_load_imgmath -> env_sphinx_imgmath.
 - Acked-by from Mauro.

--
 Documentation/conf.py | 16 ++++++++++++++--
 1 file changed, 14 insertions(+), 2 deletions(-)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 3ec1f845c839..0b8f20e8e22c 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -128,8 +128,20 @@ autosectionlabel_maxdepth = 2
 # mathjax is the default math renderer since Sphinx 1.8.
 have_latex =  have_command('latex', '--version', 'pdfTeX')
 have_dvipng = have_command('dvipng', '--version', 'dvipng')
-load_imgmath = ((have_latex and have_dvipng)
-                or (major == 1 and minor < 8)
+load_imgmath = have_latex and have_dvipng
+
+# Respect SPHINX_IMGMATH (for html docs only)
+if 'SPHINX_IMGMATH' in os.environ:
+    env_sphinx_imgmath = os.environ['SPHINX_IMGMATH']
+    if 'yes' in env_sphinx_imgmath:
+        load_imgmath = True
+    elif 'no' in env_sphinx_imgmath:
+        load_imgmath = False
+    else: # otherwide, auto selection
+        pass
+
+# Always load imgmath for Sphinx <1.8 or for epub docs
+load_imgmath = (load_imgmath or (major == 1 and minor < 8)
                 or 'epub' in sys.argv)
 
 if load_imgmath:
-- 
2.25.1



^ permalink raw reply related	[flat|nested] 10+ messages in thread

* [PATCH v2 3/3] docs: kerneldoc-preamble: Test xeCJK.sty before loading
  2022-08-08  8:49 [PATCH v2 0/3] docs: conf.py: Reduce texlive dependency Akira Yokosawa
  2022-08-08  8:51 ` [PATCH v2 1/3] docs/conf.py: Treat mathjax as fallback math renderer Akira Yokosawa
  2022-08-08  8:52 ` [PATCH v2 2/3] docs/conf.py: Respect env variable SPHINX_IMGMATH Akira Yokosawa
@ 2022-08-08  8:53 ` Akira Yokosawa
  2022-08-11 15:33   ` Akira Yokosawa
  2022-10-18  4:24   ` Akira Yokosawa
  2 siblings, 2 replies; 10+ messages in thread
From: Akira Yokosawa @ 2022-08-08  8:53 UTC (permalink / raw)
  To: Jonathan Corbet, Mauro Carvalho Chehab
  Cc: linux-doc, Mauro Carvalho Chehab, linux-kernel, Akira Yokosawa

On distros whose texlive packaging is fine-grained, texlive-xecjk
can be installed/removed independently of other texlive packages.
Conditionally loading xeCJK depending only on the existence of the
"Noto Sans CJK SC" font might end up in xelatex error of
"xeCJK.sty not found!".

Improve the situation by testing existence of xeCJK.sty before
loading it.

This is useful on RHEL 9 and its clone distros where texlive-xecjk
doesn't work at the moment due to a missing dependency [1].
"make pdfdocs" for non-CJK contents should work after removing
texlive-xecjk.

Link: [1] https://bugzilla.redhat.com/show_bug.cgi?id=2086254
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Acked-by: Mauro Carvalho Chehab <mchehab@kernel.org>
---
Changes since v1:
 - Acked-by from Mauro.

--
 Documentation/sphinx/kerneldoc-preamble.sty | 22 +++++++++++++++------
 1 file changed, 16 insertions(+), 6 deletions(-)

diff --git a/Documentation/sphinx/kerneldoc-preamble.sty b/Documentation/sphinx/kerneldoc-preamble.sty
index 2a29cbe51396..9707e033c8c4 100644
--- a/Documentation/sphinx/kerneldoc-preamble.sty
+++ b/Documentation/sphinx/kerneldoc-preamble.sty
@@ -70,8 +70,16 @@
 
 % Translations have Asian (CJK) characters which are only displayed if
 % xeCJK is used
+\usepackage{ifthen}
+\newboolean{enablecjk}
+\setboolean{enablecjk}{false}
 \IfFontExistsTF{Noto Sans CJK SC}{
-    % Load xeCJK when CJK font is available
+    \IfFileExists{xeCJK.sty}{
+	\setboolean{enablecjk}{true}
+    }{}
+}{}
+\ifthenelse{\boolean{enablecjk}}{
+    % Load xeCJK when both the Noto Sans CJK font and xeCJK.sty are available.
     \usepackage{xeCJK}
     % Noto CJK fonts don't provide slant shape. [AutoFakeSlant] permits
     % its emulation.
@@ -196,7 +204,7 @@
     % Inactivate CJK after tableofcontents
     \apptocmd{\sphinxtableofcontents}{\kerneldocCJKoff}{}{}
     \xeCJKsetup{CJKspace = true}% For inter-phrase space of Korean TOC
-}{ % No CJK font found
+}{ % Don't enable CJK
     % Custom macros to on/off CJK and switch CJK fonts (Dummy)
     \newcommand{\kerneldocCJKon}{}
     \newcommand{\kerneldocCJKoff}{}
@@ -204,14 +212,16 @@
     %% and ignore the argument (#1) in their definitions, whole contents of
     %% CJK chapters can be ignored.
     \newcommand{\kerneldocBeginSC}[1]{%
-	%% Put a note on missing CJK fonts in place of zh_CN translation.
-	\begin{sphinxadmonition}{note}{Note on missing fonts:}
+	%% Put a note on missing CJK fonts or the xecjk package in place of
+	%% zh_CN translation.
+	\begin{sphinxadmonition}{note}{Note on missing fonts and a package:}
 	    Translations of Simplified Chinese (zh\_CN), Traditional Chinese
 	    (zh\_TW), Korean (ko\_KR), and Japanese (ja\_JP) were skipped
-	    due to the lack of suitable font families.
+	    due to the lack of suitable font families and/or the texlive-xecjk
+	    package.
 
 	    If you want them, please install ``Noto Sans CJK'' font families
-	    by following instructions from
+	    along with the texlive-xecjk package by following instructions from
 	    \sphinxcode{./scripts/sphinx-pre-install}.
 	    Having optional ``Noto Serif CJK'' font families will improve
 	    the looks of those translations.
-- 
2.25.1



^ permalink raw reply related	[flat|nested] 10+ messages in thread

* Re: [PATCH v2 3/3] docs: kerneldoc-preamble: Test xeCJK.sty before loading
  2022-08-08  8:53 ` [PATCH v2 3/3] docs: kerneldoc-preamble: Test xeCJK.sty before loading Akira Yokosawa
@ 2022-08-11 15:33   ` Akira Yokosawa
  2022-08-18 17:28     ` Jonathan Corbet
  2022-10-18  4:24   ` Akira Yokosawa
  1 sibling, 1 reply; 10+ messages in thread
From: Akira Yokosawa @ 2022-08-11 15:33 UTC (permalink / raw)
  To: Jonathan Corbet
  Cc: linux-doc, Mauro Carvalho Chehab, linux-kernel, Akira Yokosawa,
	Mauro Carvalho Chehab

Hi Jon,

On Mon, 8 Aug 2022 17:53:57 +0900, Akira Yokosawa wrote:
> On distros whose texlive packaging is fine-grained, texlive-xecjk
> can be installed/removed independently of other texlive packages.
> Conditionally loading xeCJK depending only on the existence of the
> "Noto Sans CJK SC" font might end up in xelatex error of
> "xeCJK.sty not found!".
> 
> Improve the situation by testing existence of xeCJK.sty before
> loading it.
> 
> This is useful on RHEL 9 and its clone distros where texlive-xecjk
> doesn't work at the moment due to a missing dependency [1].
> "make pdfdocs" for non-CJK contents should work after removing
> texlive-xecjk.
In hindsight, I think this qualifies as a stable material.
Let me append a couple of tags.

> 
> Link: [1] https://bugzilla.redhat.com/show_bug.cgi?id=2086254
> Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
> Acked-by: Mauro Carvalho Chehab <mchehab@kernel.org>
Fixes: 398f7abdcb7e ("docs: pdfdocs: Pull LaTeX preamble part out of conf.py")
Cc: stable@vger.kernel.org # v5.18+

Jon, it's up to you whether this one is destined for v6.0-rcX or
for the next merge window.  It has no dependency on patches 1/3
and 2/3.

        Thanks, Akira


^ permalink raw reply	[flat|nested] 10+ messages in thread

* Re: [PATCH v2 1/3] docs/conf.py: Treat mathjax as fallback math renderer
  2022-08-08  8:51 ` [PATCH v2 1/3] docs/conf.py: Treat mathjax as fallback math renderer Akira Yokosawa
@ 2022-08-18 17:22   ` Jonathan Corbet
  2022-08-19 13:50     ` Akira Yokosawa
  0 siblings, 1 reply; 10+ messages in thread
From: Jonathan Corbet @ 2022-08-18 17:22 UTC (permalink / raw)
  To: Akira Yokosawa, Mauro Carvalho Chehab
  Cc: linux-doc, Mauro Carvalho Chehab, linux-kernel, Akira Yokosawa

Akira Yokosawa <akiyks@gmail.com> writes:

> Currently, math expressions using the "math::" directive or
> the ":math:" role of Sphinx need the imgmath extension for proper
> rendering in html and epub builds.
> imgmath requires dvipng (and latex).
> Otherwise, "make htmldocs" will complain of missing commands.
>
> As a matter of fact, the mathjax extension is loaded by default since
> Sphinx v1.8 and it is good enough for html docs without any dependency
> on texlive packages.
>
> Stop loading the imgmath extension for html docs unless requirements
> for imgmath are met.
>
> For epub docs, keep the same behavior of always loading imgmath.
>
> Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
> Acked-by: Mauro Carvalho Chehab <mchehab@kernel.org>
> ---
> Changes sinve v1:
>  - Acked-by from Mauro
>
> --
>  Documentation/conf.py | 34 +++++++++++++++++++++++++++++++++-
>  1 file changed, 33 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index 934727e23e0e..3ec1f845c839 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py
> @@ -15,6 +15,23 @@
>  import sys
>  import os
>  import sphinx
> +from subprocess import check_output
> +
> +# helper
> +# ------
> +
> +def have_command(cmd, ver_opt, str_in_ver):
> +    """Run ```cmd`` with ``ver_opt`` and see if ``str_in_ver`` is found
> +    or not.
> +    """
> +
> +    try:
> +        ver_str = check_output([cmd, ver_opt]).decode('utf-8', 'ignore')
> +        have_cmd = str_in_ver in ver_str
> +    except:
> +        have_cmd = False
> +
> +    return have_cmd

So this is adding infrastructure that isn't really mentioned in the
changelog.

A more fundamental comment, though, is that I have learned (the hard
way, repeatedly) that good things do not come from bare "except"
statements.  They always hide bugs.  If there is an exception you're
worried about here, please list it explicitly.

Otherwise seems good.

Thanks,

jon

^ permalink raw reply	[flat|nested] 10+ messages in thread

* Re: [PATCH v2 2/3] docs/conf.py: Respect env variable SPHINX_IMGMATH
  2022-08-08  8:52 ` [PATCH v2 2/3] docs/conf.py: Respect env variable SPHINX_IMGMATH Akira Yokosawa
@ 2022-08-18 17:24   ` Jonathan Corbet
  0 siblings, 0 replies; 10+ messages in thread
From: Jonathan Corbet @ 2022-08-18 17:24 UTC (permalink / raw)
  To: Akira Yokosawa, Mauro Carvalho Chehab
  Cc: linux-doc, Mauro Carvalho Chehab, linux-kernel, Akira Yokosawa

Akira Yokosawa <akiyks@gmail.com> writes:

> On some distros with coarse-grained packaging policy, dvipng is
> installed along with latex.  In such cases, math rendering will
> use imgmath by default.  It is possible to override the choice by
> specifying the option string of "-D html_math_renderer='mathjax'"
> to sphinx-build (Sphinx >= 1.8).
>
> To provide developers an easier-to-use knob, add code for an env
> variable "SPHINX_IMGMATH" which overrides the automatic choice
> of math renderer for html docs.
>
>     SPHINX_IMGMATH=yes : Load imgmath even if dvipng is not found
>     SPHINX_IMGMATH=no  : Don't load imgmath (fall back to mathjax)
>
> Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
> Acked-by: Mauro Carvalho Chehab <mchehab@kernel.org>
> ---
> Changes since v1:
>  - No logical changes.
>  - Renames:
>      LOAD_IMGMATH -> SPHINX_IMGMATH (Mauro),
>      opt_load_imgmath -> env_sphinx_imgmath.
>  - Acked-by from Mauro.
>
> --
>  Documentation/conf.py | 16 ++++++++++++++--
>  1 file changed, 14 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index 3ec1f845c839..0b8f20e8e22c 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py
> @@ -128,8 +128,20 @@ autosectionlabel_maxdepth = 2
>  # mathjax is the default math renderer since Sphinx 1.8.
>  have_latex =  have_command('latex', '--version', 'pdfTeX')
>  have_dvipng = have_command('dvipng', '--version', 'dvipng')
> -load_imgmath = ((have_latex and have_dvipng)
> -                or (major == 1 and minor < 8)
> +load_imgmath = have_latex and have_dvipng
> +
> +# Respect SPHINX_IMGMATH (for html docs only)
> +if 'SPHINX_IMGMATH' in os.environ:
> +    env_sphinx_imgmath = os.environ['SPHINX_IMGMATH']
> +    if 'yes' in env_sphinx_imgmath:
> +        load_imgmath = True
> +    elif 'no' in env_sphinx_imgmath:
> +        load_imgmath = False
> +    else: # otherwide, auto selection
> +        pass

That "else: pass" sequence does nothing, of course, and could be taken
out.

Otherwise fine,

jon

^ permalink raw reply	[flat|nested] 10+ messages in thread

* Re: [PATCH v2 3/3] docs: kerneldoc-preamble: Test xeCJK.sty before loading
  2022-08-11 15:33   ` Akira Yokosawa
@ 2022-08-18 17:28     ` Jonathan Corbet
  0 siblings, 0 replies; 10+ messages in thread
From: Jonathan Corbet @ 2022-08-18 17:28 UTC (permalink / raw)
  To: Akira Yokosawa
  Cc: linux-doc, Mauro Carvalho Chehab, linux-kernel, Akira Yokosawa,
	Mauro Carvalho Chehab

Akira Yokosawa <akiyks@gmail.com> writes:

> Hi Jon,
>
> On Mon, 8 Aug 2022 17:53:57 +0900, Akira Yokosawa wrote:
>> On distros whose texlive packaging is fine-grained, texlive-xecjk
>> can be installed/removed independently of other texlive packages.
>> Conditionally loading xeCJK depending only on the existence of the
>> "Noto Sans CJK SC" font might end up in xelatex error of
>> "xeCJK.sty not found!".
>> 
>> Improve the situation by testing existence of xeCJK.sty before
>> loading it.
>> 
>> This is useful on RHEL 9 and its clone distros where texlive-xecjk
>> doesn't work at the moment due to a missing dependency [1].
>> "make pdfdocs" for non-CJK contents should work after removing
>> texlive-xecjk.
> In hindsight, I think this qualifies as a stable material.
> Let me append a couple of tags.
>
>> 
>> Link: [1] https://bugzilla.redhat.com/show_bug.cgi?id=2086254
>> Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
>> Acked-by: Mauro Carvalho Chehab <mchehab@kernel.org>
> Fixes: 398f7abdcb7e ("docs: pdfdocs: Pull LaTeX preamble part out of conf.py")
> Cc: stable@vger.kernel.org # v5.18+
>
> Jon, it's up to you whether this one is destined for v6.0-rcX or
> for the next merge window.  It has no dependency on patches 1/3
> and 2/3.

OK, I've gone ahead and applied it with those tags.

Thanks,

jon

^ permalink raw reply	[flat|nested] 10+ messages in thread

* Re: [PATCH v2 1/3] docs/conf.py: Treat mathjax as fallback math renderer
  2022-08-18 17:22   ` Jonathan Corbet
@ 2022-08-19 13:50     ` Akira Yokosawa
  0 siblings, 0 replies; 10+ messages in thread
From: Akira Yokosawa @ 2022-08-19 13:50 UTC (permalink / raw)
  To: Jonathan Corbet
  Cc: linux-doc, Mauro Carvalho Chehab, linux-kernel,
	Mauro Carvalho Chehab, Akira Yokosawa

On Thu, 18 Aug 2022 11:22:24 -0600, Jonathan Corbet wrote:
> Akira Yokosawa <akiyks@gmail.com> writes:
> 
>> Currently, math expressions using the "math::" directive or
>> the ":math:" role of Sphinx need the imgmath extension for proper
>> rendering in html and epub builds.
>> imgmath requires dvipng (and latex).
>> Otherwise, "make htmldocs" will complain of missing commands.
>>
>> As a matter of fact, the mathjax extension is loaded by default since
>> Sphinx v1.8 and it is good enough for html docs without any dependency
>> on texlive packages.
>>
>> Stop loading the imgmath extension for html docs unless requirements
>> for imgmath are met.
>>
>> For epub docs, keep the same behavior of always loading imgmath.
>>
>> Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
>> Acked-by: Mauro Carvalho Chehab <mchehab@kernel.org>
>> ---
>> Changes sinve v1:
>>  - Acked-by from Mauro
>>
>> --
>>  Documentation/conf.py | 34 +++++++++++++++++++++++++++++++++-
>>  1 file changed, 33 insertions(+), 1 deletion(-)
>>
>> diff --git a/Documentation/conf.py b/Documentation/conf.py
>> index 934727e23e0e..3ec1f845c839 100644
>> --- a/Documentation/conf.py
>> +++ b/Documentation/conf.py
>> @@ -15,6 +15,23 @@
>>  import sys
>>  import os
>>  import sphinx
>> +from subprocess import check_output
>> +
>> +# helper
>> +# ------
>> +
>> +def have_command(cmd, ver_opt, str_in_ver):
>> +    """Run ```cmd`` with ``ver_opt`` and see if ``str_in_ver`` is found
>> +    or not.
>> +    """
>> +
>> +    try:
>> +        ver_str = check_output([cmd, ver_opt]).decode('utf-8', 'ignore')
>> +        have_cmd = str_in_ver in ver_str
>> +    except:
>> +        have_cmd = False
>> +
>> +    return have_cmd
> 
> So this is adding infrastructure that isn't really mentioned in the
> changelog.
Sorry for missing it.

> 
> A more fundamental comment, though, is that I have learned (the hard
> way, repeatedly) that good things do not come from bare "except"
> statements.  They always hide bugs.  If there is an exception you're
> worried about here, please list it explicitly.
I see.  Thank you for the insightful tip.

I'm more inclined to use the simpler approach of the "which()" function
defined in sphinx/kfigure.py, which is free of try-except constructs.

Will respin this along with the fix of 2/3 in a couple of days.

        Thanks, Akira

> 
> Otherwise seems good.
> 
> Thanks,
> 
> jon

^ permalink raw reply	[flat|nested] 10+ messages in thread

* Re: [PATCH v2 3/3] docs: kerneldoc-preamble: Test xeCJK.sty before loading
  2022-08-08  8:53 ` [PATCH v2 3/3] docs: kerneldoc-preamble: Test xeCJK.sty before loading Akira Yokosawa
  2022-08-11 15:33   ` Akira Yokosawa
@ 2022-10-18  4:24   ` Akira Yokosawa
  1 sibling, 0 replies; 10+ messages in thread
From: Akira Yokosawa @ 2022-10-18  4:24 UTC (permalink / raw)
  To: Jonathan Corbet, Mauro Carvalho Chehab
  Cc: linux-doc, Mauro Carvalho Chehab, linux-kernel

On Mon, 8 Aug 2022 17:53:57 +0900, Akira Yokosawa wrote:
> On distros whose texlive packaging is fine-grained, texlive-xecjk
> can be installed/removed independently of other texlive packages.
> Conditionally loading xeCJK depending only on the existence of the
> "Noto Sans CJK SC" font might end up in xelatex error of
> "xeCJK.sty not found!".
> 
> Improve the situation by testing existence of xeCJK.sty before
> loading it.
> 
> This is useful on RHEL 9 and its clone distros where texlive-xecjk
> doesn't work at the moment due to a missing dependency [1].
> "make pdfdocs" for non-CJK contents should work after removing
> texlive-xecjk.
> 
> Link: [1] https://bugzilla.redhat.com/show_bug.cgi?id=2086254
FWIW, this ticket was closed recently. It took five months. Whew...

Now EPEL 9 carries texlive-ctex and its dependencies.
It is now possible to build pdfdocs with CJK contents within the
confinement of RHEL 9 and its clones' packages as long as you are
OK with enabling EPEL 9.

        Thanks, Akira

> Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
> Acked-by: Mauro Carvalho Chehab <mchehab@kernel.org>
[...]

^ permalink raw reply	[flat|nested] 10+ messages in thread

end of thread, other threads:[~2022-10-18  4:24 UTC | newest]

Thread overview: 10+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2022-08-08  8:49 [PATCH v2 0/3] docs: conf.py: Reduce texlive dependency Akira Yokosawa
2022-08-08  8:51 ` [PATCH v2 1/3] docs/conf.py: Treat mathjax as fallback math renderer Akira Yokosawa
2022-08-18 17:22   ` Jonathan Corbet
2022-08-19 13:50     ` Akira Yokosawa
2022-08-08  8:52 ` [PATCH v2 2/3] docs/conf.py: Respect env variable SPHINX_IMGMATH Akira Yokosawa
2022-08-18 17:24   ` Jonathan Corbet
2022-08-08  8:53 ` [PATCH v2 3/3] docs: kerneldoc-preamble: Test xeCJK.sty before loading Akira Yokosawa
2022-08-11 15:33   ` Akira Yokosawa
2022-08-18 17:28     ` Jonathan Corbet
2022-10-18  4:24   ` Akira Yokosawa

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).