[Freeciv-Dev] patches: improve server 'help', and related (PR#224)

[David Pfitzner <dwp@xxxxxxxxxxxxxx>]

This is a big post, containing 4 patches mostly affecting
server/stdinhand.c, included together because there are 
intended to be applied in sequence (although the level of 
dependence varies).  The main aim is achieved by the fourth 
patch, which changes the server 'help' command.

use_my_prefix.diff:
    Simple patch to use match_prefix() instead of "by hand" code 
in command_named() and lookup_option().  Also, in show_command(), 
for an ambiguous option prefix show all matches.  Modifies 
match_prefix() so max_len_name==0 means no max.

cmd_reply_multi.diff:
    Enhance cmd_reply() to handle multiple lines, and add 
cmd_reply_prefix() which adds a prefix to lines after the first.
(Also const-qualifies some args of notify_player() etc.)

aformat_ophelp.diff:
    Use cmd_reply_prefix() to simplify some code in explain_option(),
and do auto-linewrap and auto-indent of description.  This means 
extra_help needs less manual formatting - adjusted.  Sorry, this 
also means translations will need minor (formatting) adjustments 
for option help strings, but I think the added flexibility is worth 
it.  (Also fix slightly out-of-date help for spacerace option.)

new_server_help.diff:

This patch substantially revises and improves the server 'help' 
command, to allow more detailed and flexible help on server 
commands, and to fold the functionality of 'explain' into help.

Existing behaviour:
  'help' - list of server commands, one or few lines each
  'explain' - list of options, or individual option detail

With this patch:
  'help' - introductory help
  'help options' - list of options
  'help commands' - list of commands
  'help <name>' - detail of individual option or command

Also fixed a hole that clients could obtain values of options
they shouldn't have (eg, rand seeds) via 'show' and 'explain';
now use new function may_view_option().

I left in 'explain' for backward compatibility.

Lists of commands and options supplied to clients are now
restricted to those the client may be interested in, but 
detailed help is still available on other if the client
knows what to ask for.  (Ie, leave out as convienence -- 
improve signal-to-noise.)

Other minor changes: 
- add a farewell message to quit_game(), and change exit result to 0.
- in 'show', move string values from (min,max) column to value column.
- add some const and static qualifiers.

One possible complaint is that there is now a terse listing of
command names, and detail of individual names, but no brief 
overview of commands including short help (cf 'show' for options,
or current help, except would be less than current since can
leave details to individual help).  This would be easy to add, 
but I'm not sure what the command to access this should be
(ie, the user interface).

Further improvements which could be made:
 - Displayed lists should probably be sorted alphabetically
   (eg, pre-sort some lists of pointers).
 - When a prefix is ambiguous, should display possible matches.
 - For commands from client, a prefix may be ambiguous wrt 
   commands/options which are not normally available to the client,
   which could be confusing.  Display of ambiguous matches as 
   above would help.
 - The dispatcher in handle_stdin_input could be changed to use 
   function pointers stored in commands[].
 - It might be good to have a system for command and option _aliases_.
   This would allow changing command and option names where they
   are currently unclear, while maintaining backward compatability.
 - I didn't bother writing detailed help for all commands;
   improved or expanded help entries are of course welcome.

-- David

use_my_prefix.diff.gz
Description: GNU Zip compressed data

cmd_reply_multi.diff.gz
Description: GNU Zip compressed data

aformat_ophelp.diff.gz
Description: GNU Zip compressed data

new_server_help.diff.gz
Description: GNU Zip compressed data