rodo/README.md

238 lines
6.9 KiB
Markdown
Raw Normal View History

2018-03-12 14:00:41 +00:00
# rodo
2020-04-12 15:22:46 +00:00
rodo is a todo-list program for the command line.
2019-07-11 02:21:54 +00:00
Todo:
- [X] Learn the basics of Makefiles
- [X] Make a Makefile
- [ ] Update the `README.md` to match the new `Makefile`
- [ ] Remove `install.sh` and `uninstall.sh` scripts after the `README.md` is updated
2019-03-02 15:49:45 +00:00
# Screenshot
2020-03-28 19:42:29 +00:00
![](screenshot.gif)
2019-04-30 01:35:44 +00:00
# Table of Contents
2020-03-29 19:49:23 +00:00
- [About this document](#about-this-document)
- [Conventions used in this document](#conventions-used-in-this-document)
2020-01-16 17:54:49 +00:00
- [Platforms](#platforms)
- [Requirements](#requirements)
2020-03-22 03:16:56 +00:00
- [Downloading Racket](#downloading-racket)
- [To download and install Racket](#to-download-and-install-racket)
- [Downloading the rodo source code](#downloading-the-rodo-source-code)
- [To download the rodo source code](#to-download-the-rodo-source-code)
2020-03-27 00:20:01 +00:00
- [Quick start](#quick-start)
2020-03-22 03:16:56 +00:00
- [Getting started](#getting-started)
- [Installing rodo](#installing-rodo)
- [To install rodo](#to-install-rodo)
- [Uninstalling rodo](#uninstalling-rodo)
- [To uninstall rodo](#to-uninstall-rodo)
2020-01-06 21:05:52 +00:00
- [Using rodo](#using-rodo)
- [Showing the help message](#showing-the-help-message)
- [To show the help message](#to-show-the-help-message)
2020-01-06 21:05:52 +00:00
- [Initializing rodo](#initializing-rodo)
2020-01-16 17:54:49 +00:00
- [To initialize rodo](#to-initialize-rodo)
- [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)
2020-01-06 21:05:52 +00:00
- [Configuring rodo](#configuring-rodo)
- [To configure rodo](#to-configure-rodo)
2019-06-04 02:01:34 +00:00
- [List of commands](#list-of-commands)
- [Usage examples](#usage-examples)
2019-04-30 01:35:44 +00:00
2020-03-29 19:49:23 +00:00
# About this document
2020-03-29 19:49:23 +00:00
This document will guide you through downloading, installing, and using rodo.
This document assumes you have basic command line skills, such as navigating
directories, and editing files.
2019-11-11 19:00:50 +00:00
# Conventions used in this document
2019-11-11 19:00:50 +00:00
2020-05-09 20:08:02 +00:00
* **Note**: Notes signify additional information
* **Tip**: Tips signify an alternate procedure for completing a step
* **Caution**: Cautions 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
2019-11-11 19:00:50 +00:00
2020-01-16 17:54:49 +00:00
# Platforms
2018-05-20 02:03:00 +00:00
2019-11-11 19:00:50 +00:00
Below is a list of platforms that rodo can run on:
2019-02-14 20:09:47 +00:00
* GNU/Linux
* Windows Subsystem for Linux
2019-04-30 01:35:44 +00:00
* macOS (Untested)
2018-09-08 01:01:00 +00:00
2020-01-16 17:54:49 +00:00
# Requirements
2020-01-16 17:54:49 +00:00
The following items must be downloaded and installed before you can use rodo:
2018-09-08 01:01:00 +00:00
* Racket: [https://racket-lang.org/](https://racket-lang.org/)
* rodo's source code: [https://github.com/m455/rodo](https://github.com/m455/rodo)
2019-04-30 01:35:44 +00:00
2020-03-22 03:16:56 +00:00
## Downloading Racket
2020-03-15 03:43:02 +00:00
The Racket programming language will be needed to create a single-file executable
2018-10-20 01:36:52 +00:00
2020-03-22 03:16:56 +00:00
### To download and install Racket
1. Run `sudo apt install racket` on the command line
2019-01-31 14:46:14 +00:00
2020-03-22 03:16:56 +00:00
## Downloading the rodo source code
2019-11-11 19:00:50 +00:00
rodo's source code is needed so Racket's `raco` tool can create a single-file executable
2019-11-11 19:00:50 +00:00
2020-03-22 03:16:56 +00:00
### To download the rodo source code
2019-01-31 14:46:14 +00:00
1. Run `git clone https://github.com/m455/rodo`
2019-01-31 14:46:14 +00:00
2020-03-27 00:20:01 +00:00
# Quick start
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
2. `git clone https://github.com/m455/rodo`
3. `cd rodo`
4. `sudo ./install.sh`
5. `rodo`
**Note**: To uninstall, run `sudo ./uninstall.sh`
2020-03-22 03:16:56 +00:00
# Getting started
2019-11-11 19:00:50 +00:00
2020-03-22 03:16:56 +00:00
This section will guide you through settig up rodo.
2019-11-11 19:00:50 +00:00
2020-03-15 03:44:03 +00:00
**Note**: This section assumes you have already [downloaded the rodo source code](#downloading-the-rodo-source-code).
2019-01-31 14:46:14 +00:00
2020-03-22 03:16:56 +00:00
## Installing rodo
Installing rodo will add a rodo executable to the `/usr/local/bin` directory. This allows users to
run rodo from any directory on their system.
**Note**: Writing to the `/usr/local/bin` directory requires root privileges.
### To install rodo
2019-01-31 14:46:14 +00:00
1. Change to the directory you downloaded rodo into
2. Run `sudo ./install.sh`
2018-11-12 02:56:10 +00:00
2020-03-22 03:16:56 +00:00
## Uninstalling rodo
2019-11-11 19:00:50 +00:00
2020-03-22 03:16:56 +00:00
Uninstalling rodo removes the rodo executable from the `/usr/local/bin` directory.
2019-11-11 19:00:50 +00:00
2020-03-22 03:16:56 +00:00
### To uninstall rodo
2019-11-11 19:00:50 +00:00
1. Change to the directory you downloaded rodo into
2. Run `sudo ./uninstall`
2019-11-11 19:00:50 +00:00
2020-01-06 21:05:52 +00:00
# Using rodo
2020-03-15 03:27:48 +00:00
This section will teach you how to use rodo's commands.
2020-03-15 03:24:25 +00:00
2020-03-15 03:44:03 +00:00
**Note**: This section assumes you have [installed rodo](#installing-rodo).
2020-01-06 21:05:52 +00:00
## Showing the help message
2020-01-06 21:05:52 +00:00
2020-03-22 03:16:56 +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.
2020-01-06 21:05:52 +00:00
### To show the help message
2020-01-06 21:05:52 +00:00
1. Run `rodo -h`
## Initializing rodo
Before using rodo, you must initialize rodo. Initializing will allow you to save
your list to a text file for later access.
### To initialize rodo
1. Run `rodo init`
## Displaying your list
2020-01-06 21:05:52 +00:00
Displaying your list will allow you to view items you have added to your list.
2020-03-15 03:27:48 +00:00
You will notice numbers beside the items in your list.
**Note**: These numbers are useful references for when you want to remove items from your list. For
more information, see the [Removing an Item from Your List](#removing-an-item-from-your-list) topic.
2020-01-06 21:05:52 +00:00
### To display your list
2020-01-06 21:05:52 +00:00
1. Run `rodo ls`
## Adding an item to your list
2020-01-06 21:05:52 +00:00
Adding an item to your list will save it to a text file to access later.
### To add an item to your list
2020-01-06 21:05:52 +00:00
1. Run `rodo add "this is an example of an item using double quotation marks"`
2020-05-09 20:08:02 +00:00
**Note**: The double quotation marks are optional, but recommended
2020-01-06 21:05:52 +00:00
## Removing an item from your list
2020-01-06 21:05:52 +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.
### To remove an item from your list
2020-01-06 21:05:52 +00:00
1. Run `rodo rm 1`
2020-05-09 20:08:02 +00:00
**Note 1**: The "1" in the procedure above will remove the first item in your
2020-01-06 21:05:52 +00:00
list.
2020-05-09 20:08:02 +00:00
**Note 2**: You may need to run `rodo ls` first to see which numbers correspond
2020-01-06 21:05:52 +00:00
with which item in your list.
## Configuring rodo
You can configure rodo's settings, such as the location of the list file, and
command names.
### To configure rodo
2020-01-06 21:05:52 +00:00
**Caution**: Changing the `config.rkt` file should be done at your own risk as it may break rodo's functionality
1. Edit the `config.rkt` file
2. `sudo ./install.sh`
2020-01-06 21:05:52 +00:00
2019-04-30 01:35:44 +00:00
# List of commands
This section lists and describes rodo's commands.
2018-04-10 00:27:01 +00:00
2019-04-30 01:35:44 +00:00
* `-h` or `--help` displays the help message
* `init` creates a list file (See the `config.rkt` file for the default location of this file)
* `ls` displays your list
* `add` adds an item to your list
* `rm` removes an item from your list
2018-04-13 06:14:51 +00:00
2019-04-30 00:31:36 +00:00
# Usage examples
2018-04-10 00:27:01 +00:00
2019-11-11 19:00:50 +00:00
The examples below assume that you have [added rodo to your $PATH](#adding-rodo-to-your-path).
2019-03-13 03:43:15 +00:00
`rodo -h`
`rodo --help`
`rodo init`
2018-04-13 06:14:51 +00:00
`rodo ls`
2018-09-08 04:30:28 +00:00
`rodo add "this is an item"`
2018-09-08 04:30:28 +00:00
`rodo add this is an item without quotation marks`
2018-09-08 04:30:28 +00:00
2019-11-11 19:00:50 +00:00
`rodo rm 1`
2019-11-11 19:00:50 +00:00
**Note**: You may have to run `rodo ls` to see which number corresponds to which item in your list.