ps: generalize help text logic, add related translator hints

This commit represents an experiment in nls help text support.

The word --help itself been made translatable along with the
help section names and their abbreviations.  Thus, the work of
the translators will ultimately alter program run-time behavior.

Perhaps someday all "long" options can behave in a similar way
which could offer a considerable benefit to other languages.
Instead of translationg just option descriptions, the long
forms of those options could also be transalated.

This commit also:
 . includes the section abbreviations in --help output
 . isolates all --help support in the ps/help.c module
 . provides (hopefully) meaningful Translator guidance
 . removes --help support from the ps/common.h header
 . removes --help support from the ps/parser.c module
 . eliminates tabs in line with the style of other ps modules
 . eliminates the need for the include/c.h header file
This commit is contained in:
Jim Warner 2012-01-02 01:33:34 -06:00 committed by Craig Small
parent b8c3288594
commit 4fb48c0bdb
5 changed files with 214 additions and 131 deletions

View File

@ -12,7 +12,6 @@
#ifndef PROCPS_PS_H #ifndef PROCPS_PS_H
#define PROCPS_PS_H #define PROCPS_PS_H
#include "../include/c.h"
#include "../include/nls.h" #include "../include/nls.h"
#include "../proc/procps.h" #include "../proc/procps.h"
#include "../proc/escape.h" #include "../proc/escape.h"
@ -27,17 +26,6 @@
/***************** GENERAL DEFINE ********************/ /***************** GENERAL DEFINE ********************/
/* usage output sections */
enum {
USAGE_DEFAULT,
USAGE_ALL,
USAGE_SELECTION,
USAGE_LIST,
USAGE_OUTPUT,
USAGE_THREADS,
USAGE_MISC
};
/* selection list */ /* selection list */
#define SEL_RUID 1 #define SEL_RUID 1
#define SEL_EUID 2 #define SEL_EUID 2
@ -325,9 +313,13 @@ extern unsigned thread_flags;
extern int unix_f_option; extern int unix_f_option;
extern int user_is_number; extern int user_is_number;
extern int wchan_is_number; extern int wchan_is_number;
extern const char *the_word_help;
/************************* PS GLOBALS *********************/ /************************* PS GLOBALS *********************/
/* display.c */
extern char *myname;
/* sortformat.c */ /* sortformat.c */
extern int defer_sf_option(const char *arg, int source); extern int defer_sf_option(const char *arg, int source);
extern const char *process_sf_options(int localbroken); extern const char *process_sf_options(int localbroken);
@ -338,7 +330,7 @@ extern int want_this_proc(proc_t *buf);
extern const char *select_bits_setup(void); extern const char *select_bits_setup(void);
/* help.c */ /* help.c */
extern void usage(FILE * out, int section) NORETURN; extern void do_help(const char *opt, int rc) NORETURN;
/* global.c */ /* global.c */
extern void self_info(void); extern void self_info(void);

View File

@ -34,6 +34,8 @@
#define SIGCHLD SIGCLD #define SIGCHLD SIGCLD
#endif #endif
char *myname;
/* just reports a crash */ /* just reports a crash */
static void signal_handler(int signo){ static void signal_handler(int signo){
if(signo==SIGPIPE) _exit(0); /* "ps | head" will cause this */ if(signo==SIGPIPE) _exit(0); /* "ps | head" will cause this */
@ -44,7 +46,7 @@ static void signal_handler(int signo){
"Please send bug reports to <procps@freelists.org>\n"), "Please send bug reports to <procps@freelists.org>\n"),
signo, signo,
signal_number_to_name(signo), signal_number_to_name(signo),
program_invocation_short_name, myname,
procps_version procps_version
); );
_exit(signo+128); _exit(signo+128);
@ -523,6 +525,9 @@ static void fancy_spew(void){
/***** no comment */ /***** no comment */
int main(int argc, char *argv[]){ int main(int argc, char *argv[]){
myname = strrchr(*argv, '/');
if (myname) ++myname; else myname = *argv;
setlocale (LC_ALL, ""); setlocale (LC_ALL, "");
bindtextdomain(PACKAGE, LOCALEDIR); bindtextdomain(PACKAGE, LOCALEDIR);
textdomain(PACKAGE); textdomain(PACKAGE);

View File

@ -81,7 +81,7 @@ unsigned thread_flags = 0xffffffff;
int unix_f_option = -1; int unix_f_option = -1;
int user_is_number = -1; int user_is_number = -1;
int wchan_is_number = -1; int wchan_is_number = -1;
const char *the_word_help;
static void reset_selection_list(void){ static void reset_selection_list(void){
selection_node *old; selection_node *old;
@ -391,6 +391,14 @@ void reset_global(void){
unix_f_option = 0; unix_f_option = 0;
user_is_number = 0; user_is_number = 0;
wchan_is_number = 0; wchan_is_number = 0;
/* Translation Note:
. The following translatable word will be used to recognize the
. user's request for help text. In other words, the translation
. you provide will alter program behavior.
.
. It must be limited to 15 characters or less.
*/
the_word_help = _("help");
} }
static const char archdefs[] = static const char archdefs[] =

231
ps/help.c
View File

@ -12,101 +12,196 @@
#include <errno.h> #include <errno.h>
#include <stdio.h> #include <stdio.h>
#include <stdlib.h> #include <stdlib.h>
#include <string.h>
#include "common.h" #include "common.h"
void usage(FILE * out, int section) NORETURN;
void usage(FILE * out, int section){ enum {
fputs(USAGE_HEADER, out); HELP_SMP, HELP_LST, HELP_OUT,
fprintf(out, HELP_THD, HELP_MSC, HELP_ALL,
_(" %s [options]\n"), program_invocation_short_name); HELP_default
if (section == USAGE_SELECTION || section == USAGE_ALL) { };
fputs(_("\nSimple options:\n"
" -A all processes\n" static struct {
" -N, --deselect negate selection\n" const char *word;
" -a all without tty and session leader\n" const char *abrv;
" -d all except session leader\n" } help_tab[HELP_default];
" -e all processes\n"
" T all processes on this terminal\n"
" a all without tty, including other users\n" static int parse_help_opt (const char *opt) {
" g obsolete, do not use\n" /* Translation Notes for ps Help #1 ---------------------------------
" r only running processes\n" . This next group of lines represents 6 pairs of words + abbreviations
" x processes without controlling ttys\n"), out); . which are the basis of the 'ps' program help text.
.
. The words and abbreviations you provide will alter program behavior.
. They will also appear in the help usage summary associated with the
. "Notes for ps Help #2" below.
.
. In their English form, help text would look like this:
. Try 'ps --help <simple|list|output|threads|misc|all>'
. or 'ps --help <s|l|o|t|m|a>'
. for additional help text.
.
. When translating these 6 pairs you may choose any appropriate
. language equivalents and the only requirement is the abbreviated
. representations must be unique.
.
. By default, those abbreviations are single characters. However,
. they are not limited to only one character after translation.
. */
/* Translation Hint, Pair #1 */
help_tab[HELP_SMP].word = _("simple"); help_tab[HELP_SMP].abrv = _("s");
/* Translation Hint, Pair #2 */
help_tab[HELP_LST].word = _("list"); help_tab[HELP_LST].abrv = _("l");
/* Translation Hint, Pair #3 */
help_tab[HELP_OUT].word = _("output"); help_tab[HELP_OUT].abrv = _("o");
/* Translation Hint, Pair #4 */
help_tab[HELP_THD].word = _("threads"); help_tab[HELP_THD].abrv = _("t");
/* Translation Hint, Pair #5 */
help_tab[HELP_MSC].word = _("misc"); help_tab[HELP_MSC].abrv = _("m");
/* Translation Hint, Pair #6 */
help_tab[HELP_ALL].word = _("all"); help_tab[HELP_ALL].abrv = _("a");
/*
* the above are doubled on each line so they carry the same .pot
* line # reference and thus appear more like true "pairs" even
* though xgettext will produce separate msgid/msgstr groups */
if(opt) {
int i;
for (i = HELP_SMP; i < HELP_default; i++)
if (!strcmp(opt, help_tab[i].word) || !strcmp(opt, help_tab[i].abrv))
return i;
} }
if (section == USAGE_LIST || section == USAGE_ALL) { return HELP_default;
fputs(_("\nSelection by list:\n" }
void do_help (const char *opt, int rc) NORETURN;
void do_help (const char *opt, int rc) {
FILE *out = (rc == EXIT_SUCCESS) ? stdout : stderr;
int section = parse_help_opt(opt);
fprintf(out, _("\n"
"Usage:\n"
" %s [options]\n"), myname);
if (section == HELP_SMP || section == HELP_ALL) {
fprintf(out, _("\n"
"Basic options:\n"
" -A, -e all processes\n"
" -a all with tty, except session leaders\n"
" a all with tty, including other users\n"
" -d all except session leaders\n"
" -N, --deselect negate selection\n"
" r only running processes\n"
" T all processes on this terminal\n"
" x processes without controlling ttys\n"));
}
if (section == HELP_LST || section == HELP_ALL) {
fprintf(out, _("\n"
"Selection by list:\n"
" -C <command> command name\n" " -C <command> command name\n"
" U, -u, --user <uid> effective user id or name\n"
" -U, --User <uid> real user id or name\n"
" -G, --Group <gid> real group id or name\n" " -G, --Group <gid> real group id or name\n"
" -g, --group <group> session or effective group name\n" " -g, --group <group> session or effective group name\n"
" -p, --pid <pid> process id\n" " -p, --pid <pid> process id\n"
" --ppid <pid> select by parent process id\n" " --ppid <pid> select by parent process id\n"
" -s, --sid <session> session id\n" " -s, --sid <session> session id\n"
" t, -t, --tty <tty> terminal\n" " -t, t, --tty <tty> terminal\n"
"\n selection <arguments> take csv list e.g. `-u root,nobody'\n"), out); " -u, U, --user <uid> effective user id or name\n"
" -U, --User <uid> real user id or name\n"
"\n"
" selection <arguments> take either:\n"
" comma-separated list e.g. '-u root,nobody' or\n"
" blank-separated list e.g. '-p 123 4567'\n"));
} }
if (section == USAGE_OUTPUT || section == USAGE_ALL) { if (section == HELP_OUT || section == HELP_ALL) {
fputs(_("\nOutput formats:\n" fprintf(out, _("\n"
" o, -o, --format <format>" "Output formats:\n"
" user defined format\n" " -F extra full\n"
" O <format> preloaded -o allowing sorting\n" " -f full-format, including command lines\n"
" -O <format> preloaded, with default columns, allowing sorting\n" " f, --forest ascii art process tree\n"
" -H show process hierarchy\n"
" -j jobs format\n" " -j jobs format\n"
" j BSD job control format\n" " j BSD job control format\n"
" -l long format\n" " -l long format\n"
" l BSD long format\n" " l BSD long format\n"
" y do not show flags, show rrs in place addr (used with -l)\n" " -M, Z add security data (for SE Linux)\n"
" -f full-format\n" " -O <format> preloaded with default columns\n"
" -F extra full\n" " O <format> as -O, with BSD personality\n"
" -o, o, --format <format>\n"
" user defined format\n"
" s signal format\n" " s signal format\n"
" v virtual memory\n"
" u user-oriented format\n" " u user-oriented format\n"
" v virtual memory format\n"
" X register format\n" " X register format\n"
" Z, -M security data (for SE Linux)\n" " -y do not show flags, show rrs vs. addr (used with -l)\n"
" f, --forest ascii art process tree\n"
" -H show process hierarchy\n"
" --context display security context (for SE Linux)\n" " --context display security context (for SE Linux)\n"
" --heading repeat header lines\n" " --headers repeat header lines, one per page\n"
" --no-headers do not print header at all\n" " --no-headers do not print header at all\n"
" --cols <num> set screen width\n" " --cols, --columns, --width <num>\n"
" --rows <num> set screen height\n"), out); " set screen width\n"
" --rows, --lines <num>\n"
" set screen height\n"));
} }
if (section == USAGE_THREADS || section == USAGE_ALL) { if (section == HELP_THD || section == HELP_ALL) {
fputs(_("\nShow threads:\n" fprintf(out, _("\n"
"Show threads:\n"
" H as if they where processes\n" " H as if they where processes\n"
" -L possibly with LWP and NLWP columns\n" " -L possibly with LWP and NLWP columns\n"
" -T possibly with SPID column\n" " -m, m after processes\n"
" m, -m after processes\n"), out); " -T possibly with SPID column\n"));
} }
if (section == USAGE_MISC || section == USAGE_ALL) { if (section == HELP_MSC || section == HELP_ALL) {
fputs(_("\nMisc options:\n" fprintf(out, _("\n"
" w, -w unlimited output width\n" "Miscellaneous options:\n"
" L list format codes\n" " -c show scheduling class with -l option\n"
" c true command name\n" " c show true command name\n"
" e show the environment after command\n"
" k, --sort specify sort order as: [+|-]key[,[+|-]key[,...]]\n"
" L list format specifiers\n"
" n display numeric uid and wchan\n" " n display numeric uid and wchan\n"
" -y do not show flags, show rss (only with -l)\n"
" -c show scheduling class\n"
" --sort <spec> specify sort order, can be a csv list\n"
" S, --cumulative include some dead child process data\n" " S, --cumulative include some dead child process data\n"
" --info print debuggin information\n" " -y do not show flags, show rss (only with -l)\n"
" V,-V, --version display version information and exit\n" " -V, V, --version display version information and exit\n"
" --help <selection|list|output|threads|misc|all>\n" " -w, w unlimited output width\n"
" display help\n"), out); "\n"
" --%s <%s|%s|%s|%s|%s|%s>\n"
" display help and exit\n")
, the_word_help
, help_tab[HELP_SMP].word, help_tab[HELP_LST].word
, help_tab[HELP_OUT].word, help_tab[HELP_THD].word
, help_tab[HELP_MSC].word, help_tab[HELP_ALL].word);
} }
if (section == USAGE_DEFAULT) if (section == HELP_default) {
/* Translation Notes for ps Help #2 ---------------------------------
/* Translation Hint: do not translate arguments, that breaks . Most of the following c-format string is derived from the 6
* string comparison. Outputting something like following . pairs of words + chars mentioned above in "Notes for ps Help #1".
* might work. .
* . In its full English form, help text would look like this:
* Zry `%s --help <selection|list|output|threads|misc|all> . Try 'ps --help <simple|list|output|threads|misc|all>'
* (zlekzio|lizt|czreen vrites|threadz|mizc|trezt) . or 'ps --help <s|l|o|t|m|a>'
*/ . for additional help text.
fprintf(out, _("\n Try `%s --help <selection|list|output|threads|misc|all>'\n" .
" for more information.\n"), program_invocation_short_name); . The word for "help" will be translated elsewhere. Thus, the only
fprintf(out, USAGE_MAN_TAIL("ps(1)")); . translations below will be: "Try", "or" and "for additional...".
exit(out == stderr ? EXIT_FAILURE : EXIT_SUCCESS); . */
fprintf(out, _("\n"
" Try '%s --%s <%s|%s|%s|%s|%s|%s>'\n"
" or '%s --%s <%s|%s|%s|%s|%s|%s>'\n"
" for additional help text.\n")
, myname, the_word_help
, help_tab[HELP_SMP].word, help_tab[HELP_LST].word
, help_tab[HELP_OUT].word, help_tab[HELP_THD].word
, help_tab[HELP_MSC].word, help_tab[HELP_ALL].word
, myname, the_word_help
, help_tab[HELP_SMP].abrv, help_tab[HELP_LST].abrv
, help_tab[HELP_OUT].abrv, help_tab[HELP_THD].abrv
, help_tab[HELP_MSC].abrv, help_tab[HELP_ALL].abrv);
}
fprintf(out, _("\nFor more details see ps(1).\n"));
exit(rc);
} }
/* Missing: /* Missing:

View File

@ -153,22 +153,6 @@ found_it:
return 0; return 0;
} }
static int parse_usage_section(const char *opt){
if (!strcmp(opt, "s") || !strcmp(opt, "selection"))
return USAGE_SELECTION;
if (!strcmp(opt, "l") || !strcmp(opt, "list"))
return USAGE_LIST;
if (!strcmp(opt, "o") || !strcmp(opt, "output"))
return USAGE_OUTPUT;
if (!strcmp(opt, "t") || !strcmp(opt, "threads"))
return USAGE_THREADS;
if (!strcmp(opt, "m") || !strcmp(opt, "misc"))
return USAGE_MISC;
if (!strcmp(opt, "a") || !strcmp(opt, "all"))
return USAGE_ALL;
return USAGE_DEFAULT;
}
/* /*
* Used to parse lists in a generic way. (function pointers) * Used to parse lists in a generic way. (function pointers)
*/ */
@ -793,7 +777,6 @@ static const char *parse_gnu_option(void){
char buf[16]; char buf[16];
gnu_table_struct findme = { buf, NULL}; gnu_table_struct findme = { buf, NULL};
gnu_table_struct *found; gnu_table_struct *found;
int usage_section;
static const gnu_table_struct gnu_table[] = { static const gnu_table_struct gnu_table[] = {
{"Group", &&case_Group}, /* rgid */ {"Group", &&case_Group}, /* rgid */
{"User", &&case_User}, /* ruid */ {"User", &&case_User}, /* ruid */
@ -809,7 +792,7 @@ static const char *parse_gnu_option(void){
{"headers", &&case_headers}, {"headers", &&case_headers},
{"heading", &&case_heading}, {"heading", &&case_heading},
{"headings", &&case_headings}, {"headings", &&case_headings},
{"help", &&case_help}, //{"help", &&case_help}, /* now TRANSLATABLE ! */
{"info", &&case_info}, {"info", &&case_info},
{"lines", &&case_lines}, {"lines", &&case_lines},
{"no-header", &&case_no_header}, {"no-header", &&case_no_header},
@ -843,7 +826,11 @@ static const char *parse_gnu_option(void){
sizeof(gnu_table_struct), compare_gnu_table_structs sizeof(gnu_table_struct), compare_gnu_table_structs
); );
if(!found) return _("Unknown gnu long option."); if(!found) {
if (!strcmp(buf, the_word_help))
goto case_help;
return _("Unknown gnu long option.");
}
goto *(found->jump); /* See gcc extension info. :-) */ goto *(found->jump); /* See gcc extension info. :-) */
@ -932,11 +919,7 @@ static const char *parse_gnu_option(void){
case_help: case_help:
trace("--help\n"); trace("--help\n");
arg = grab_gnu_arg(); arg = grab_gnu_arg();
if(!arg) do_help(arg, EXIT_SUCCESS);
usage_section = USAGE_DEFAULT;
else
usage_section = parse_usage_section(arg);
usage(stdout, usage_section);
case_info: case_info:
trace("--info\n"); trace("--info\n");
exclusive("--info"); exclusive("--info");
@ -1266,5 +1249,5 @@ total_failure:
reset_parser(); reset_parser();
if(personality & PER_FORCE_BSD) fprintf(stderr, _("ERROR: %s\n"), err2); if(personality & PER_FORCE_BSD) fprintf(stderr, _("ERROR: %s\n"), err2);
else fprintf(stderr, _("ERROR: %s\n"), err); else fprintf(stderr, _("ERROR: %s\n"), err);
usage(stderr, USAGE_DEFAULT); do_help(NULL, EXIT_FAILURE);
} }