brush up docs

README.md

@@ -7,6 +7,7 @@ files and emojis.  Generate Slack Export without admin privileges.
 
 **Quick links**:
 
+- [Installation And Quickstart](#installation-and-quickstart)
 - [Join the discussion in Telegram](https://t.me/slackdump).
 - [Buy me a cup of tea](https://ko-fi.com/rusq_), or use **Github Sponsors**
   button on the top of the page.
@@ -32,24 +33,19 @@ Typical use scenarios:
 * create a Slack Export archive without admin access, or
 * save your favourite emojis.
 
-There are four modes of operation (more on this in [User Guide][ug]):
+There are several modes of operation
 
 1. List users/channels
 1. Dumping messages and threads
 1. Creating a Slack Export in Mattermost or Standard modes.
+1. Creating an Archive
 1. Emoji download mode.
+1. Viewing export, dump or archive files or directories (displays images).
+1. Search mode (messages and files).
 
-Slackdump accepts two types of input (see [Dumping
-Conversations][usage-channels] section):
+Run `slackdump help` to see all available options:
 
-1. the URL/link of the channel or thread, OR
-1. the ID of the channel.
-
-[ug]: doc/README.rst
-[usage-channels]: doc/usage-channels.rst
-
-Quick Start
-===========
+## Installation and Quickstart
 
 On macOS, you can install Slackdump with Homebrew::
 
@@ -64,12 +60,10 @@ On other Operating Systems, please follow these steps:
 1. Run the `./slackdump` or `slackdump.exe` executable (see note below).
 1. You know the drill:  use arrow keys to select the menu item, and Enter (or
    Return) to confirm.
+1. Follow these [qickstart instructions][man-quickstart].
 
 [releases]: https://github.com/rusq/slackdump/releases/
 
-By default, Slackdump uses the EZ-Login 3000 automatic login, and interactive
-mode.
-
 > [!NOTE] 
 > On Windows and macOS you may be presented with "Unknown developer" window,
 > this is fine.  Reason for this is that the executable hasn't been signed by
@@ -85,6 +79,18 @@ mode.
     "Unknown developer" window, then go to System Preferences -> Security and
     Privacy -> General, and press "Open Anyway" button.
 
+### Getting Help
+
+- Quickstart guide: `slackdump help quickstart`, read [online][man-quickstart].
+- Generic command overview: `man ./slackdump.1`
+- [Ez-Login 3000](https://github.com/rusq/slackdump/wiki/EZ-Login-3000) Guide.
+- V2 to V3 migration notes: `slackdump help v2migrate`, read [online][man-v2migrate].
+- What's new in V3: `slackdump help whatsnew`, read [online][man-changelog].
+
+[man-quickstart]: https://github.com/rusq/slackdump/blob/master/cmd/slackdump/internal/man/assets/quickstart.md
+[man-v2migrate]: https://github.com/rusq/slackdump/blob/master/cmd/slackdump/internal/man/assets/v2migr.md
+[man-changelog]: https://github.com/rusq/slackdump/blob/master/cmd/slackdump/internal/man/assets/changelog.md
+
 
 ## Slackord2: Migrating to Discord
 
@@ -94,7 +100,8 @@ nice GUI, that is compatible with the export files generated by Slackdump.
 
 ## User Guide
 
-For more advanced features and instructions, please see the [User Guide][ug].
+For more advanced features and instructions, please see the [User Guide][ug],
+and read `slackdump help` pages.
 
 # Previewing Results
 
@@ -183,15 +190,9 @@ No, you don't.  Just run the application and EZ-Login 3000 will take
 care of the authentication or, alternatively, grab that token and
 cookie from the browser Slack session.  See [User's Guide][ug].
 
-
-
 #### I'm getting "invalid_auth" error
 
-Go get the new Cookie from the browser and Token as well.
-
-#### Slackdump takes a very long time to cache users
-
-Disable the user cache with `-no-user-cache` flag.
+Run `slackdump workspace new <name or url>` to reauthenticate.
 
 #### How to read the export file?
 

cmd/slackdump/internal/format/format.go

@@ -14,6 +14,7 @@ import (
 	"runtime/trace"
 
 	"github.com/rusq/slack"
+
 	"github.com/rusq/slackdump/v3/cmd/slackdump/internal/bootstrap"
 
 	"github.com/rusq/slackdump/v3/cmd/slackdump/internal/cfg"
@@ -23,17 +24,27 @@ import (
 	"github.com/rusq/slackdump/v3/types"
 )
 
+// TODO this is hacky in the following ways:
+// 1. User must extract the JSON file from the archive
+// 2. What about exports etc.?
+// 3. Getting users online is hacky, as it requires authentication to be present,
+//    but if the user doesn't need online users.  The login should happen locally.
+
 var CmdFormat = &base.Command{
 	Run:       runFormat,
 	UsageLine: "slackdump format [flags] <format> <file.json>",
-	Short:     "converts the slackdump files to a human readable format",
+	Short:     "converts the slackdump dump files to a human readable format",
 	Long: `
 # Format Command
+
+Format command formats the json files generated by "slackdump dump" command to
+a human readable format.  The command takes the format type and the file to
+convert as arguments.
 `, // TODO: add more info
 	CustomFlags: false,
 	FlagMask:    cfg.OmitAll & ^cfg.OmitWorkspaceFlag,
 	PrintFlags:  true,
-	RequireAuth: false,
+	RequireAuth: true,
 }
 
 //go:generate stringer -type dumptype -trimprefix=dt
@@ -155,7 +166,7 @@ type dump struct {
 // member variables populated.  If it fails to detect the type it will return
 // ErrUnknown and set the dump filetype to dtUnknown.
 func detectAndRead(rs io.ReadSeeker) (*dump, error) {
-	var d = new(dump)
+	d := new(dump)
 
 	if conv, err := unmarshal[types.Conversation](rs); err != nil && !isJSONTypeErr(err) {
 		return nil, err
@@ -221,7 +232,7 @@ func unmarshal[OUT any](rs io.ReadSeeker) (OUT, error) {
 
 func getUsers(ctx context.Context, dmp *dump, isOnline bool) ([]slack.User, error) {
 	if isOnline {
-		return getUsersOnline(ctx, cfg.CacheDir(), cfg.Workspace, cfg.LegacyBrowser)
+		return getUsersOnline(ctx)
 	}
 	rgn := trace.StartRegion(ctx, "userIDs")
 	ids := dmp.userIDs()
@@ -237,7 +248,7 @@ func getUsers(ctx context.Context, dmp *dump, isOnline bool) ([]slack.User, erro
 	return uu, nil
 }
 
-func getUsersOnline(ctx context.Context, cacheDir, wsp string, usePlaywright bool) ([]slack.User, error) {
+func getUsersOnline(ctx context.Context) ([]slack.User, error) {
 	sess, err := bootstrap.SlackdumpSession(ctx)
 	if err != nil {
 		return nil, err
@@ -282,7 +293,7 @@ func matchUsers(r io.Reader, ids []string) ([]slack.User, error) {
 		return nil, err
 	}
 	fileIDs := uu.IndexByID()
-	var matchingCnt = 0 // matching users count
+	matchingCnt := 0 // matching users count
 	for _, id := range ids {
 		if fileIDs[id] != nil {
 			matchingCnt++

cmd/slackdump/internal/man/assets/changelog.md

@@ -1,10 +1,36 @@
-# v2.3.0
+# v3.0.0
+
+Gist:
+- 2.6x dump speed improvement on channels with threads;
+- Support for enteprise workspaces;
+- json logging on demand;
+- new structured CLI;
+- improved TUI for the wizardry with bells and whistles;
+- multiple workspaces with ability to switch between them without `-auth-reset`;
+- api limits configuration files;
+- uninstallation tool;
+- slackdump system information tool;
+- pgp encryption for traces (under tools);
+- search results archival;
+
+## New Archive format
+
+Consider using the new `archive` command to save your workspace data.  You can read about
+it in the `slackdump help archive` command and the format it produces in the
+`slackdump help chunk` command.
+
+## Viewer
+
+Slackdump V3 introduces a viewer for exported data.  To view the exported data, run:
+```
+slackdump view <export file or directory>
+```
+
+NOTE: search results are not supported by the viewer yet.
+
 
 ## Breaking changes
 
-- legacy command line interface moved under "v1" command, so if you need to
-  use the old CLI, instead of `./slackdump`, run `./slackdump v1`. The legacy
-  CLI will be phased out:  deprecated in v2.4.0, and removed in v2.5.0;
 - `-download` flag renamed to `-files` and is set to "true" by default;
 - `-r` flag that allowed to generate text files was replaced by
   `slackdump convert` command.
@@ -21,7 +47,7 @@
       `workspace select` command;
     - The "_Current_" workspace can be overridden by providing the `-w <name>`
       flag.
-- Slackdump `record` mode allows to dump the entire workspace into a directory
+- Slackdump `archive` mode allows to dump the entire workspace into a directory
   of chunk files.
 - Slackdump `convert` mode allows to convert chunk files into other formats,
   such as Slack export format, or Slackdump format.

cmd/slackdump/internal/man/assets/v2migr.md

@@ -0,0 +1,37 @@
+# Migration from V2 to V3
+
+## Authentication
+
+V2 supported a single Slack workspace.  If your Slackdump is already logged in,
+this workspace will be listed as "default" in the `slackdump workspace list`
+output.  You can continue to use this workspace in V3.
+
+If you were using `.env` or `secrets.txt` file for authentication, you need to
+run: `slackdump workspace import <filename>` to import the workspace.
+
+## Commands
+
+V3 introduces a new command structure.  The commands are now grouped into
+categories.  Usually the mapping is straightforward, i.e. `slackdump
+-list-users` becomes `slackdump list users`. The `help` command will show you
+the new command structure.
+
+Notable change is that files are downloaded by default. If you want to disable
+this behaviour, you need to specify `-files=false` flag, i.e.
+```
+slackdump export -files=false
+```
+
+## Entity list
+
+If you were using the individual timestamps for channels, the syntax has changed to use comma
+delimiters "," instead of pipe "|".  For example, to limit the export for channel C123 to
+January 2024, you should use:
+```
+slackdump export C123,2024-01-01T00:00:00,2024-02-01T00:00:00
+```
+(instead of `C123|2024-01-01T00:00:00|2024-02-01T00:00:00`)
+
+## Suggestions
+
+Suggestions to add to this document are welcomed, please open an issue or a pull request.

cmd/slackdump/internal/man/migrate.go

@@ -0,0 +1,16 @@
+package man
+
+import (
+	_ "embed"
+
+	"github.com/rusq/slackdump/v3/cmd/slackdump/internal/golang/base"
+)
+
+//go:embed assets/v2migr.md
+var mdMigrate string
+
+var Migration = &base.Command{
+	UsageLine: "v2migrate",
+	Short:     "Migrating from V2 notes",
+	Long:      mdMigrate,
+}

cmd/slackdump/internal/view/assets/view.md

@@ -1,4 +1,4 @@
-# Command: view
+# View Command
 
 The `view` command allows you to view the contents of an archive, 
 export, or dump directory or ZIP file.

cmd/slackdump/internal/workspace/assets/import.md

@@ -8,6 +8,12 @@ The file should have the following format:
 SLACK_TOKEN=xoxc-...
 SLACK_COOKIE=xoxd-...
 ```
+The command will test the provided credentials, and if successful, it will
+encrypt and save them to Slackdump's credential storage. It is recommended to
+delete the .env or secrets.txt file after the import to ensure security.
+
+Slackdump will detect the name of the workspace automatically and Select it as
+current.
 
 **SLACK_TOKEN** can be one of the following types:
 
@@ -20,7 +26,4 @@ SLACK_COOKIE=xoxd-...
 **SLACK_COOKIE** is required only if the `SLACK_TOKEN` is a client token
 (`xoxc-...`).
 
-The command will test the provided credentials, and if successful, it will
-encrypt and save them to Slackdump's credential storage. It is recommended to
-delete the .env or secrets.txt file after the import to ensure security.
 

cmd/slackdump/main.go

@@ -59,6 +59,7 @@ func init() {
 		man.Syntax,
 		man.Login,
 		man.Chunk,
+		man.Migration,
 	}
 }
 

doc/README.rst

@@ -17,7 +17,8 @@ Releases_ page, extract and run it:
 
 #. Download the archive from the Releases_ page for your operating system.
 
-   .. tip:: **MacOS users** should download ``darwin`` release file.
+   .. tip:: **MacOS users** can use ``brew install slackdump`` to install the
+      latest version.
 #. Unpack;
 #. Change directory to where you have unpacked the archive;
 #. Run ``./slackdump -h`` to view help options.
@@ -26,26 +27,29 @@ For compiling from sources see: `Compiling from sources`_
 
 Logging in
 ----------
-There are two types of login options available:
 
-- Automatic_ (**EZ-Login 3000**, works only in 64-bit systems); OR
-- Manual_
+See the quickstart_ guide on how to login.
 
-Automatic_ login is the default one, it requires no prior setup, and the
-general recommendation is to use the Automatic login.  If the Automatic login
-doesn't work for some reason, fallback to Manual_ login steps.
+If you need a token, you can use Manual_ steps, save them to the file and then
+import them with::
+
+  slackdump workspace import <filename>
+
+Read more in Workspace Import_.
+
+.. _quickstart: https://github.com/rusq/slackdump/blob/master/cmd/slackdump/internal/man/assets/quickstart.md
+.. _Import: https://github.com/rusq/slackdump/blob/master/cmd/slackdump/internal/workspace/assets/import.md
 
 Usage
 -----
-There are four modes of operation:
+There are several modes of operation:
 
 - `Listing users/channels`_
 - `Dumping messages and threads`_ (private and public)
 - `Creating a Slack export`_
 - `Downloading all Emojis`_
 
 
-.. _Automatic:  login-auto.rst
 .. _Manual: login-manual.rst
 .. _Installation: usage-install.rst
 .. _Dumping messages and threads: usage-channels.rst