From bf7b8484cdcb3cafe39a06bf414b5ce2551ea314 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Helleu?= Date: Sun, 24 May 2026 15:36:16 +0200 Subject: [PATCH] doc: switch syntax highlighting to automatic light/dark theme with bevel on code blocks Syntax highlighting now follows the user's `prefers-color-scheme`: - Light theme uses the pygments `default` style, embedded by Asciidoctor as before. - Dark theme uses the pygments `monokai` style, generated at CMake configure time via `pygmentize` and injected into the docinfo through a `@PYGMENTS_DARK_CSS@` placeholder, scoped under `@media (prefers-color-scheme: dark)`. To support template substitution, `doc/docinfo.html` is renamed to `docinfo.html.in` and produced into the build directory via `configure_file`; all HTML targets now depend on the generated docinfo and the `docinfodir` attribute points to the binary dir. Code blocks also gain a subtle 3D bevel: - `pre` borders use theme-specific bevel colors (`--pre-bevel-light` on top/left, `--pre-bevel-dark` on bottom/right) for a raised look in both themes. - A shared `--pre-bevel-bg` surface color is applied to literalblock, listingblock and `pre.pygments`, so all code blocks sit on the same background regardless of the pygments style. - `pre { line-height: 1.25 }` is forced to keep line spacing consistent between light (Asciidoctor base `1.45`) and dark (pygments `125%`). `python3-pygments` is added to the documented build dependencies (the `pygmentize` binary it provides is required at configure time). --- doc/CMakeLists.txt | 39 ++++++++++++++++++++------- doc/de/weechat_user.de.adoc | 2 +- doc/{docinfo.html => docinfo.html.in} | 39 +++++++++------------------ doc/en/weechat_user.en.adoc | 2 +- doc/fr/weechat_user.fr.adoc | 2 +- doc/it/weechat_user.it.adoc | 2 +- doc/ja/weechat_user.ja.adoc | 2 +- doc/pl/weechat_user.pl.adoc | 2 +- doc/sr/weechat_user.sr.adoc | 2 +- 9 files changed, 49 insertions(+), 43 deletions(-) rename doc/{docinfo.html => docinfo.html.in} (90%) diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index 7f3acbfa6..6113ac43d 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -36,6 +36,25 @@ if(ENABLE_MAN OR ENABLE_DOC) find_package(Asciidoctor) if(ASCIIDOCTOR_FOUND) + # Asciidoctor embeds the light style automatically; the dark stylesheet + # is generated below and scoped via @media in docinfo.html.in. + set(PYGMENTS_LIGHT_STYLE "default") + set(PYGMENTS_DARK_STYLE "monokai") + find_program(PYGMENTIZE_EXECUTABLE pygmentize REQUIRED) + execute_process( + COMMAND "${PYGMENTIZE_EXECUTABLE}" -O "classprefix=tok-" -f html -a "pre.pygments" -S "${PYGMENTS_DARK_STYLE}" + OUTPUT_VARIABLE PYGMENTS_DARK_CSS + RESULT_VARIABLE _pygmentize_result + ) + if(NOT _pygmentize_result EQUAL 0) + message(SEND_ERROR "Failed to generate pygments CSS for dark theme (style: ${PYGMENTS_DARK_STYLE})") + endif() + configure_file( + "${CMAKE_CURRENT_SOURCE_DIR}/docinfo.html.in" + "${CMAKE_CURRENT_BINARY_DIR}/docinfo.html" + @ONLY + ) + # common asciidoctor arguments set(ASCIIDOCTOR_ARGS -v @@ -46,8 +65,8 @@ if(ENABLE_MAN OR ENABLE_DOC) -a revnumber="${VERSION}" -a sectanchors -a source-highlighter=pygments - -a pygments-style=native - -a docinfodir="${CMAKE_CURRENT_SOURCE_DIR}" + -a pygments-style=${PYGMENTS_LIGHT_STYLE} + -a docinfodir="${CMAKE_CURRENT_BINARY_DIR}" -a autogendir="${CMAKE_CURRENT_BINARY_DIR}/autogen" ) @@ -205,7 +224,7 @@ if(ENABLE_MAN OR ENABLE_DOC) OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/weechat_user.${lang}.html" COMMAND "${ASCIIDOCTOR_EXECUTABLE}" ARGS ${ASCIIDOCTOR_ARGS} ${ASCIIDOCTOR_USER_ARGS} -o "weechat_user.${lang}.html" "${CMAKE_CURRENT_SOURCE_DIR}/${lang}/weechat_user.${lang}.adoc" DEPENDS - "${CMAKE_CURRENT_SOURCE_DIR}/docinfo.html" + "${CMAKE_CURRENT_BINARY_DIR}/docinfo.html" "${CMAKE_CURRENT_SOURCE_DIR}/${lang}/weechat_user.${lang}.adoc" "${CMAKE_CURRENT_SOURCE_DIR}/${lang}/includes/attributes-${lang}.adoc" "${CMAKE_CURRENT_SOURCE_DIR}/${lang}/includes/cmdline_options.${lang}.adoc" @@ -226,7 +245,7 @@ if(ENABLE_MAN OR ENABLE_DOC) OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/weechat_plugin_api.${lang}.html" COMMAND "${ASCIIDOCTOR_EXECUTABLE}" ARGS ${ASCIIDOCTOR_ARGS} ${ASCIIDOCTOR_PLUGIN_API_ARGS} -o "weechat_plugin_api.${lang}.html" "${CMAKE_CURRENT_SOURCE_DIR}/${lang}/weechat_plugin_api.${lang}.adoc" DEPENDS - "${CMAKE_CURRENT_SOURCE_DIR}/docinfo.html" + "${CMAKE_CURRENT_BINARY_DIR}/docinfo.html" "${CMAKE_CURRENT_SOURCE_DIR}/${lang}/weechat_plugin_api.${lang}.adoc" "${CMAKE_CURRENT_SOURCE_DIR}/${lang}/includes/attributes-${lang}.adoc" doc-autogen @@ -250,7 +269,7 @@ if(ENABLE_MAN OR ENABLE_DOC) OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/weechat_scripting.${lang}.html" COMMAND "${ASCIIDOCTOR_EXECUTABLE}" ARGS ${ASCIIDOCTOR_ARGS} ${ASCIIDOCTOR_SCRIPTING_ARGS} -o "weechat_scripting.${lang}.html" "${CMAKE_CURRENT_SOURCE_DIR}/${lang}/weechat_scripting.${lang}.adoc" DEPENDS - "${CMAKE_CURRENT_SOURCE_DIR}/docinfo.html" + "${CMAKE_CURRENT_BINARY_DIR}/docinfo.html" "${CMAKE_CURRENT_SOURCE_DIR}/${lang}/weechat_scripting.${lang}.adoc" "${CMAKE_CURRENT_SOURCE_DIR}/${lang}/includes/attributes-${lang}.adoc" doc-autogen @@ -268,7 +287,7 @@ if(ENABLE_MAN OR ENABLE_DOC) OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/weechat_faq.${lang}.html" COMMAND "${ASCIIDOCTOR_EXECUTABLE}" ARGS ${ASCIIDOCTOR_ARGS} ${ASCIIDOCTOR_FAQ_ARGS} -o "weechat_faq.${lang}.html" "${CMAKE_CURRENT_SOURCE_DIR}/${lang}/weechat_faq.${lang}.adoc" DEPENDS - "${CMAKE_CURRENT_SOURCE_DIR}/docinfo.html" + "${CMAKE_CURRENT_BINARY_DIR}/docinfo.html" "${CMAKE_CURRENT_SOURCE_DIR}/${lang}/weechat_faq.${lang}.adoc" "${CMAKE_CURRENT_SOURCE_DIR}/${lang}/includes/attributes-${lang}.adoc" WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}" @@ -283,7 +302,7 @@ if(ENABLE_MAN OR ENABLE_DOC) OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/weechat_quickstart.${lang}.html" COMMAND "${ASCIIDOCTOR_EXECUTABLE}" ARGS ${ASCIIDOCTOR_ARGS} ${ASCIIDOCTOR_QUICKSTART_ARGS} -o "weechat_quickstart.${lang}.html" "${CMAKE_CURRENT_SOURCE_DIR}/${lang}/weechat_quickstart.${lang}.adoc" DEPENDS - "${CMAKE_CURRENT_SOURCE_DIR}/docinfo.html" + "${CMAKE_CURRENT_BINARY_DIR}/docinfo.html" "${CMAKE_CURRENT_SOURCE_DIR}/${lang}/weechat_quickstart.${lang}.adoc" "${CMAKE_CURRENT_SOURCE_DIR}/${lang}/includes/attributes-${lang}.adoc" WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}" @@ -298,7 +317,7 @@ if(ENABLE_MAN OR ENABLE_DOC) OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/weechat_relay_api.${lang}.html" COMMAND "${ASCIIDOCTOR_EXECUTABLE}" ARGS ${ASCIIDOCTOR_ARGS} ${ASCIIDOCTOR_RELAY_API_ARGS} -o "weechat_relay_api.${lang}.html" "${CMAKE_CURRENT_SOURCE_DIR}/${lang}/weechat_relay_api.${lang}.adoc" DEPENDS - "${CMAKE_CURRENT_SOURCE_DIR}/docinfo.html" + "${CMAKE_CURRENT_BINARY_DIR}/docinfo.html" "${CMAKE_CURRENT_SOURCE_DIR}/${lang}/weechat_relay_api.${lang}.adoc" "${CMAKE_CURRENT_SOURCE_DIR}/${lang}/includes/attributes-${lang}.adoc" "${CMAKE_CURRENT_SOURCE_DIR}/${lang}/includes/relay.${lang}.adoc" @@ -314,7 +333,7 @@ if(ENABLE_MAN OR ENABLE_DOC) OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/weechat_relay_weechat.${lang}.html" COMMAND "${ASCIIDOCTOR_EXECUTABLE}" ARGS ${ASCIIDOCTOR_ARGS} ${ASCIIDOCTOR_RELAY_WEECHAT_ARGS} -o "weechat_relay_weechat.${lang}.html" "${CMAKE_CURRENT_SOURCE_DIR}/${lang}/weechat_relay_weechat.${lang}.adoc" DEPENDS - "${CMAKE_CURRENT_SOURCE_DIR}/docinfo.html" + "${CMAKE_CURRENT_BINARY_DIR}/docinfo.html" "${CMAKE_CURRENT_SOURCE_DIR}/${lang}/weechat_relay_weechat.${lang}.adoc" "${CMAKE_CURRENT_SOURCE_DIR}/${lang}/includes/attributes-${lang}.adoc" "${CMAKE_CURRENT_SOURCE_DIR}/${lang}/includes/relay.${lang}.adoc" @@ -330,7 +349,7 @@ if(ENABLE_MAN OR ENABLE_DOC) OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/weechat_dev.${lang}.html" COMMAND "${ASCIIDOCTOR_EXECUTABLE}" ARGS ${ASCIIDOCTOR_ARGS} ${ASCIIDOCTOR_DEV_ARGS} -o "weechat_dev.${lang}.html" "${CMAKE_CURRENT_SOURCE_DIR}/${lang}/weechat_dev.${lang}.adoc" DEPENDS - "${CMAKE_CURRENT_SOURCE_DIR}/docinfo.html" + "${CMAKE_CURRENT_BINARY_DIR}/docinfo.html" "${CMAKE_CURRENT_SOURCE_DIR}/${lang}/weechat_dev.${lang}.adoc" "${CMAKE_CURRENT_SOURCE_DIR}/${lang}/includes/attributes-${lang}.adoc" WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}" diff --git a/doc/de/weechat_user.de.adoc b/doc/de/weechat_user.de.adoc index 35280001f..6e1ab8850 100644 --- a/doc/de/weechat_user.de.adoc +++ b/doc/de/weechat_user.de.adoc @@ -212,7 +212,7 @@ WeeChat optional sind: | asciidoctor | ≥ 1.5.4 | zum Erstellen der man page und der Dokumentation. -| ruby-pygments.rb | +| python3-pygments, ruby-pygments.rb | | Build Dokumentation. | libcpputest-dev | ≥ 3.4 diff --git a/doc/docinfo.html b/doc/docinfo.html.in similarity index 90% rename from doc/docinfo.html rename to doc/docinfo.html.in index 762661e3c..5d38a64eb 100644 --- a/doc/docinfo.html +++ b/doc/docinfo.html.in @@ -26,9 +26,6 @@ SPDX-License-Identifier: GPL-3.0-or-later --header-details-color: #aaa; --border: 1px solid #444; --code-bg-color: #252525; - --pre-color: #ddd; - --pre-bg-color: #202020; - --pre-code-bg-color: #202020; --keyseq-color: #777; --kbd-bg-color: #252525; --kbd-border: 1px solid #333; @@ -39,7 +36,11 @@ SPDX-License-Identifier: GPL-3.0-or-later --icon-caution-color: #bf3400; --icon-important-color: #f44336; --mark-bg-color: #007; + --pre-bevel-light: #3e3e3e; + --pre-bevel-dark: #2a2a2a; + --pre-bevel-bg: #1f1f1f; } + @PYGMENTS_DARK_CSS@ } @media (not (prefers-color-scheme: dark)), (prefers-color-scheme: light) { @@ -59,9 +60,6 @@ SPDX-License-Identifier: GPL-3.0-or-later --border: 1px solid #dddddf; --code-bg-color: #f7f7f8; --keyseq-color: #333c; - --pre-color: #353535; - --pre-bg-color: #f7f7f8; - --pre-code-bg-color: #202020; --kbd-bg-color: #f7f7f7; --kbd-border: 1px solid #ccc; --kbd-box-shadow: 0 1px 0 rgba(0, 0, 0, .2), inset 0 0 0 .1em #fff; @@ -71,6 +69,9 @@ SPDX-License-Identifier: GPL-3.0-or-later --icon-caution-color: #ff0000; --icon-important-color: #bf0000; --mark-bg-color: #9df; + --pre-bevel-light: #e5e5e7; + --pre-bevel-dark: #b4b4b8; + --pre-bevel-bg: #f6f6f7; } } @@ -145,6 +146,10 @@ code, .prettyprint { pre { color: var(--pre-color) !important; + border: 1px solid; + border-color: var(--pre-bevel-light) var(--pre-bevel-dark) var(--pre-bevel-dark) var(--pre-bevel-light); + border-radius: 3px; + line-height: 1.25; } pre > code { @@ -162,8 +167,8 @@ kbd { color: var(--body-color); } -.literalblock pre, .listingblock > .content > pre:not(.highlight), .listingblock > .content > pre[class="highlight"], .listingblock > .content > pre[class^="highlight "] { - background-color: var(--pre-bg-color); +.literalblock pre, .listingblock > .content > pre:not(.highlight), .listingblock > .content > pre[class="highlight"], .listingblock > .content > pre[class^="highlight "], pre.pygments { + background-color: var(--pre-bg-color, var(--pre-bevel-bg)); color: var(--body-color); } @@ -200,24 +205,6 @@ mark { color: var(--body-color); } -/* syntax highlighting tuning */ - -pre.pygments { - color: #ddd !important; -} - -pre.pygments .tok-cp { - color: #44cfaf; -} - -pre.pygments .tok-nc, pre.pygments .tok-nf { - color: #649fef; -} - -pre.pygments .tok-gu, pre.pygments .tok-nc, pre.pygments .tok-nn { - text-decoration: none; -} - /* asciidoctor styles tuning */ #header, #content, #footnotes, #footer { diff --git a/doc/en/weechat_user.en.adoc b/doc/en/weechat_user.en.adoc index 5170fa334..183dc87ba 100644 --- a/doc/en/weechat_user.en.adoc +++ b/doc/en/weechat_user.en.adoc @@ -210,7 +210,7 @@ WeeChat: | asciidoctor | ≥ 1.5.4 | Build man page and documentation. -| ruby-pygments.rb | +| python3-pygments, ruby-pygments.rb | | Build documentation. | libcpputest-dev | ≥ 3.4 diff --git a/doc/fr/weechat_user.fr.adoc b/doc/fr/weechat_user.fr.adoc index bf0afe9a2..658f2a98c 100644 --- a/doc/fr/weechat_user.fr.adoc +++ b/doc/fr/weechat_user.fr.adoc @@ -208,7 +208,7 @@ Le tableau suivant liste les paquets optionnels pour compiler WeeChat : | asciidoctor | ≥ 1.5.4 | Construction de la page man et de la documentation. -| ruby-pygments.rb | +| python3-pygments, ruby-pygments.rb | | Construction de la documentation. | libcpputest-dev | ≥ 3.4 diff --git a/doc/it/weechat_user.it.adoc b/doc/it/weechat_user.it.adoc index 09e5ab785..e758d66a0 100644 --- a/doc/it/weechat_user.it.adoc +++ b/doc/it/weechat_user.it.adoc @@ -245,7 +245,7 @@ WeeChat: | Build man page and documentation. // TRANSLATION MISSING -| ruby-pygments.rb | +| python3-pygments, ruby-pygments.rb | | Build documentation. // TRANSLATION MISSING diff --git a/doc/ja/weechat_user.ja.adoc b/doc/ja/weechat_user.ja.adoc index 797318bec..0e72c9733 100644 --- a/doc/ja/weechat_user.ja.adoc +++ b/doc/ja/weechat_user.ja.adoc @@ -229,7 +229,7 @@ WeeChat: | man ページと文書のビルド // TRANSLATION MISSING -| ruby-pygments.rb | +| python3-pygments, ruby-pygments.rb | | Build documentation. | libcpputest-dev | 3.4 以上 diff --git a/doc/pl/weechat_user.pl.adoc b/doc/pl/weechat_user.pl.adoc index abc5cd5fe..a31903f85 100644 --- a/doc/pl/weechat_user.pl.adoc +++ b/doc/pl/weechat_user.pl.adoc @@ -210,7 +210,7 @@ WeeChat: | asciidoctor | ≥ 1.5.4 | Tworzenie strony man i dokumentacji. -| ruby-pygments.rb | +| python3-pygments, ruby-pygments.rb | | Dokumentacja budowania. | libcpputest-dev | ≥ 3.4 diff --git a/doc/sr/weechat_user.sr.adoc b/doc/sr/weechat_user.sr.adoc index ce9834e5d..484b63650 100644 --- a/doc/sr/weechat_user.sr.adoc +++ b/doc/sr/weechat_user.sr.adoc @@ -203,7 +203,7 @@ WeeChat мора да се изгради са CMake. | asciidoctor | ≥ 1.5.4 | Изградња man странице и документације. -| ruby-pygments.rb | +| python3-pygments, ruby-pygments.rb | | Документација изградње. | libcpputest-dev | ≥ 3.4