# HG changeset patch
# User Mychaela Falconia <falcon@freecalypso.org>
# Date 1613363889 0
# Node ID 8dee7aa9ec584437462dba60814037ad7e966a24
# Parent  d4058ae94749d1fc9b11df0c308142dd719ca36c
doc/User-oriented-commands: phonebook commands documented

diff -r d4058ae94749 -r 8dee7aa9ec58 doc/User-oriented-commands
--- a/doc/User-oriented-commands	Mon Feb 15 02:01:01 2021 +0000
+++ b/doc/User-oriented-commands	Mon Feb 15 04:38:09 2021 +0000
@@ -210,7 +210,78 @@
 
 fc-simtool provides a unified set of commands and data formats for working with
 all SIM phonebooks: all pb-* commands take the name of the phonebook to be
-operated on as their first argument.
+operated on as their first argument.  The following commands are available:
+
+pb-dump PBNAME
+
+This command dumps the full content of the selected phonebook on the terminal.
+The data format for representing SIM phonebook content in UNIX-based text files
+and dumps is described in the SIM-data-formats document in the freecalypso-docs
+repository.
+
+pb-dump PBNAME outfile
+
+This form of the pb-dump command dumps the full content of the selected
+phonebook, but saves it in the named file instead of sending it to the terminal.
+This form is ideal for making backups of large SIM phonebooks.
+
+pb-dump-rec PBNAME rec
+
+This command dumps a single record from a potentially large phonebook.
+
+pb-dump-rec PBNAME start-rec end-rec
+
+This command dumps the specified range of records from a potentially large
+phonebook.
+
+pb-update PBNAME filename
+
+This command reads a phonebook data file in the format described in the
+SIM-data-formats document and uploads it into the named SIM phonebook, writing
+each record from the data file into the SIM with an UPDATE RECORD command.
+
+Please note that this command does NOT include a built-in erase of those SIM
+phonebook record positions which are not covered by the data file being uploaded
+- any non-blank records in those positions will retain their previous content.
+
+pb-update-imm PBNAME rec phone-number [alpha-tag]
+
+This command writes a single phonebook entry directly from the command line,
+without going through a data file.  The specific record index to write into must
+always be specified (there is no built-in "find first empty record" function),
+and the entry format for both the phone number and the alpha tag is more relaxed
+compared to the very strict format required in data files:
+
+* The phone number can begin with a '+' character for international format;
+
+* The comma-separated TON/NPI byte is optional and will usually be omitted in
+  ordinary usage - this byte will default to 0x91 if the number begins with '+'
+  or to 0x81 otherwise;
+
+* Double-quotes around the alpha tag argument are required only if it contains
+  spaces or other problematic characters, and can be omitted otherwise;
+
+* If the alpha tag is empty, the last argument can be omitted altogether.
+
+pb-update-imm-hex PBNAME rec phone-number alpha-tag-hex
+
+This command is like pb-update-imm, but the alpha tag argument (required for
+this command) is given in hex - intended for creating phonebook entries with
+UCS-2 alpha tags.
+
+pb-erase PBNAME
+
+This command fully erases the named phonebook.
+
+pb-erase-one PBNAME rec
+
+This command erases the specified individual record in the named phonebook.
+
+pb-erase-range PBNAME start-rec end-rec
+
+This command erases the specified range of records in the named phonebook.  The
+starting record must be identified by number (SIM record numbers are 1-based);
+the ending record argument may be either as a number or the "end" keyword.
 
 Last Number Dialed (LND)
 ========================