Improve man pages formatting (lists, italics, etc)

4 files changed, 138 insertions, 45 deletions

diff --git a/doc/README b/doc/README
new file mode 100644
index 0000000..aa3c99a
--- /dev/null
+++ b/doc/README
@@ -0,0 +1 @@
+Run 'make doc' from the root directory to generate man pages in doc/man1.
\ No newline at end of file
diff --git a/tgrecv b/tgrecv
index 2d80493..a98820f 100755
--- a/tgrecv
+++ b/tgrecv
@@ -67,7 +67,6 @@ $cache->offset($updates->[-1]{'update_id'}+1) if ($AUTO_OFFSET && @$updates);
 print $out encode_json($updates);
 
 
-
 __END__
 
 =head1 NAME
@@ -76,28 +75,54 @@ tgrecv - Receive updates from Telegram, output them as JSON
 
 =head1 SYNOPSIS
 
-tgrecv [-h | --help] [-v]
+B<tgrecv> [B<-h> | B<--help>] [B<-v>]
 
-tgrecv [options]
+B<tgrecv> [I<options>]
 
 =head1 OPTIONS
 
-  --offset                Offset of the first message to receive - previous ones are
-                          discarded
-  --auto-offset           Use offset cache to automatically discard previous updates
-                          (if combined with --offset, cache the last update but
-                          still use the provided offset for the current request)
-  --timeout               Timeout for long polling (default: 60 seconds)
-  --output=file           Write the output to file instead of stdout
-  (--token | -t) <token>  Bot token (see AUTHENTICATION)
-  --version               Show version
-  --verbose | -v          Show more information (combine with -h to see full manual)
-  --help | -h             Show this message
+=over
+
+=item B<--offset>
+
+Offset of the first message to receive - previous ones are discarded
+
+=item B<--auto-offset>
+
+Use offset cache to automatically discard previous updates (if combined with
+B<--offset>, cache the last update but still use the provided offset for the
+current request)
+
+=item B<--timeout=>I<seconds>
+
+Timeout for long polling (default: 60 seconds)
+
+=item B<--output=>I<file>
+
+Write the output to I<file> instead of stdout
+
+=item B<--token>=I<token>, B<-t> I<token>
+
+Bot token (see B<AUTHENTICATION>)
+
+=item B<--version>
+
+Show version
+
+=item B<--verbose>, B<-v>
+
+Show more information (combine with B<-h> to see full manual)
+
+=item B<--help>, B<-h>
+
+Show this message
+
+=back
 
 =head1 DESCRIPTION
 
 This program receives a single update batch from the Telegram bot identified by
-B<token>, and outputs it as a JSON array. The array can contain multiple
+I<token>, and outputs it as a JSON array. The array can contain multiple
 updates. The connection is blocking (long polling), so it waits until an update
 is available before exiting.
 
@@ -105,9 +130,20 @@ is available before exiting.
 
 To get the bot token, this program will check (in order):
 
-  - The "--token" CLI argument
-  - The "TGUTILS_TOKEN" environment variable
-  - The contents of "$XDG_CONFIG_HOME/tgutils_token"
-    (usually ~/.config/tgutils_token)
+=over 2
+
+=item -
+
+The B<--token> CLI argument
+
+=item -
+
+The B<TGUTILS_TOKEN> environment variable
+
+=item -
+
+The contents of I<$XDG_CONFIG_HOME>B</tgutils_token> (usually B<~/.config/tgutils_token>)
+
+=back
 
 =cut
diff --git a/tgsend b/tgsend
index a757311..a889457 100755
--- a/tgsend
+++ b/tgsend
@@ -57,34 +57,63 @@ __END__
 
 =head1 NAME
 
-tgsend - Send message to a Telegram chat using a bot token
+tgsend - Send message to one or more Telegram chats
 
 =head1 SYNOPSIS
 
-tgsend [-h | --help] [-v]
+B<tgsend> [B<-h> | B<--help>] [B<-v>]
 
-tgsend [options] [chatid1 chatid2 ...]
+B<tgsend> [I<options>] I<chat_ids>...
 
 =head1 OPTIONS
 
-  --pretend | -p          Do not actually do anything
-  (--token | -t) <token>  Bot token (see AUTHENTICATION)
-  --version               Show version
-  --verbose | -v          Show more information (combine with -h to see full manual)
-  --help | -h             Show this message
+=over
+
+=item B<--pretend>, B<-p>
+
+Do not actually do anything
+
+=item B<--token>=I<token>, B<-t> I<token>
+
+Bot token (see B<AUTHENTICATION>)
+
+=item B<--version>
+
+Show version
+
+=item B<--verbose>, B<-v>
+
+Show more information (combine with B<-h> to see full manual)
+
+=item B<--help>, B<-h>
+
+Show this message
+
+=back
 
 =head1 DESCRIPTION
 
-This program sends its standard input to the Telegram chats whose IDs are passed
-as arguments, using the given bot token.
+This program will send its standard input to the given Telegram I<chat_ids>, from
+the bot identified by I<token>.
 
 =head1 AUTHENTICATION
 
 To get the bot token, this program will check (in order):
 
-  - The "--token" CLI argument
-  - The "TGUTILS_TOKEN" environment variable
-  - The contents of "$XDG_CONFIG_HOME/tgutils_token"
-    (usually ~/.config/tgutils_token)
+=over 2
+
+=item -
+
+The B<--token> CLI argument
+
+=item -
+
+The B<TGUTILS_TOKEN> environment variable
+
+=item -
+
+The contents of I<$XDG_CONFIG_HOME>B</tgutils_token> (usually B<~/.config/tgutils_token>)
+
+=back
 
 =cut
diff --git a/tgserver b/tgserver
index d1058bf..6d1f69d 100755
--- a/tgserver
+++ b/tgserver
@@ -66,6 +66,7 @@ while (1) {
     }
 }
 
+
 __END__
 
 =head1 NAME
@@ -74,30 +75,56 @@ tgserver - Interact with a Telegram Bot
 
 =head1 SYNOPSIS
 
-tgserver [-h | --help] [-v]
+B<tgserver> [B<-h> | B<--help>] [B<-v>]
 
-tgserver [options] -- B<prog>
+B<tgserver> [I<options>] -- I<prog>
 
 =head1 OPTIONS
 
-  (--token | -t) <token>  Bot token (see AUTHENTICATION)
-  --version               Show version
-  --verbose | -v          Show more information (combine with -h to see full manual)
-  --help | -h             Show this message
+=over
+
+=item B<--token>=I<token>, B<-t> I<token>
+
+Bot token (see B<AUTHENTICATION>)
+
+=item B<--version>
+
+Show version
+
+=item B<--verbose>, B<-v>
+
+Show more information (combine with B<-h> to see full manual)
+
+=item B<--help>, B<-h>
+
+Show this message
+
+=back
 
 =head1 DESCRIPTION
 
-This program waits for Telegram updates from the bot specified by the token. For
-every update it runs B<prog> with stdin piped to the update, and sending stdout
+This program waits for Telegram updates from the bot identified by I<token>. For
+every update it runs I<prog> with stdin piped to the update, and sending stdout
 back as response.
 
 =head1 AUTHENTICATION
 
 To get the bot token, this program will check (in order):
 
-  - The "--token" CLI argument
-  - The "TGUTILS_TOKEN" environment variable
-  - The contents of "$XDG_CONFIG_HOME/tgutils_token"
-    (usually ~/.config/tgutils_token)
+=over 2
+
+=item -
+
+The B<--token> CLI argument
+
+=item -
+
+The B<TGUTILS_TOKEN> environment variable
+
+=item -
+
+The contents of I<$XDG_CONFIG_HOME>B</tgutils_token> (usually B<~/.config/tgutils_token>)
+
+=back
 
 =cut