pericmd 014: description, alt.lang

Let’s see what else we can put in Rinci metadata.

description

summary is what we use for short (one-line, max +-70 character) description that will show up as the abstract in help message or POD alongside the program name. For longer description (one to several paragraphs), we’ll use the appropriately named description property.

$SPEC{hello} = {
    v => 1.1,
    summary => 'Say hello',
    description => <<'_',

Say hello in English.

If you give an option `--salutation`, it will actually salute with the
salutation. There is also some shortcut options like `-m` (short for male) which
is equivalent to `--salutation Mr` and `-f` (short for female) which is
equivalent to `--salutation Mrs`.

_
};

For longer text, we usually want markup. The (default) markup defined for description is Markdown. I haven’t more specifically specify which flavor of Markdown it should be in, probably CommonMark. Why not POD? you ask. Because Markdown is slightly nicer (especially for bullet points) and more popular and “language-neutral” (meaning it’s much more well-known outside the Perl world compared to POD). Rinci is intended to be used across languages, after all.

The description is used also in CLI help message as well as in POD. Under CLI help message, it will just be spewed as-is:

% ./hello --help
hello - Say hello

Usage:
  hello --help (or -h, -?)
  hello --version (or -v)
  hello [options]

Say hello in English.

If you give an option `--salutation`, it will actually salute with the
salutation. There is also some shortcut options like `-m` (short for male) which
is equivalent to `--salutation Mr` and `-f` (short for female) which is
equivalent to `--salutation Mrs`.

Options:
  --config-path=s     Set path to configuration file
  --config-profile=s  Set configuration profile to use
  --format=s          Choose output format, e.g. json, text
  --help, -h, -?      Display this help message
  --json              Set output format to json
  --naked-res         When outputing as JSON, strip result envelope
  --no-config         Do not use any configuration file
  --version, -v       

And in POD (please refer to the previous post pericmd 012), if you build the distribution you will get this POD (note that the Markdown markups will be converted to POD formatting):

=pod

=head1 SYNOPSIS

Usage:

 % hello [options]

=head1 DESCRIPTION

Say hello in English.

If you give an option C<--salutation>, it will actually salute with the
salutation. There is also some shortcut options like C<-m> (short for male) which
is equivalent to C<--salutation Mr> and C<-f> (short for female) which is
equivalent to C<--salutation Mrs>.

=head1 OPTIONS

C<*> marks required options.

...

alt.lang

Rinci allows you to specify alternate languages (translations) for summary and description (basically any kind of text properties). You do this by appending “alt.lang.LANGCODE” after the property name. For example:

$SPEC{hello} = {
    v => 1.1,
    summary => 'Say hello',
    "summary.alt.lang.id_ID" => 'Katakan halo',
};

Perinci::CmdLine will detect locale and display the appropriate language.

% PERINCI_CMDLINE_ANY=classic LANG=id_ID.UTF-8 ./hello --help
hello - Katakan halo                                                           
Cara pakai                                                                     
  hello --help (atau -h, -?)                                                     
  hello --version (atau -v)                                                    
  hello [opsi]                                                                 
Opsi                                                                           
  --config-path=s                       --config-profile=s                     
  --debug                               --format-options=s                     
  --format=s                            --help, -h, -?                         
  --json                                --log-level=s                          
  --no-config                           --quiet                                
  --trace                               --verbose                              
  --version, -v                                                                
Untuk bantuan lebih lengkap, gunakan '--help --verbose'.     

For now, to see help message in language other than English, you need to add PERINCI_CMDLINE_ANY=classic because Perinci::CmdLine::Lite doesn’t support translation yet, only Perinci::CmdLine::Classic does, so the environment variable is used to select the Classic backend. You’ll also notice that the Classic backend produces somewhat nicer and more colorful help message, because the focus of the Classic backend is indeed on prettiness (unlike the default Lite backend, which focuses on low startup overhead).

What if user’s locale is one that we don’t have translation for:

% PERINCI_CMDLINE_ANY=classic LANG=fr_FR.UTF-8 ./hello --help
hello - {en_US Say hello}                                                      
Utilisation                                                                    
  hello --help (ou -h, -?)                                                     
  hello --version (ou -v)                                                      
  hello [options]                                                              
Options                                                                        
  --config-path=s                       --config-profile=s                     
  --debug                               --format-options=s                     
  --format=s                            --help, -h, -?                         
  --json                                --log-level=s                          
  --no-config                           --quiet                                
  --trace                               --verbose                              
  --version, -v                                                                
Pour de l'aide plus complète, utilisez '--help --verbose'.                     

You’ll see that the text is surrounded by {en_US …} to mark that the text is in English instead of the requested language.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s