api: add support of format/translation of command arguments description line by line (issue #2005)

ChangeLog.adoc

@@ -37,6 +37,7 @@ New features::
   * core: add options weechat.buffer.* to save buffer properties set by user, add option `setauto` in command `/buffer` (issue #352)
   * core: add parameters and key bindings to move to edges of current area with commands `/cursor go` and `/cursor move` (issue #1282)
   * core: add variables "_chat_focused_line_bol" and "_chat_focused_line_eol" in focus data (issue #1955)
+  * api: add support of format/translation of command arguments description line by line (issue #2005)
   * api: add function string_concat (issue #2005)
   * api: add support of path to variable and hashtable comparison in function hdata_compare (issue #1066)
   * api: add infos "nick_color_ignore_case" and "nick_color_name_ignore_case" (issue #194)

doc/en/weechat_dev.en.adoc

@@ -424,6 +424,8 @@ WeeChat "core" is located in following directories:
 |          test-core-utf8.cpp         | Tests: UTF-8.
 |          test-core-util.cpp         | Tests: utility functions.
 |          test-core-sys.cpp          | Tests: system functions.
+|          hook/                      | Root of unit tests for hooks.
+|             test-hook-command.cpp   | Tests: hooks "command".
 |       gui/                          | Root of unit tests for interfaces.
 |          test-gui-bar-window.cpp    | Tests: bar window functions.
 |          test-gui-buffer.cpp        | Tests: buffer functions.

doc/fr/weechat_dev.fr.adoc

@@ -150,7 +150,7 @@ Le cœur de WeeChat est situé dans les répertoires suivants :
 |    wee-util.c                   | Quelques autres fonctions utilitaires.
 |    wee-version.c                | Fonctions pour la version de WeeChat.
 |    weechat.c                    | Fonctions principales : options de ligne de commande, démarrage.
-|    hook/                        | Hook functions.
+|    hook/                        | Fonctions "hook".
 |       wee-hook-command-run.c    | Hook "command_run".
 |       wee-hook-command.c        | Hook "command".
 |       wee-hook-completion.c     | Hook "completion".
@@ -426,6 +426,8 @@ Le cœur de WeeChat est situé dans les répertoires suivants :
 |          test-core-utf8.cpp         | Tests : UTF-8.
 |          test-core-util.cpp         | Tests : fonctions utiles.
 |          test-core-sys.cpp          | Tests : fonctions système.
+|          hook/                      | Racine des tests pour les hooks.
+|             test-hook-command.cpp   | Tests : hooks "command".
 |       gui/                          | Racine des tests unitaires pour les interfaces.
 |          test-gui-bar-window.cpp    | Tests : fonctions de fenêtres de barre.
 |          test-gui-buffer.cpp        | Tests : fonctions de tampons.

doc/ja/weechat_dev.ja.adoc

@@ -459,6 +459,10 @@ WeeChat "core" は以下のディレクトリに配置されています:
 |          test-core-util.cpp         | テスト: ユーティリティ関数
 // TRANSLATION MISSING
 |          test-core-sys.cpp          | Tests: system functions.
+// TRANSLATION MISSING
+|          hook/                      | Root of unit tests for hooks.
+// TRANSLATION MISSING
+|             test-hook-command.cpp   | Tests: hooks "command".
 |       gui/                          | インターフェースの単体テストを収める最上位ディレクトリ
 // TRANSLATION MISSING
 |          test-gui-bar-window.cpp    | Tests: bar window functions.

doc/sr/weechat_dev.sr.adoc

@@ -427,6 +427,11 @@ WeeChat „језгро” се налази у следећим директо
 |          test-core-utf8.cpp         | Тестови: UTF-8.
 |          test-core-util.cpp         | Тестови: помоћне функције.
 |          test-core-sys.cpp          | Тестови: системске функције.
+// TRANSLATION MISSING
+|          hook/                      | Root of unit tests for hooks.
+// TRANSLATION MISSING
+|             test-hook-command.cpp   | Tests: hooks "command".
+>>>>>>> 94c43287a (core: add a way to format and translate description of command arguments line by line)
 |       gui/                          | Корен unit тестова интерфејса.
 |          test-gui-bar-window.cpp    | Тестови: функције прозора траке.
 |          test-gui-buffer.cpp        | Тестови: бафер функције.

src/core/hook/wee-hook-command.h

@@ -76,6 +76,7 @@ struct t_hook_command_similar
 };
 
 extern char *hook_command_get_description (struct t_hook *hook);
+extern char *hook_command_format_args_description (const char *args_description);
 extern struct t_hook *hook_command (struct t_weechat_plugin *plugin,
                                     const char *command,
                                     const char *description,

src/core/wee-command.c

@@ -3006,7 +3006,7 @@ COMMAND_CALLBACK(help)
     struct t_weechat_plugin *ptr_plugin;
     struct t_config_option *ptr_option;
     int i, length, command_found, first_line_displayed, verbose;
-    char *string, *ptr_string, *pos_double_pipe, *pos_end;
+    char *string, *ptr_string, *pos_double_pipe, *pos_end, *args_desc;
     char empty_string[1] = { '\0' }, str_format[64];
 
     /* make C compiler happy */
@@ -3121,12 +3121,13 @@ COMMAND_CALLBACK(help)
                 gui_chat_printf (NULL, "%s",
                                  _(HOOK_COMMAND(ptr_hook, description)));
             }
-            if (HOOK_COMMAND(ptr_hook, args_description)
-                && HOOK_COMMAND(ptr_hook, args_description)[0])
+            args_desc = hook_command_format_args_description (
+                HOOK_COMMAND(ptr_hook, args_description));
+            if (args_desc)
             {
                 gui_chat_printf (NULL, "");
-                gui_chat_printf (NULL, "%s",
-                                 _(HOOK_COMMAND(ptr_hook, args_description)));
+                gui_chat_printf (NULL, "%s", args_desc);
+                free (args_desc);
             }
         }
     }

src/core/wee-command.h

@@ -82,6 +82,9 @@ struct t_gui_buffer;
         return WEECHAT_RC_ERROR;                                        \
     }
 
+#define CMD_ARGS_DESC(args...)                                          \
+    STR_CONCAT("\n", WEECHAT_HOOK_COMMAND_STR_FORMATTED, ##args)
+
 struct t_command_repeat
 {
     char *buffer_name;                 /* full buffer name                  */

src/core/wee-doc.c

@@ -256,7 +256,7 @@ doc_gen_user_commands (const char *path, const char *lang)
     struct t_hook *ptr_hook;
     struct t_arraylist *list_hooks;
     int i, list_size, length, first_cmd_plugin, first_line;
-    char old_plugin[1024], format[32], *value;
+    char old_plugin[1024], format[32], *value, *args_desc;
     const char *ptr_args, *pos_pipes, *pos_next;
 
     file = doc_gen_open_file (path, "user", "commands", lang);
@@ -365,12 +365,12 @@ doc_gen_user_commands (const char *path, const char *lang)
             }
             ptr_args = pos_next;
         }
-        if (HOOK_COMMAND(ptr_hook, args_description)
-            && HOOK_COMMAND(ptr_hook, args_description[0]))
+        args_desc = hook_command_format_args_description (
+            HOOK_COMMAND(ptr_hook, args_description));
+        if (args_desc)
         {
-            string_fprintf (file,
-                            "\n%s\n",
-                            TRANS(HOOK_COMMAND(ptr_hook, args_description)));
+            string_fprintf (file, "\n%s\n", args_desc);
+            free (args_desc);
         }
     }
 

src/core/weechat.h

@@ -48,6 +48,7 @@
     #define N_(string) (string)
     #define gettext(string) (string)
 #endif /* !defined(_) */
+#define AI(string) (string)
 
 
 #define WEECHAT_COPYRIGHT_DATE   "(C) 2003-2023"

src/plugins/weechat-plugin.h

@@ -220,6 +220,19 @@ struct timeval;
 #define WEECHAT_STR_CONCAT(separator, argz...)                          \
     weechat_string_concat (separator, ##argz, NULL)
 
+/*
+ * string used at beginning of arguments description to format the help text
+ * and translate it line by line
+ */
+#define WEECHAT_HOOK_COMMAND_STR_FORMATTED "[fmt]"
+
+/* macro to concatenate strings for description of command arguments */
+#define WEECHAT_CMD_ARGS_DESC(args...)                                  \
+    WEECHAT_STR_CONCAT(                                                 \
+        "\n",                                                           \
+        WEECHAT_HOOK_COMMAND_STR_FORMATTED,                             \
+        ##args)
+
 /*
  * macro to return error in case of missing arguments in callback of
  * hook_command
@@ -1248,6 +1261,7 @@ extern int weechat_plugin_end (struct t_weechat_plugin *plugin);
 #define NG_(single,plural,number)                                       \
     (weechat_plugin->ngettext)(single, plural, number)
 #endif /* NG_ */
+#define AI(string) (string)
 #endif /* WEECHAT_H */
 #define weechat_gettext(string) (weechat_plugin->gettext)(string)
 #define weechat_ngettext(single,plural,number)                          \

tests/CMakeLists.txt

@@ -44,6 +44,7 @@ set(LIB_WEECHAT_UNIT_TESTS_CORE_SRC
   unit/core/test-core-utf8.cpp
   unit/core/test-core-util.cpp
   unit/core/test-core-sys.cpp
+  unit/core/hook/test-hook-command.cpp
   unit/gui/test-gui-bar.cpp
   unit/gui/test-gui-bar-item.cpp
   unit/gui/test-gui-bar-item-custom.cpp

tests/tests.cpp

@@ -78,6 +78,8 @@ IMPORT_TEST_GROUP(CoreUrl);
 IMPORT_TEST_GROUP(CoreUtf8);
 IMPORT_TEST_GROUP(CoreUtil);
 IMPORT_TEST_GROUP(CoreSys);
+/* core/hook */
+IMPORT_TEST_GROUP(HookCommand);
 /* GUI */
 IMPORT_TEST_GROUP(GuiBar);
 IMPORT_TEST_GROUP(GuiBarItem);