update man page

.gitignore

@@ -55,3 +55,6 @@ dist/
 
 # outputs
 slackdump_2*
+*.pdf
+*.ps
+*.html

slackdump.1

@@ -1,3 +1,5 @@
+
+.\" https://man.openbsd.org/mdoc.7
 .Dd $Mdocdate$
 .Dt SLACKDUMP 1
 .Os
@@ -14,72 +16,145 @@ The
 .Nm
 utility dumps Slack workspace contents.  Currently it supports the
 following Slack entities:
+.Bl -tag -compact -width messages -offset ident
+.It Em messages
+Includes all messages in all channels, direct, and group messages.
+.It Em replies
+Includes all message replies or, in other words — threads.
+.It Em files
+Files are dumped along with messages they belong to.
+.It Em emojis
+Emojis are dumped along with their index which contains their names and aliases
+as a JSON file.
+.It Em users
+Users include full profile information without custom fields.
+.It Em channels
+Channels, that are visible to the current authenticated user.  This includes:
 .Bl -dash -compact
 .It
-messages, which includes all messages in all channels, direct, and group messages.
-.It 
-message replies, or, in other words — threads.
-.It 
-files are dumped along with messages they belong to.
-.It 
-emojis, along with their index as a JSON file.
-.It 
-users, with their profile information.
-.It 
-and channels.
+current and archive public channels including those that this user is not a
+member of;
+.It
+private group conversations;
+.It
+direct messages (private conversations between two users).
+.El
 .El
 .Pp
 If no command is given, on a dumb terminal, the 
-.Ar help
-command is assumed.
-On an interactive terminal a list of options will be presented, allowing the
-user to enter an interactive mode, display help, or exit.
+.Cm help
+command is assumed.  On an interactive terminal a list of options will
+be presented, allowing the user to enter an interactive mode, display
+help, or exit.
 .Sh COMMANDS
 The following commands are supported (listed in alphabetical order):
 .Bl -tag -width workspace
-.It Ar config
-Allows to perform different operations on the API limits configuration files.
-.It Ar convert
+.It Cm config Ar subcommand
+Allows to perform different operations on the API limits configuration
+files.
+.It Cm convert
 Convert between formats.
-.It Ar dump
+.It Cm diag Ar subcommand
+Contains various diagnostic utilities.  Developers might ask to run
+these commands to help with debugging.
+.It Cm dump
 Dump selected channels or threads.
-.It Ar emoji
+.It Cm emoji
 Export Slack workspace emojis.
-.It Ar export
+.It Cm export
 Export workspace contents.
-.It Ar format
-Format the conversations, users, and channels as human readable files.  
+.It Cm format
+Format the conversations, users, and channels as human readable files.
 It supports TEXT and CSV formats.
-.It Ar help
-Display help.
-.It Ar list
+.It Cm help Ar command
+Display help.  To get the subcommand help, use the combination of
+.Cm main_command Cm help Ar subcommand
+For example, to get help on the
+.Ar new
+subcommand of the
+.Cm workspace
+command, run the following:
+.Bd -literal -offset indent
+.Nm Cm workspace Cm help Ar new
+.Ed
+.It Cm list
 List channels or users in the desired format
 .Pq default output is text
-.It Ar record
+.It Cm record
 Export workspace in the internal Chunk format.
-.It Ar version
+.It Cm version
 Display version information.
-.It Ar workspace
+.It Cm workspace
 Manage Slack workspaces authentication.
 .El
 .\"
 .Sh USAGE
-.Ss Authentication
+.Ss Quickstart
+The quickest way to get started is to run the following command:
+.Bl -enum -compact
+.It
+Authenticate in a new workspace using the
+.Cm workspace
+.Ar new
+command;
+.It
+Run
+.Cm dump
+,
+.Cm record
+or
+.Cm export
+, depending on your requirements.
+.El
+.Sh AUTHENTICATION
 Slackdump supports multiple authentication methods, listed below.
-.Bl -tag -width "token+cookie file"
-.It Em EZ-LOGIN 3000
-This is the default mode, and is the most convenient one.  It requires no
-additional configuration and works out of the box.  However, it is not
-supported on all systems.
-.It token
-This method requires Application or Bot token.
-.It token+cookie
-This is the pair of token and cookie that you can get from your browser manually
-following the instructions in the documentation.
-.It token+cookie file
+.Ss Automatic login (EZ-LOGIN 3000)
+This is the default authentication mode, and so far is the most convenient one.
+It requires no additional configuration and works out of the box.  However, it
+is not supported on all systems:  it requires GUI and x64 architecture, and may
+require some additional steps on CentOS and other Redhat derived systems.
+
+If the automatic login does not work for some reason, you can try to use one of
+the manual login methods, described in the next section.
+
+This method works on Single-Sign-On enabled workspaces as well in most cases.
+.Ss Manual login methods
+.Bl -tag -width token+cookie
+.It Em token
+This method requires Application
+.Pq xoxa-
+, Bot
+.Pq xoxb-
+or a Legacy
+.Pq xoxp-
+token. You can get these tokens (except Legacy) from the Slack
+Workspace Administration page.  See the
+.Lk https://api.slack.com/authentication/token-types "Slack documentation"
+for more details.
+.Pp
+.Sy Note:
+You will not be able to access your DMs with the Application or Bot tokens, and
+Legacy tokens are deprecated.
+.It Em token+cookie
+This is the pair of the Client Token
+.Pq xoxc-
+and a 
+.Dq d=
+Browser Cookie
+.Pq xoxd=
+value that you can get from your browser manually following the instructions in
+the documentation.
+.It Em token+cookie file
 This is the same as above, but it requires the 
 .Dq cookie.txt
-file.
+file, exported from you Browser session in Mozilla format.  On Firefox, you could use
+.Lk https://addons.mozilla.org/en-US/firefox/addon/cookies-txt/ "Cookies.txt"
+extension.
+.Sy Note:
+Some browser extensions may be unsafe and may expose your private data, so use them at
+your own risk.  The authors of this utility do not endorse any of the
+extensions mentioned above.
+
 .El
 .\" 
 .Sh ENVIRONMENT
@@ -128,15 +203,39 @@ Contains path to a file where trace output will be written.
 .\" .Sh FILES
 .\" .Sh EXIT STATUS
 .\" For sections 1, 6, and 8 only.
-.\" .Sh EXAMPLES
+.Sh EXAMPLES
+Getting help on a specific command:
+.Bd -literal -offset indent
+.Nm Cm help Ar <command>
+.Ed
+.Pp
+Authenticate in a new workspace
+.Lk https://myworkspace.slack.com
+:
+.Bd -literal -offset indent
+.Nm Cm workspace Cm new Ar myworkspace
+.Ed
+.Pp
+Run full workspace export:
+.Bd -literal -offset indent
+.Nm Cm export
+.Ed
+.Pp
+Run full workspace export with debug output:
+.Bd -offset indent
+DEBUG=1 
+.Nm Cm export
+.Ed
 .\" .Sh DIAGNOSTICS
 .\" For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only.
 .\" .Sh ERRORS
 .\" For sections 2, 3, 4, and 9 errno settings only.
 .\" .Sh SEE ALSO
 .\" .Xr foobar 1
 .\" .Sh STANDARDS
-.\" .Sh HISTORY
+.Sh HISTORY
+Slackdump was created as a tool to dump private messages from Slack in 2018, and
+was released as an GPL-3 Open Source application to public in October 2021.
 .Sh AUTHORS
 The
 .Nm