nicethings/README.md

285 lines
10 KiB
Markdown
Raw Normal View History

# nicethings
2020-01-20 19:17:21 +00:00
2021-03-09 23:26:22 +00:00
A program to cheer people up on shared Unix servers, specifically, [tilde.town](https://tilde.town).
2020-01-20 19:17:21 +00:00
2021-02-25 00:18:47 +00:00
## Table of Contents
2020-07-07 15:45:19 +00:00
2020-11-28 05:30:02 +00:00
<!-- vim-markdown-toc GFM -->
* [Disclaimer](#disclaimer)
* [Conventions used in this document](#conventions-used-in-this-document)
* [How it works](#how-it-works)
* [How it works in detail](#how-it-works-in-detail)
* [Platforms](#platforms)
* [Requirements](#requirements)
* [Quick start](#quick-start)
* [Downloading nicethings](#downloading-nicethings)
* [Downloading nicethings using git](#downloading-nicethings-using-git)
* [To download nicethings using git](#to-download-nicethings-using-git)
* [Installing nicethings](#installing-nicethings)
* [Installing nicethings globally](#installing-nicethings-globally)
* [To install nicethings globally](#to-install-nicethings-globally)
* [Installing nicethings locally](#installing-nicethings-locally)
* [To install nicethings locally](#to-install-nicethings-locally)
* [Installing nicethings to a custom directory](#installing-nicethings-to-a-custom-directory)
* [To install nicethings to a custom directory](#to-install-nicethings-to-a-custom-directory)
* [Uninstalling nicethings](#uninstalling-nicethings)
* [Uninstalling nicethings globally](#uninstalling-nicethings-globally)
* [To uninstall nicethings globally](#to-uninstall-nicethings-globally)
* [Uninstalling nicethings locally](#uninstalling-nicethings-locally)
* [To uninstall nicethings locally](#to-uninstall-nicethings-locally)
* [Using nicethings](#using-nicethings)
* [Showing the help message](#showing-the-help-message)
* [To show the help message](#to-show-the-help-message)
* [Displaying your list](#displaying-your-list)
* [To display your list](#to-display-your-list)
* [Adding an item to your list](#adding-an-item-to-your-list)
* [To add an item to your list](#to-add-an-item-to-your-list)
* [Removing an item from your list](#removing-an-item-from-your-list)
* [To remove an item from your list](#to-remove-an-item-from-your-list)
* [List of commands](#list-of-commands)
* [Usage examples](#usage-examples)
<!-- vim-markdown-toc -->
2020-01-20 19:17:21 +00:00
2021-02-25 00:18:47 +00:00
## Disclaimer
2020-07-07 15:45:19 +00:00
This is a hobby project I built for [tilde.town](tilde.town).
I take no responsibility for anything that nicethings deletes.
Backup anything you don't want deleted.
2021-02-25 00:18:47 +00:00
## Conventions used in this document
2020-07-07 15:45:19 +00:00
* **Note**: Notes signify additional information
* **Tip**: Tips signify an alternate procedure for completing a step
* **Warning**: Warnings signify that damage may occur
* **Example**: Examples provide a visual reference of how a procedure would be carried out in the real world
* `Inline code`: Inline code signifies package names, filenames, or commands
* ```Code block```: Code blocks signify file contents
2021-02-25 00:18:47 +00:00
## How it works
2020-11-28 05:30:02 +00:00
Each user on the shared Unix server may have a `.nicethings` file. The `.nicethings` file may be
populated with a list of nice messages created by a user. All users' `.nicethings` files are
converted to lists. All lists are combined into one list. A random nice message is picked from from
this list and is displayed to the user.
2021-02-25 00:18:47 +00:00
### How it works in detail
2020-11-28 05:30:02 +00:00
* Each user has a `~/.nicethings` directory.
* Users can add messages to this file using the `nicethings add "your nice message here"` interface.
* Each message is stored in the file as separate lines. No file format is used.
* Users can display a numbered list of the messages they have stored using the `nicethings ls` interface.
* Users can remove their own messages using the `nicethings rm 2` interface, where the number refers to an item in their list.
* Users can view a random message from a random user using the `nicethings` interface (with no arguments).
2021-02-25 00:18:47 +00:00
## Platforms
2020-07-07 15:45:19 +00:00
Below is a list of platforms that nicethings can run on:
* GNU/Linux
* Windows (Using Windows Subsystem for Linux)
* macOS (Using [Homebrew](https://brew.sh/))
2021-02-25 00:18:47 +00:00
## Requirements
2020-07-07 15:45:19 +00:00
The following items must be downloaded and installed before you can use nicethings:
* Racket: [https://racket-lang.org/](https://racket-lang.org/)
2021-02-25 00:18:47 +00:00
## Quick start
2020-07-07 15:45:19 +00:00
This section is for users who are familiar with git, a Unix-like command line environment, or
scripting.
1. Make sure [Racket](https://racket-lang.org/) is installed
2020-10-01 02:31:48 +00:00
2. `git clone https://git.m455.casa/m455/nicethings.git`
2020-07-07 15:45:19 +00:00
3. `cd nicethings`
4. `sudo make install-global`
5. `nicethings`
**Note**: To uninstall, run `sudo make uninstall-global`
* `nicethings help` - Displays the help message
* `nicethings add "your nice message here"` - Adds the message inside of quotation marks to your list of nice things
* `nicethings ls` - Displays your list of nice things
* `nicethings rm 2` - Removes the third item from your list. (The list starts at 0)
**Note**: You may need to run `nicethings ls` to see which number corresponds to which item in your list before running `nicethings rm <number>`
2021-02-25 00:18:47 +00:00
## Downloading nicethings
2020-07-07 15:45:19 +00:00
nicethings's source code exists in a public git repository. This makes
accessing the code convenient, because you don't need to sign in or
register for an account to download it.
2021-02-25 00:18:47 +00:00
### Downloading nicethings using git
2020-07-07 15:45:19 +00:00
You can use tools such as `git` to download nicethings's source code. You
will need the source code to install nicethings.
2021-02-25 00:18:47 +00:00
#### To download nicethings using git
2020-01-20 19:17:21 +00:00
2020-10-01 02:31:48 +00:00
1. Run `git clone https://git.m455.casa/m455/nicethings.git`
2020-07-07 15:45:19 +00:00
**Note**: This will create a `nicethings` directory in your current directory.
2021-02-25 00:18:47 +00:00
## Installing nicethings
2020-07-07 15:45:19 +00:00
You can either install nicethings globally or locally on your system. A global installation allows all users on a machine to use nicethings, while a local installation only allows one user to use nicethings.
See the options below for installing nicethings:
* [Installing nicethings globally](#installing-nicethings-globally)
* [Installing nicethings locally](#installing-nicethings-locally)
* [Installing nicethings to a custom directory](#installing-nicethings-to-a-custom-directory)
2021-02-25 00:18:47 +00:00
### Installing nicethings globally
2020-07-07 15:45:19 +00:00
This option will install nicethings into `/usr/local/bin/`.
This section assumes you have [downloaded nicethings](#downloading-nicethings).
2021-02-25 00:18:47 +00:00
#### To install nicethings globally
2020-07-07 15:45:19 +00:00
1. Run `cd nicethings`
2. Run `sudo make install-global`
2021-02-25 00:18:47 +00:00
### Installing nicethings locally
2020-07-07 15:45:19 +00:00
This option will install nicethings into `~/.local/bin/`.
This section assumes you have [downloaded nicethings](#downloading-nicethings).
2021-02-25 00:18:47 +00:00
#### To install nicethings locally
2020-07-07 15:45:19 +00:00
1. Run `cd nicethings`
2. Run `make install-local`
2020-07-07 15:45:19 +00:00
2021-02-25 00:18:47 +00:00
### Installing nicethings to a custom directory
2020-07-07 15:45:19 +00:00
If you wish to have nicethings exist elsewhere on your system, you can also
build a single-file executable. Building a single-file executable
allows you to place the executable in convenient places on your
system, such as a directory on your `$PATH`.
This section assumes you have [downloaded nicethings](#downloading-nicethings).
2021-02-25 00:18:47 +00:00
#### To install nicethings to a custom directory
2020-07-07 15:45:19 +00:00
**Warning**: You will have to manually uninstall custom installations
1. Run `cd nicethings`
2020-07-11 22:52:28 +00:00
2. Run `make install-custom location=~/path/to/custom/location`
**Example**: In step 2., you could run `make install-custom location=~/bin/`
2020-07-07 15:45:19 +00:00
2021-02-25 00:18:47 +00:00
## Uninstalling nicethings
2020-07-07 15:45:19 +00:00
Depending on your installation method, you can uninstall a global or local installation of nicethings.
See the options below for uninstalling nicethings:
* [Uninstalling nicethings globally](#uninstalling-nicethings-globally)
* [Uninstalling nicethings locally](#uninstalling-nicethings-locally)
2021-02-25 00:18:47 +00:00
### Uninstalling nicethings globally
2020-07-07 15:45:19 +00:00
This option will remove the `nicethings` executable from `/usr/local/bin/`.
This section assumes you have [downloaded nicethings](#downloading-nicethings).
2021-02-25 00:18:47 +00:00
#### To uninstall nicethings globally
2020-07-07 15:45:19 +00:00
1. Run `cd nicethings`
2. Run `sudo make uninstall-global`
2021-02-25 00:18:47 +00:00
### Uninstalling nicethings locally
2020-07-07 15:45:19 +00:00
This option will remove the `nicethings` executable from `~/.local/bin/`.
This section assumes you have [downloaded nicethings](#downloading-nicethings).
2021-02-25 00:18:47 +00:00
#### To uninstall nicethings locally
2020-07-07 15:45:19 +00:00
1. Run `cd nicethings`
2. Run `make uninstall-local`
2020-07-07 15:45:19 +00:00
2021-02-25 00:18:47 +00:00
## Using nicethings
2020-07-07 15:45:19 +00:00
This section will teach you how to use nicethings's commands.
This section assumes you have [installed nicethings](#installing-nicethings).
2021-02-25 00:18:47 +00:00
### Showing the help message
2020-07-07 15:45:19 +00:00
The help message will provide a list of available commands. This is list useful in case you forget
the name of a command or how to use a command.
2021-02-25 00:18:47 +00:00
#### To show the help message
2020-07-07 15:45:19 +00:00
1. Run `nicethings help`
2021-02-25 00:18:47 +00:00
### Displaying your list
2020-07-07 15:45:19 +00:00
Displaying your list will allow you to view items you have added to your list.
You will notice numbers beside the items in your list.
2020-11-28 05:32:44 +00:00
**Note**: These numbers are useful references for when you want to
[remove items from your list](#removing-an-item-from-your-list).
2020-07-07 15:45:19 +00:00
2021-02-25 00:18:47 +00:00
#### To display your list
2020-07-07 15:45:19 +00:00
1. Run `nicethings ls`
2021-02-25 00:18:47 +00:00
### Adding an item to your list
2020-07-07 15:45:19 +00:00
Adding an item to your list will save it to a text file to access later.
2021-02-25 00:18:47 +00:00
#### To add an item to your list
2020-07-07 15:45:19 +00:00
1. Run `nicethings add "this is an example of an item using double quotation marks"`
**Note**: The double quotation marks are optional, but recommended
2021-02-25 00:18:47 +00:00
### Removing an item from your list
2020-07-07 15:45:19 +00:00
When removing an item from your list, you can reference the numbers beside each
item when [Displaying Your List](#displaying-your-list). You can use these
numbers when removing an item from your list.
2021-02-25 00:18:47 +00:00
#### To remove an item from your list
2020-07-07 15:45:19 +00:00
1. Run `nicethings rm 1`
**Note 1**: The "1" in the procedure above will remove the first item in your
list.
**Note 2**: You may need to run `nicethings ls` first to see which numbers correspond
with which item in your list.
2021-02-25 00:18:47 +00:00
## List of commands
2020-07-07 15:45:19 +00:00
This section lists and describes nicethings's commands.
* `help` displays the help message
* `ls` displays your list
* `add` adds an item to your list
* `rm` removes an item from your list
2021-02-25 00:18:47 +00:00
## Usage examples
2020-07-07 15:45:19 +00:00
The examples below assume that you have [added nicethings to your $PATH](#adding-nicethings-to-your-path).
`nicethings help`
`nicethings ls`
`nicethings add "this is a nice message"`
`nicethings rm 1`
**Note**: You may have to run `nicethings ls` to see which number corresponds to which item in your list.