mirror of
https://github.com/weechat/weechat.git
synced 2026-07-07 02:05:41 +02:00
doc: document /theme command and theme file format
Add the "Themes" section to user guides and plugin API references in every language where the corresponding adoc exists. User guide (10 files): English (the new prose) and French (a full translation, with section title "Thèmes"). For the other languages — German, Italian, Japanese, Polish, Serbian — the body is the English text with only the section title localized where the existing Colors section is localized (Themen / Motywy / Теме); Italian and Japanese keep the English "Themes" title to match their existing English-only section titles. Coverage by file: - doc/en/weechat_user.en.adoc (new English section) - doc/fr/weechat_user.fr.adoc (full French translation) - doc/de/weechat_user.de.adoc (English body, "Themen" title) - doc/it/weechat_user.it.adoc (English body and title) - doc/ja/weechat_user.ja.adoc (English body and title) - doc/pl/weechat_user.pl.adoc (English body, "Motywy" title) - doc/sr/weechat_user.sr.adoc (English body, "Теме" title) Plugin API reference (5 files): same approach — English plus full French translation; Italian, Japanese and Serbian keep the English body with their conventional section title: - doc/en/weechat_plugin_api.en.adoc (new English section) - doc/fr/weechat_plugin_api.fr.adoc (full French translation) - doc/it/weechat_plugin_api.it.adoc (English body and title) - doc/ja/weechat_plugin_api.ja.adoc (English body and title) - doc/sr/weechat_plugin_api.sr.adoc (English body, "Теме" title) User-guide content covers themable options, /theme apply with the automatic backup mechanism, /theme save and /theme delete with the reserved-name rules, the .theme file format with a sample, and the user-file-shadows-built-in resolution order. The API-reference content documents weechat_theme_register (prototype, arguments, return value, C example, Python example) with notes on the themable flag and per-script auto-cleanup on script unload. The /theme command's CMD_ARGS_DESC help text and the cmdline option descriptions are picked up automatically by the doc generator (doc-autogen), so no manual entries are needed there.
This commit is contained in:
Sébastien Helleu
File diff suppressed because it is too large
Load Diff
@@ -9627,6 +9627,89 @@ elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_ERROR:
|
||||
# ...
|
||||
----
|
||||
|
||||
[[themes]]
|
||||
=== Themes
|
||||
|
||||
Functions to contribute color (and other themable option) overrides to
|
||||
built-in themes. See the
|
||||
link:weechat_user.en.html#themes[user's guide / Themes] section for the
|
||||
end-user side and the `+/theme+` command.
|
||||
|
||||
==== theme_register
|
||||
|
||||
_WeeChat ≥ 4.10.0._
|
||||
|
||||
Register a contribution of option overrides under a named theme. The
|
||||
caller's plugin is the owner of the contribution; subsequent calls
|
||||
with the same theme name from the same plugin merge into the existing
|
||||
contribution (later keys win for duplicates).
|
||||
|
||||
When the calling plugin is unloaded, all its contributions are
|
||||
automatically dropped from every theme.
|
||||
|
||||
Prototype:
|
||||
|
||||
[source,c]
|
||||
----
|
||||
struct t_theme *weechat_theme_register (const char *name,
|
||||
struct t_hashtable *overrides);
|
||||
----
|
||||
|
||||
Arguments:
|
||||
|
||||
* _name_: theme name (for example `+light+` or a custom name)
|
||||
* _overrides_: hashtable mapping full option names
|
||||
(e.g. `+irc.color.input_nick+`) to their string values; the caller
|
||||
retains ownership and may free the hashtable right after the call
|
||||
|
||||
Return value:
|
||||
|
||||
* pointer to the registered theme (existing or newly created), NULL on
|
||||
error
|
||||
|
||||
C example:
|
||||
|
||||
[source,c]
|
||||
----
|
||||
struct t_hashtable *overrides = weechat_hashtable_new (
|
||||
8,
|
||||
WEECHAT_HASHTABLE_STRING,
|
||||
WEECHAT_HASHTABLE_STRING,
|
||||
NULL, NULL);
|
||||
if (overrides)
|
||||
{
|
||||
weechat_hashtable_set (overrides, "irc.color.input_nick", "cyan");
|
||||
weechat_hashtable_set (overrides, "irc.color.topic_old", "darkgray");
|
||||
weechat_theme_register ("light", overrides);
|
||||
weechat_hashtable_free (overrides);
|
||||
}
|
||||
----
|
||||
|
||||
Script (Python):
|
||||
|
||||
[source,python]
|
||||
----
|
||||
# prototype
|
||||
def theme_register(name: str, overrides: Dict[str, str]) -> str: ...
|
||||
|
||||
# example
|
||||
weechat.theme_register("light", {
|
||||
"irc.color.input_nick": "cyan",
|
||||
"irc.color.topic_old": "darkgray",
|
||||
})
|
||||
----
|
||||
|
||||
[NOTE]
|
||||
Only options that have the _themable_ flag will be set by `/theme apply`.
|
||||
All `*.color.*` options are themable by default; string options that
|
||||
hold `+${color:...}+` references are explicitly opted in. Entries
|
||||
targeting non-themable options are silently skipped at apply-time with
|
||||
a warning logged to the _core_ buffer.
|
||||
|
||||
[NOTE]
|
||||
When called from a script, the contribution is automatically dropped
|
||||
when the script unloads (no manual cleanup is needed).
|
||||
|
||||
[[key_bindings]]
|
||||
=== Key bindings
|
||||
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -9771,6 +9771,95 @@ elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_ERROR:
|
||||
# ...
|
||||
----
|
||||
|
||||
[[themes]]
|
||||
=== Thèmes
|
||||
|
||||
Fonctions permettant de contribuer des surcharges d'options de couleur
|
||||
(et autres options modifiables par un thème) à des thèmes intégrés.
|
||||
Voir la section
|
||||
link:weechat_user.fr.html#themes[guide utilisateur / Thèmes] pour le
|
||||
côté utilisateur final et la commande `+/theme+`.
|
||||
|
||||
==== theme_register
|
||||
|
||||
_WeeChat ≥ 4.10.0._
|
||||
|
||||
Enregistrer une contribution de surcharges d'options sous un thème
|
||||
nommé. L'extension appelante est le propriétaire de la contribution ;
|
||||
les appels suivants avec le même nom de thème depuis la même extension
|
||||
sont fusionnés dans la contribution existante (en cas de doublons, les
|
||||
dernières clés gagnent).
|
||||
|
||||
Lorsque l'extension appelante est déchargée, toutes ses contributions
|
||||
sont automatiquement retirées de tous les thèmes.
|
||||
|
||||
Prototype :
|
||||
|
||||
[source,c]
|
||||
----
|
||||
struct t_theme *weechat_theme_register (const char *name,
|
||||
struct t_hashtable *overrides);
|
||||
----
|
||||
|
||||
Paramètres :
|
||||
|
||||
* _name_ : nom du thème (par exemple `+light+` ou un nom personnalisé)
|
||||
* _overrides_ : table de hachage associant des noms d'options complets
|
||||
(par exemple `+irc.color.input_nick+`) à leurs valeurs chaîne ;
|
||||
l'appelant en conserve la propriété et peut la libérer juste après
|
||||
l'appel
|
||||
|
||||
Valeur de retour :
|
||||
|
||||
* pointeur vers le thème enregistré (existant ou nouvellement créé),
|
||||
NULL en cas d'erreur
|
||||
|
||||
Exemple en C :
|
||||
|
||||
[source,c]
|
||||
----
|
||||
struct t_hashtable *overrides = weechat_hashtable_new (
|
||||
8,
|
||||
WEECHAT_HASHTABLE_STRING,
|
||||
WEECHAT_HASHTABLE_STRING,
|
||||
NULL, NULL);
|
||||
if (overrides)
|
||||
{
|
||||
weechat_hashtable_set (overrides, "irc.color.input_nick", "cyan");
|
||||
weechat_hashtable_set (overrides, "irc.color.topic_old", "darkgray");
|
||||
weechat_theme_register ("light", overrides);
|
||||
weechat_hashtable_free (overrides);
|
||||
}
|
||||
----
|
||||
|
||||
Script (Python) :
|
||||
|
||||
[source,python]
|
||||
----
|
||||
# prototype
|
||||
def theme_register(name: str, overrides: Dict[str, str]) -> str: ...
|
||||
|
||||
# exemple
|
||||
weechat.theme_register("light", {
|
||||
"irc.color.input_nick": "cyan",
|
||||
"irc.color.topic_old": "darkgray",
|
||||
})
|
||||
----
|
||||
|
||||
[NOTE]
|
||||
Seules les options possédant le flag _themable_ seront modifiées par
|
||||
`/theme apply`. Toutes les options `*.color.*` sont modifiables par
|
||||
défaut ; les options de type chaîne contenant des références
|
||||
`+${color:...}+` sont explicitement déclarées comme modifiables. Les
|
||||
entrées ciblant des options non modifiables sont silencieusement
|
||||
ignorées au moment de l'application avec un avertissement écrit sur
|
||||
le tampon _core_.
|
||||
|
||||
[NOTE]
|
||||
Lorsqu'elle est appelée depuis un script, la contribution est
|
||||
automatiquement retirée lorsque le script est déchargé (aucun nettoyage
|
||||
manuel n'est nécessaire).
|
||||
|
||||
[[key_bindings]]
|
||||
=== Associations de touches
|
||||
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -9967,6 +9967,90 @@ elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_ERROR:
|
||||
# ...
|
||||
----
|
||||
|
||||
// TRANSLATION MISSING
|
||||
[[themes]]
|
||||
=== Themes
|
||||
|
||||
Functions to contribute color (and other themable option) overrides to
|
||||
built-in themes. See the
|
||||
link:weechat_user.it.html#themes[user's guide / Themes] section for the
|
||||
end-user side and the `+/theme+` command.
|
||||
|
||||
==== theme_register
|
||||
|
||||
_WeeChat ≥ 4.10.0._
|
||||
|
||||
Register a contribution of option overrides under a named theme. The
|
||||
caller's plugin is the owner of the contribution; subsequent calls
|
||||
with the same theme name from the same plugin merge into the existing
|
||||
contribution (later keys win for duplicates).
|
||||
|
||||
When the calling plugin is unloaded, all its contributions are
|
||||
automatically dropped from every theme.
|
||||
|
||||
Prototype:
|
||||
|
||||
[source,c]
|
||||
----
|
||||
struct t_theme *weechat_theme_register (const char *name,
|
||||
struct t_hashtable *overrides);
|
||||
----
|
||||
|
||||
Arguments:
|
||||
|
||||
* _name_: theme name (for example `+light+` or a custom name)
|
||||
* _overrides_: hashtable mapping full option names
|
||||
(e.g. `+irc.color.input_nick+`) to their string values; the caller
|
||||
retains ownership and may free the hashtable right after the call
|
||||
|
||||
Return value:
|
||||
|
||||
* pointer to the registered theme (existing or newly created), NULL on
|
||||
error
|
||||
|
||||
C example:
|
||||
|
||||
[source,c]
|
||||
----
|
||||
struct t_hashtable *overrides = weechat_hashtable_new (
|
||||
8,
|
||||
WEECHAT_HASHTABLE_STRING,
|
||||
WEECHAT_HASHTABLE_STRING,
|
||||
NULL, NULL);
|
||||
if (overrides)
|
||||
{
|
||||
weechat_hashtable_set (overrides, "irc.color.input_nick", "cyan");
|
||||
weechat_hashtable_set (overrides, "irc.color.topic_old", "darkgray");
|
||||
weechat_theme_register ("light", overrides);
|
||||
weechat_hashtable_free (overrides);
|
||||
}
|
||||
----
|
||||
|
||||
Script (Python):
|
||||
|
||||
[source,python]
|
||||
----
|
||||
# prototype
|
||||
def theme_register(name: str, overrides: Dict[str, str]) -> str: ...
|
||||
|
||||
# example
|
||||
weechat.theme_register("light", {
|
||||
"irc.color.input_nick": "cyan",
|
||||
"irc.color.topic_old": "darkgray",
|
||||
})
|
||||
----
|
||||
|
||||
[NOTE]
|
||||
Only options that have the _themable_ flag will be set by `/theme apply`.
|
||||
All `*.color.*` options are themable by default; string options that
|
||||
hold `+${color:...}+` references are explicitly opted in. Entries
|
||||
targeting non-themable options are silently skipped at apply-time with
|
||||
a warning logged to the _core_ buffer.
|
||||
|
||||
[NOTE]
|
||||
When called from a script, the contribution is automatically dropped
|
||||
when the script unloads (no manual cleanup is needed).
|
||||
|
||||
[[key_bindings]]
|
||||
=== Combinazione tasti
|
||||
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -9746,6 +9746,90 @@ elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_ERROR:
|
||||
# ...
|
||||
----
|
||||
|
||||
// TRANSLATION MISSING
|
||||
[[themes]]
|
||||
=== Themes
|
||||
|
||||
Functions to contribute color (and other themable option) overrides to
|
||||
built-in themes. See the
|
||||
link:weechat_user.ja.html#themes[user's guide / Themes] section for the
|
||||
end-user side and the `+/theme+` command.
|
||||
|
||||
==== theme_register
|
||||
|
||||
_WeeChat ≥ 4.10.0._
|
||||
|
||||
Register a contribution of option overrides under a named theme. The
|
||||
caller's plugin is the owner of the contribution; subsequent calls
|
||||
with the same theme name from the same plugin merge into the existing
|
||||
contribution (later keys win for duplicates).
|
||||
|
||||
When the calling plugin is unloaded, all its contributions are
|
||||
automatically dropped from every theme.
|
||||
|
||||
Prototype:
|
||||
|
||||
[source,c]
|
||||
----
|
||||
struct t_theme *weechat_theme_register (const char *name,
|
||||
struct t_hashtable *overrides);
|
||||
----
|
||||
|
||||
Arguments:
|
||||
|
||||
* _name_: theme name (for example `+light+` or a custom name)
|
||||
* _overrides_: hashtable mapping full option names
|
||||
(e.g. `+irc.color.input_nick+`) to their string values; the caller
|
||||
retains ownership and may free the hashtable right after the call
|
||||
|
||||
Return value:
|
||||
|
||||
* pointer to the registered theme (existing or newly created), NULL on
|
||||
error
|
||||
|
||||
C example:
|
||||
|
||||
[source,c]
|
||||
----
|
||||
struct t_hashtable *overrides = weechat_hashtable_new (
|
||||
8,
|
||||
WEECHAT_HASHTABLE_STRING,
|
||||
WEECHAT_HASHTABLE_STRING,
|
||||
NULL, NULL);
|
||||
if (overrides)
|
||||
{
|
||||
weechat_hashtable_set (overrides, "irc.color.input_nick", "cyan");
|
||||
weechat_hashtable_set (overrides, "irc.color.topic_old", "darkgray");
|
||||
weechat_theme_register ("light", overrides);
|
||||
weechat_hashtable_free (overrides);
|
||||
}
|
||||
----
|
||||
|
||||
Script (Python):
|
||||
|
||||
[source,python]
|
||||
----
|
||||
# prototype
|
||||
def theme_register(name: str, overrides: Dict[str, str]) -> str: ...
|
||||
|
||||
# example
|
||||
weechat.theme_register("light", {
|
||||
"irc.color.input_nick": "cyan",
|
||||
"irc.color.topic_old": "darkgray",
|
||||
})
|
||||
----
|
||||
|
||||
[NOTE]
|
||||
Only options that have the _themable_ flag will be set by `/theme apply`.
|
||||
All `*.color.*` options are themable by default; string options that
|
||||
hold `+${color:...}+` references are explicitly opted in. Entries
|
||||
targeting non-themable options are silently skipped at apply-time with
|
||||
a warning logged to the _core_ buffer.
|
||||
|
||||
[NOTE]
|
||||
When called from a script, the contribution is automatically dropped
|
||||
when the script unloads (no manual cleanup is needed).
|
||||
|
||||
[[key_bindings]]
|
||||
=== キー割り当て
|
||||
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -9436,6 +9436,90 @@ elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_ERROR:
|
||||
# ...
|
||||
----
|
||||
|
||||
// TRANSLATION MISSING
|
||||
[[themes]]
|
||||
=== Теме
|
||||
|
||||
Functions to contribute color (and other themable option) overrides to
|
||||
built-in themes. See the
|
||||
link:weechat_user.sr.html#themes[user's guide / Themes] section for the
|
||||
end-user side and the `+/theme+` command.
|
||||
|
||||
==== theme_register
|
||||
|
||||
_WeeChat ≥ 4.10.0._
|
||||
|
||||
Register a contribution of option overrides under a named theme. The
|
||||
caller's plugin is the owner of the contribution; subsequent calls
|
||||
with the same theme name from the same plugin merge into the existing
|
||||
contribution (later keys win for duplicates).
|
||||
|
||||
When the calling plugin is unloaded, all its contributions are
|
||||
automatically dropped from every theme.
|
||||
|
||||
Prototype:
|
||||
|
||||
[source,c]
|
||||
----
|
||||
struct t_theme *weechat_theme_register (const char *name,
|
||||
struct t_hashtable *overrides);
|
||||
----
|
||||
|
||||
Arguments:
|
||||
|
||||
* _name_: theme name (for example `+light+` or a custom name)
|
||||
* _overrides_: hashtable mapping full option names
|
||||
(e.g. `+irc.color.input_nick+`) to their string values; the caller
|
||||
retains ownership and may free the hashtable right after the call
|
||||
|
||||
Return value:
|
||||
|
||||
* pointer to the registered theme (existing or newly created), NULL on
|
||||
error
|
||||
|
||||
C example:
|
||||
|
||||
[source,c]
|
||||
----
|
||||
struct t_hashtable *overrides = weechat_hashtable_new (
|
||||
8,
|
||||
WEECHAT_HASHTABLE_STRING,
|
||||
WEECHAT_HASHTABLE_STRING,
|
||||
NULL, NULL);
|
||||
if (overrides)
|
||||
{
|
||||
weechat_hashtable_set (overrides, "irc.color.input_nick", "cyan");
|
||||
weechat_hashtable_set (overrides, "irc.color.topic_old", "darkgray");
|
||||
weechat_theme_register ("light", overrides);
|
||||
weechat_hashtable_free (overrides);
|
||||
}
|
||||
----
|
||||
|
||||
Script (Python):
|
||||
|
||||
[source,python]
|
||||
----
|
||||
# prototype
|
||||
def theme_register(name: str, overrides: Dict[str, str]) -> str: ...
|
||||
|
||||
# example
|
||||
weechat.theme_register("light", {
|
||||
"irc.color.input_nick": "cyan",
|
||||
"irc.color.topic_old": "darkgray",
|
||||
})
|
||||
----
|
||||
|
||||
[NOTE]
|
||||
Only options that have the _themable_ flag will be set by `/theme apply`.
|
||||
All `*.color.*` options are themable by default; string options that
|
||||
hold `+${color:...}+` references are explicitly opted in. Entries
|
||||
targeting non-themable options are silently skipped at apply-time with
|
||||
a warning logged to the _core_ buffer.
|
||||
|
||||
[NOTE]
|
||||
When called from a script, the contribution is automatically dropped
|
||||
when the script unloads (no manual cleanup is needed).
|
||||
|
||||
[[key_bindings]]
|
||||
=== Тастерске пречице
|
||||
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user