Step 1 of User Documentation

User Documentation/1-Installation.md

@@ -0,0 +1,47 @@
+# Installing Task
+
+This installation guide was written on July 12th, 2023. Since Task is still in alpha, the installation method may change in the future.
+
+1. Clone the contents of the `setup/as-command` branch into a repository of your choosing.  
+    ```
+    git init
+    git clone -b setup/as-command https://github.com/hanssun07/racket-task.git
+    ``` 
+    > **Check:** Along wih the README, you should see `empty-domain.dat`, `task-config`, and 3 scripts: `task`, `task-sync`, `task-update`.
+2. Update your system PATH variable to include the directory above. The method to do this varies between Operating System, so look it up if you must.
+    > **Check:** *Restart the Terminal First!* If you can type `task` into the terminal and *NOT* get "command not found", you did this step right (It should still error out though)
+3. In your terminal's configuration, update your terminal's variables to export the EDITOR variable. This variable tells Task what text editor to boot up to make changes to tasks. For example, in a Bash Shell, append to the `.bashrc` file:
+    ```
+    export EDITOR=vim
+    ```
+    to make Task boot up vim.
+    > This might vary depending on choice of terminal - if in doubt, look it up!
+4. Run this in the terminal to grab the most recent version of Task:
+    ```
+    task-update
+    ```
+    Optionally, specify which branch to grab by instead using `task-update <branch>`. 
+    > `task-update` is also how you update the Task program, so run it occasionally! 
+
+    > **Check:** You should see a folder called `program` be created in the repository containing the scripts.
+
+That's all the configuration on the system - now, we need to clear the scripts and reboot Task's configuration.
+> **Note:** If you wish to add multiple task domains or manage user login behaviour, you would be changing these files! 
+
+5. `task-sync` is for if you wish to share your tasks with other people through the internet, like with a GitHub repository! To explain fully we would need to discuss what a task domain is, which is done later.
+    Go ahead and just remove the 3 sample `run` commands listed at the end, or commment them out for now.
+6. `task` is the main application, and needs to know where to look to save data. Again, has to do with domain stuff. 
+    For now, just remove the 3 sample `check` commands, or comment them out.
+7. `task.config` tells task about each of the task domains - what they are, where to find them, user info etc.
+    For now, remove code so that it only reads:
+    ```
+    (domain :
+    (datafile "empty-domain.dat")
+    (login "admin"))
+    ```
+8. Good to go! Run `task`, and you eventually be greeted with something like:
+    ```
+    Logged in as :admin
+    admin@:>
+    ```
+   And you're in the REPL!

User Documentation/2-DomainsUsers.md

@@ -0,0 +1,105 @@
+# Domains and Users
+
+Being able to work to track individual progress is cool and all, but what if you want to share your progress with friends or coworkers? Or maintain some form of work-life seperation and organize tasks seperately? This is where domains and users come in.
+
+> A **domain** is a grouping of tasks that make sense together in some way. For example, you could have a domain to track progress for 1 project, and another domain for another project.
+
+> **Users** are people authorized (by name) to access a certain domain. You can change who you login as for each domain by changing the `(login "XXX")` in the respective domain setting in task.config - but more on this later.
+
+Say you are Elvarg, and you want to get together with your friends Vorkath and Galvek to open a cute bakery together and want to keep track of tasks. However, you and Galvek also want to secretly use the bakery as a front for world domination (Vorkath is unaware of this).
+
+You have also already created two GitHub repositories to allow for the tasks to be shared, and copied down the clone link. However, they are both empty.
+
+## Setting Up Domains and Users
+1. Elvarg needs to create two folders on her computer, each of which containing a copy of `empty-domain.dat`. Name it `data.dat`. Elvarg would also initialize these as git repositories.
+    > You could also just create the .dat file, if you want. Here's what's in there to start:
+    >  ```
+    >  ()
+    >  (("admin"))
+    >  ```
+   Here is what the file structure could look like:
+   ```
+   |- bakery-tasks
+   |   \- bakery-data.dat
+   |- dom-tasks
+       \- domination-data.dat
+   |- task
+   |- task-sync
+   |- task-update
+   |- task.config
+   ```
+2. Elvarg needs to tell Task about these 2 domains:
+    1. The `task` script needs to know to check for these 2 folders. At the end of the `task` script, Elvarg should add 2 routes from wherever the `task` script is to the respective folders:
+        ```
+        check ./bakery-tasks
+        check ./dom-tasks
+       ```
+    2. The `task.config` needs to be able to login to these domains properly. Elvarg should add these to `task.config`:
+        ```
+        (domain Frontend:
+          (datafile "./bakery-tasks/bakery-data.dat")
+          (login "admin"))
+        (domain EvilPlans:
+          (datafile "./dom-tasks/domination-data.dat")
+          (login "admin"))
+        ```
+        The name ___ in `(domain ___:` tells Task what the domain's nickname is, while the datafile field of courses tells where the datafile is located.  
+        The login field tells Task which user is logged into this domain - we didn't add any users yet, so we have to use "admin".
+3. Elvarg can then login to Task and add Vorkath, Galvek and herself as users:
+    ```C
+    task // to get into Task
+    cd Frontend // swap to the Bakery domain
+    u Elvarg // command to add user
+    u Galvek
+    u Vorkath
+    cd EvilPlans // and for world domination...
+    u Elvarg
+    u Galvek
+    q // quit out of task
+    ```
+4. [OPTIONAL] Elvarg can change the login in `task.config` from `"admin"` to `"Elvarg"` now, no longer needing to log in as admin.
+5. Elvarg needs to edit `task-sync` so keeping track of progress with GitHub is easier. To the bottom of the script, add:
+    ```
+    run ./bakery-tasks <Bakery-repository-link> -b main
+    run ./dom-tasks <WorldDom-repository-link>
+    ```
+    THE `[-b <branchName>]` part is optional, for if you want your changes to go to a specific branch.
+6. Finally, Elvarg runs `task-sync` to upload the changes to the shared repository.
+
+## Using a Remote Task Domain
+Galvek and Vorkath can now each see the task domain on GitHub, and start tracking their progress. Let's focus on Galvek - for Vorkath it is similar. 
+1. Galvek creates 2 folders in his computer to store the domains. Here is what the file structure could look like:
+   ```
+   |- baking-tasks
+   |- destroying-tasks
+   |- task
+   |- task-sync
+   |- task-update
+   |- task.config
+   ```
+2. Galvek edits `task-sync` to track the GitHub repositories that Elvarg set up. He adds:
+    ```
+    run ./baking-tasks <Bakery-repository-link> -b main
+    run ./destroying-tasks <WorldDom-repository-link>
+    ```
+3. Galvek can now run `task-sync` - if all is correct, the `.dat` files should appear in the respective domains.
+4. Galvek needs to similarly edit `task` by adding these 2 to the end:
+    ```
+    check ./baking-tasks
+    check ./destroying-tasks
+    ```
+5. Galvek also edits `task.config`. Since Elvarg set it up, Galvek can now log in as himself (or admin, if he wants). He adds:
+    ```
+    (domain Cookings:
+      (datafile "./baking-tasks/bakery-data.dat")
+      (login "Galvek"))
+    (domain Crimes:
+      (datafile "./destroying-tasks/domination-data.dat")
+      (login "Galvek"))
+    ```
+6. Galvek can now run `task`, make changes, and when done run `task-sync` to upload the changes onto GitHub for Elvarg and Vorkath to see.
+
+## Summary
+- Domains are specially-built `.dat` files that can be shared across systems through repositories like GitHub.
+- New users past "admin" are added using the `u <user>` command in Task
+- There are 3 places to edit when adding a new domain: `task`, `task.config` and `task-setup` (if nessecary)

User Documentation/3-TaskREPL.md

@@ -0,0 +1,91 @@
+# The Task REPL
+
+After you have logged onto Task by typing `task`, you should be greeted with a list of all the task domains you're logged into, as well as a prompt for commands.
+
+Continuing our example from earlier, Vorkath has set up his domains and has logged in. By typing in the command `ld`, he sees 2 domains: `:`, the root domain; and `bakery` (assuming he named the domain "bakery" in `task.config`).
+
+When Task initializes, it always starts in the root domain. From here, Vorkath can type in any of the valid commands to do things. Commands have a full name and a shorthand.
+
+### ? | help
+
+Pretty self explanatory - if you ever get lost or forget the name of a command, this summons the list of all valid commands.
+
+### : | summary
+
+This command provides a summary of tasks that have been assigned to the users logged in, tasks that are pending assignment, as well as a count for how many tasks need evaluation by the user. This takes into account tasks from _all domains_.
+
+## Domain Management
+
+### ld | list-domains
+Displays a list of all currently available task domains.
+
+### cd | change-domain
+`change-domain` allows the user to hop between different task domains. It takes one input as well - the path to the other domain. Shortcuts also exist to hop from the root domain or to the home domain:
+
+```C
+    cd /...    // from the root domain
+    cd ~       // to the home domain
+    cd         // to the home domain
+```
+
+For example, Vorkath can switch to the `bakery` domain with `cd bakery`.
+
+### \<path\>:\<command\>
+If you want to run a command in a specific domain without first `cd`-ing into it, this is the command for you. Simply prepend any other command (along with it's inputs) with the path and a colon `:`.
+For example, if Vorkath were in the root `:` domain, he could run `bakery:cat 0` to run `cat 0` within the bakery task domain.
+
+## User Management
+
+### u | new-user
+Adds a new user to the current task domain. Takes one input, which is the name of the user, no quotations nessecary.
+For example, if Vorkath wants to add Bob to help on the tasks, he could do `u Bob`. After saving these changes, Bob can now setup `task.config` to login as "Bob".
+
+### swap-user
+This command lets you login to a different user. Upon typing in the command, a prompt will appear. Type in a valid username to swap to that user.
+
+## Task Management
+
+### n | new-task
+
+`new-task` creates a new task in the domain you are currently in. It takes one input, the name of the task in quotations.
+For instance, after Vorkath switches to the `bakery` domain, he could do:
+
+```C
+    n "Perfect recipe for bread"
+    n "Get Food Safety Approval for dragonfire cooking"
+    n "Finish budgeting for Quarter 4"
+    n "Violate antitrust laws"
+```
+
+to initialize 4 new tasks.
+
+### ls | list
+
+Lists out all tasks in the current task domain, including their ID, name, status, and either priority score or current assignee. `ls` can be augmented with options to filter results:
+
+- `-a` will display all tasks, even tasks that `ls` usually hides for brevity
+- `-a [word]` displays all tasks that meet a certain criteria, dependent on the word. - `ready` / `assigned` / `done` will only show tasks that have the "ready", "assigned", or "done" status respectively - `blocked` / `unassigned` / `not-done` are the inverses of the above, showing all tasks without the matching status - `mine` shows all tasks assigned to the current user - a `<number>` can be used to indicate a maximum number of tasks to show - `-t` or `by-id` will list tasks in ascending id order - `-p` or `by-priority` will list tasks in descending priority score
+- Options can also be used together to achieve precision filtering - in this case, the options are applied from left to right. For instance, `ls -a mine -p 3` will display the 3 most prioritized tasks assigned to the current user.
+
+### cat | view-task
+Given the id of a task (for instance, `cat 0`), it will provide more details about the task in the current task domain, such as a detailed description, the priority score, and timestamps for when the task was created, finished etc.
+
+### e | eval
+Enters evaluation mode, allowing the user to assign priority, interest and whether the task description needs to be refined.
+
+### ed | edit
+Given a Task ID (for instance, `ed 0`), enters edit mode, allowing the user to edit the task description and name, as well as assign the task or otherwise change the task's status.
+
+## Saving and Exiting
+
+### reload
+Unknown Behavior? It seems to run an infinite loop for now...
+
+### commit
+Unknown Behavior? It seems to do nothing for now...
+
+### q | quit
+Save all your changes, commiting all changes in all task domains. It then quits out of Task.
+
+### q! | exit
+Ragequit out of Task, discarding all changes from the current session.

User Documentation/4-TasksAndModes.md

@@ -0,0 +1,72 @@
+# Tasks, Edit Mode and Evaluate Mode
+
+## What is a Task?
+A Task has all of the following:
+
+0. A unique ID (Ex. 0)
+1. A name (Ex. Violate Antitrust Laws)
+2. An optional description (Ex. Monopolize Gilenor's Baking Industry)
+3. A status (Ex. Ready)
+4. Evaluations from each user, each containing:
+    1. An interest ranking from 0 to 4
+    2. A priority ranking from 0 to 4
+    3. Whether the task needs refinement or not (1 for yes, 0 for no)
+A complete overview of each Task can be obtained by using the `cat` command on the task's ID.
+
+## What are the Statuses?
+### Blocked (b)
+Means that the task is currently inaccessible - often becuase there is another task that it depends on that is undone, or some other reason. These tasks are only visible by using the `ls -a` or `ls -a blocked` command.
+
+### Ready (r)
+Means that the task is ready to go - anyone can start working on it! These tasks show up with `ls` and include a number roughly representing which task you should prioritize (based on task evaluations users have done).
+
+### Assigned (a)
+Means that the task is currently being worked on by a user (which could include yourself). When `ls`-ing, instead of the task piority number, it shows which user is currently assigned to the task.
+
+### Done (d)
+Task is complete, woo! Only visible with `ls -a` or `ls -a done` to avoid clutter. 
+
+## What is Evaluation Mode?
+Upon entering the `e` command, the user will enter evaluation mode, allowing the user to rank the tasks. 
+
+### \<interest\> \<priority\> \<needs-refinement\>
+In some order, each of the tasks that the user has partially unranked will appear. The user then should input 3 numbers, seperated with spaces, which represent the interest ranking, the piority ranking, and whether the tasks need refinement, in that order.
+If less than 3 inputs are given, those values that are not given inputs remain unset.
+```C
+4 2 0   // ok
+3     0          1   // sure?
+2 // priority and interest remain unassigned.
+5 5 5 // out of bound input, causes an error.
+```
+
+### s | skip
+Skips evaluation of the current task, and move on to the next one.
+### ? | help
+Displays a list of all available commands, if you ever need it.
+### q | quit
+Exit Evaluation Mode, and return to the main REPL.
+
+## What is Edit Mode?
+Upon entering the `ed` command with an ID, the user will enter Edit Mode, allowing the user to edit details of the task.
+
+### cat | show
+Displays the current task's attributes.
+### sd | set-desc
+Opens up the user's editor of choice (specified by the EDITOR environment variable set during installation). The user can then input whatever description they want there, and upon saving and exiting the editor it will write it to the description.
+### n | rename
+Takes one input, which is a string of text in quotations. Use it to change the task's name.
+### b | block
+Set the task's status to blocked.
+### r | ready
+Set the task's status to ready.
+### a | assign
+Takes a username as an input. Sets the task's status to assigned, and assigned it the the user with the given username.
+By default, if no username is specified, the task is assigned to the current user.
+### d | done
+Set a task's status to done.
+### e | eval
+Edit the evaluation given to the task. Takes 3 three inputs, in the same format and order as in Evaluation Mode.
+### ? | help
+Displays a list of all the available commands, if you ever need it.
+### q | quit
+Exit Edit Mode and return to the main REPL.

User Documentation/README.md

@@ -0,0 +1,12 @@
+# Task
+
+Task is an incremental command-line task manager system, complete with multiple users, task domains, and much more!   
+Powered by Racket, and in active alpha. 
+
+## Table of Contents
+1. Installation - how to setup Task for yourself
+2. Domains and Users - Setting up Task groups and Collaborators
+3. The Task REPL - How to navigate Task
+4. Tasks, Edit Mode and Evaluate Mode - How to use Task
+
+###### Made by Andoiiii