Add documentation from the old sites page

Author: dparrish

README README.mdREADME renamed to README.md

@@ -1,112 +1,111 @@
-libcli
+Libcli provides a shared C library for including a Cisco-like command-line
+interface into other software.
 
-libcli emulates a cisco style telnet command-line interface.
+It’s a telnet interface which supports command-line editing, history,
+authentication and callbacks for a user-definable function tree.
 
 To compile:
 
-	make
-	make install
+```sh
+$ make
+$ make install
+```
 
-This will install libcli.so into /usr/local/lib. If you want to change
-the location, edit Makefile.
+This will install `libcli.so` into `/usr/local/lib`. If you want to change the
+location, edit Makefile.
 
-There is a test application built called clitest. Run this and telnet
-to port 8000.
+There is a test application built called clitest. Run this and telnet to port
+8000.
 
 By default, a single username and password combination is enabled.
 
+```
 Username: fred
 Password: nerk
+```
 
-Get help by entering "help" or hitting ?.
+Get help by entering `help` or hitting `?`.
 
 libcli provides support for using the arrow keys for command-line editing. Up
 and Down arrows will cycle through the command history, and Left & Right can be
 used for editing the current command line.
+
 libcli also works out the shortest way of entering a command, so if you have a
-command "show users grep foobar" defined, you can enter "sh us g foobar" if that
+command `show users | grep foobar` defined, you can enter `sh us | g foobar` if that
 is the shortest possible way of doing it.
 
-Enter "sh?" at the command line to get a list of commands starting with "sh"
+Enter `sh?` at the command line to get a list of commands starting with `sh`
 
 A few commands are defined in every libcli program:
-help
-quit
-exit
-logout
-history
-
-
 
+* `help`
+* `quit`
+* `exit`
+* `logout`
+* `history`
 
 Use in your own code:
 
-First of all, make sure you #include <libcli.h> in your C code, and link
-with -lcli.
+First of all, make sure you `#include <libcli.h>` in your C code, and link with
+`-lcli`.
 
 If you have any trouble with this, have a look at clitest.c for a
 demonstration.
 
-Start your program off with a cli_init().
+Start your program off with a `cli_init()`.
 This sets up the internal data structures required.
 
 When a user connects, they are presented with a greeting if one is set using the
-cli_set_banner(banner) function.
-
+`cli_set_banner(banner)` function.
 
 By default, the command-line session is not authenticated, which means users
 will get full access as soon as they connect. As this may not be always the best
 thing, 2 methods of authentication are available.
 
 First, you can add username / password combinations with the
-cli_allow_user(username, password) function. When a user connects, they can
+`cli_allow_user(username, password)` function. When a user connects, they can
 connect with any of these username / password combinations.
 
-Secondly, you can add a callback using the cli_set_auth_callback(callback)
-function. This function is passed the username and password as char *, and must
-return CLI_OK if the user is to have access and CLI_ERROR if they are not.
+Secondly, you can add a callback using the `cli_set_auth_callback(callback)`
+function. This function is passed the username and password as `char *`, and must
+return `CLI_OK` if the user is to have access and `CLI_ERROR` if they are not.
 
 The library itself will take care of prompting the user for credentials.
 
-
-
-
 Commands are built using a tree-like structure. You define commands with the
-cli_register_command(parent, command, callback, privilege, mode, help) function.
+`cli_register_command(parent, command, callback, privilege, mode, help)` function.
 
-parent is a cli_command * reference to a previously added command. Using a
+`parent` is a `cli_command *` reference to a previously added command. Using a
 parent you can build up complex commands.
-e.g. to provide commands "show users", "show sessions" and "show people", use
+
+e.g. to provide commands `show users`, `show sessions` and `show people`, use
 the following sequence:
 
+```c
 cli_command *c = cli_register_command(NULL, "show", NULL, PRIVILEGE_UNPRIVILEGED, MODE_EXEC, NULL);
 cli_register_command(c, "sessions", fn_sessions, PRIVILEGE_UNPRIVILEGED, MODE_EXEC, "Show the sessions connected");
 cli_register_command(c, "users", fn_users, PRIVILEGE_UNPRIVILEGED, MODE_EXEC, "Show the users connected");
 cli_register_command(c, "people", fn_people, PRIVILEGE_UNPRIVILEGED, MODE_EXEC, "Show a list of the people I like");
+```
 
-
-If callback is NULL, the command can be used as part of a tree, but cannot be
+If callback is `NULL`, the command can be used as part of a tree, but cannot be
 individually run. 
 
-
 If you decide later that you don't want a command to be run, you can call
-cli_unregister_command(command).
+`cli_unregister_command(command)`.
 You can use this to build dynamic command trees.
 
-
 It is possible to carry along a user-defined context to all command callbacks
-using cli_set_context(cli, context) and cli_get_context(cli) functions.
+using `cli_set_context(cli, context)` and `cli_get_context(cli)` functions.
 
 
 You are responsible for accepting a TCP connection, and for creating a
 process or thread to run the cli.  Once you are ready to process the
-connection, call cli_loop(cli, sock) to interact with the user on the
+connection, call `cli_loop(cli, sock)` to interact with the user on the
 given socket.
 
 This function will return when the user exits the cli, either by breaking the
-connection or entering "quit".
-
-Call cli_done() to free the data structures.
+connection or entering `quit`.
 
+Call `cli_done()` to free the data structures.
 
-- David Parrish (david@dparrish.com)

clitest.c

@@ -260,7 +260,7 @@ int shape_transient_eval(struct cli_def *cli, const char *name, const char *valu
     return CLI_OK;
   }
   cli_error(cli, "unrecognized value for setting %s -> %s", name, value);
-  return  CLI_ERROR;
+  return CLI_ERROR;
 }
 
 const char *KnownColors[] = {"black",    "white",    "gray",      "red",        "blue",
@@ -319,12 +319,12 @@ void run_child(int x) {
   cli_set_hostname(cli, "router");
   cli_telnet_protocol(cli, 1);
   cli_regular(cli, regular_callback);
-  
+
   // change regular update to 5 seconds rather than default of 1 second
   cli_regular_interval(cli, 5);
-  
+
   // set 60 second idle timeout
-  cli_set_idle_timeout_callback(cli, 60, idle_timeout); 
+  cli_set_idle_timeout_callback(cli, 60, idle_timeout);
   cli_register_command(cli, NULL, "test", cmd_test, PRIVILEGE_UNPRIVILEGED, MODE_EXEC, NULL);
   cli_register_command(cli, NULL, "simple", NULL, PRIVILEGE_UNPRIVILEGED, MODE_EXEC, NULL);
   cli_register_command(cli, NULL, "simon", NULL, PRIVILEGE_UNPRIVILEGED, MODE_EXEC, NULL);