Skip to content

Latest commit

 

History

History
486 lines (366 loc) · 19 KB

UserGuide.md

File metadata and controls

486 lines (366 loc) · 19 KB

Doist - User Guide

By : W13-B4      Since: Jan 2017      Licence: MIT

  1. Introduction
  2. Quick Start
  3. Features
    3.1. Viewing help
    3.2. Adding a new task
    3.3. Listing tasks
    3.4. Sorting tasks
    3.5. Finding a task
    3.6. Editing an existing task
    3.7. Deleting a task
    3.8. Marking tasks as finished
    3.9. Undoing previous commands
    3.10. Setting an alias for a command word
    3.11. Loading an external data file
    3.12. Changing the storage location
    3.13 Changing themes
    3.14. Saving the data
    3.15. Clearing all tasks
    3.16. Exiting the program
  4. FAQs
  5. Command Summary

1. Introduction

Do you love the adrenaline rush you get when you check an item off your to-do list, but are you too busy to actually make one? Use Doist today, be a Doist and feel more organised than ever before!

Doist is the comprehensive tool to help you in all your planning. It allows you to key in, sort, tag and even search for your tasks and events so that you can focus on getting things done. Your hands never need to leave the keyboard with our command-line input interface, and our easy-to-use UI will keep you coming back for more. Once you are a Doist, there's no looking back.

Doist. Rediscover your love for doing things, one line at a time!

2. Quick Start

Are you ready to be a Doist?

  1. Ensure you have Java version 1.8.0_60 or later installed in your computer.

Having any Java 8 version is not enough. This app will not work with earlier versions of Java 8.

  1. Download the latest .jar from the releases tab.

  2. Copy the file to the folder you want to use as the home folder for Doist. You can change this later.

  3. Double-click the file to start the app. The GUI should appear in a few seconds.


    Figure 2.1: Doist Application Window

  4. Voila, you are ready to be more productive! Type a command in the command box and press Enter to execute it.
    e.g. typing help and pressing Enter will open the help window.

Getting started with commands :

Type the following commands and press Enter after each command.

  1. add Attend group meeting \from 3pm \to 5pm.
    Adds an event for today with a description of "Attend group meeting" from 3pm to 5pm today
  2. add Go grocery shopping \by 6pm 25th Oct.
    Adds a task with a description of "Go grocery shopping" which has a 6pm deadline on the 25th of October.
  3. finish 1
    Marks the first task in the list as finished.
  4. list pending
    Lists all the pending tasks.
  5. delete 1
    Deletes the 1st task shown in the current list.
  6. exit
    Exits the application.

Go ahead and try out different date and time formats for the add command!

Refer to the Features section below for details of each command.

3. Features

Command Format

Take note of some general information for our commands :

Figure 3.1: General command format

  • All parameters start with the backslash \.
    e.g. \from, \to
  • Command words and parameters that consist of multiple words will not contain spaces. Underscores are used instead.
    e.g. remove_alias
  • Words in UPPER_CASE are the values. You can enter whatever you want for them!
  • Items in [] are optional.
  • Items with ... after them can have multiple instances, separated by space.
    e.g. [INDEX...] means you can specify multiple indices for that command.
  • The command parameters can be entered in any order after the command word.
    e.g. add Buy the milk \to 3pm \from 5pm works too!

Command Features

  • Highlight: Commands get highlighted with different colours as you type!

  • Auto-complete: When you start typing a command, Doist will provide you with command word suggestions. Press TAB to accept the first suggestion.


    Figure 3.2: Autocomplete giving command word suggestions

  • Command History: Use ↑ and ↓ to scroll through previously typed commands. You won't have to remember what you have previously typed!

  • Quick Navigation: Use Esc to enter navigation mode. In navigation mode, you can use j and k to scroll through the tasks up and down respectively. To exit navigation mode and to resume normal typing, press Esc again.

3.1 Viewing help : help

Feeling a little lost? Simply type help to view the handy help page!

Format: help

The following window will appear:
Figure 3.1.1: The help window pops up when you use the help command

3.2 Adding a new task : add

You can use the add command to add tasks. Tracking your tasks is what Doist does best!

Description
Add a new task with a description by using just the add command word.

Format: add TASK_DESCRIPTION

Examples:

  • add buy milk

Start time and End time
Add a task with a start time and end time for events that occur over a period of time with \from and \to parameters.

Format: add TASK_DESCRIPTION [\from START_TIME] [\to END_TIME]

Examples:

  • add buy milk \from 3pm \to 4pm
  • add buy milk \from 12 Oct 3pm \to 12 Oct 4pm

Remarks:

  • See Figure 3.2.1 for acceptable date and time formats.

Deadline
Add a task that has a deadline with the \by key.
Format: add TASK_DESCRIPTION [\by TIME]

Examples:

  • add buy milk \by 3pm
  • add buy milk \by 28th Feb

Acceptable date and time formats

Date Format Examples
Day Month 1st Oct
Day Month Year 1st Oct 2017
Month Day Oct 1st
Month / Day 10/1
Month / Day / Year 10/1/17
Relative today, tomorrow, tmr, two days later
Time Format Examples
Hour:Min 03:00
Hour.Min 03.00, 3.00
Hour am/pm (12 hour format) 3pm, 3am
Hour (24 hour format) 3

Figure 3.2.1: Acceptable date and time formats

Remarks:

  • If you do not explicitly state the date, the date will be assumed to be within the next 24 hours
  • If you do not explicitly state the time, the time will be assumed to be the current time of the day
  • If you do not explicitly state the year, the year will be assumed to be the current year
  • Note that the start time must be earlier or equal to the end time

Priority
Add a task with higher priorities with the \as key. By default, tasks are of normal priority. Since we all have certain tasks that are more important than others, you can indicate that they are important or very important!

Format: [\as PRIORITY]

Examples:

  • add buy milk \as important
  • add buy milk \as very important

Remarks:

  • Priority can be normal, important, very important

Figure 3.2.2: Important and very important tasks have stars next to them

Tags
Add a task with tags with the \under key. Separate multiple tags with spaces.

Format: [\under TAG...]

Examples:

  • add buy milk \under shopping friends
  • add buy milk \under for_myself

Remarks:

  • Tasks can have any number of tags (including 0)

Sample Commands:

  • do group meeting \from 4pm today \to 6pm today \as important \under school_work CS2103T
  • add submit pre-tutorial activities \by 6pm this Wednesday

3.3 Listing tasks : list

You can use the list command to list different types of tasks! Doist knows that you have many tasks and will need to filter them in some way to concentrate on doing those tasks.

List all, pending, overdue, finished
Just typing list will allow you to list all tasks!
List pending, overdue, finished tasks too with the list command.

Format: list [TYPE] where TYPE can be pending, overdue or finished

Examples:

  • list
  • list pending
  • list overdue
  • list finished

Remarks:

  • list will by default show all tasks, with finished tasks placed at the bottom

List tasks during a time period
If you want to list tasks occurring during a time period, just use the \from and \to parameters.

Format: [\from TIME] [\to TIME]

Examples:

  • list \from 3pm \to 5pm

Remarks:

  • See Figure 3.2.1 for acceptable date and time formats

List tasks under tags
You can even list tasks that are under certain tags by using the \under key.

Format: [\under TAG]

Examples:
list \under shopping

Sample Commmands

  • list pending \under school_work
  • list pending \from today \to tomorrow
  • list finished \from 1st March \to 20th March \under internship

3.4 Sorting tasks : sort

You can use the sort command to sort tasks in alphabetical order, by priority or by time. You can even combine multiple sorting methods!

Format: sort TYPE [TYPE...] where TYPE can be alpha, priority or time

The default sorting

Examples:

  • sort priority
  • sort alpha priority time

Remarks:

  • By default, tasks are sorted by time, priority then alphabetical order.

3.5 Finding a task : find

You can use the find command to find tasks whose description contains any of the given search queries. You just need to remember any of the words in the description of a task to find it in your long list of tasks!

Doist will suggest descriptions of existing tasks to make finding a task easier. Just press TAB to accept the first suggestion!


Figure 3.4.1: Autocomplete giving suggestions for find

Format: find QUERY [QUERY...]

Examples:

  • find buy groceries
  • find meeting with professor

Remarks:

  • Spaces are allowed in search query.
  • The search is case insensitive.
  • The order of the search terms does not matter. e.g. Hans Bo will match Bo Hans
  • Only the task description is searched.
  • Tasks matching at least one search query will be returned. e.g. A task with a description of Hans will match search query Hans Bo
  • Even if the description of the task does not contain the exact word that you search, Doist will return close matches!

3.6 Editing an existing task : edit

You can use the edit command to edit the specified task. Feel free to edit whatever you want in one line. Be assured that other properties of the task will not change!

Format: edit INDEX [TASK_DESCRIPTION] [\from START_TIME] [\to END_TIME] [\as PRIORITY] [\under TAG...]

Just like the add command, \by can be used in place of \from and to.

Format: edit INDEX [TASK_DESCRIPTION] [\by TIME] [\as PRIORITY] [\under TAG...]

Examples:

  • edit 3 edited description of task

Remarks:

Sample Commands

  • list
    edit 1 watch NBA \from tuesday 7pm \to tuesday 9pm
    Suppose that the description of this task is originally watch nba, the new description will be changed to watch NBA. The 'from' and 'to' times will also be updated.

3.7 Deleting a task : delete

You can use the delete command to delete the task specifed by an index. The index refers to the index number of the task shown in the most recent listing.

Format: delete INDEX [INDEX...] [INDEX - INDEX]

Examples:

  • delete 3
  • delete 3 4 5
  • delete 2-6

Remarks:

  • Deletes the tasks at the specified INDEX.
  • You can delete more than one task by specifying multiple indices.
  • You can also specify a range of indices to be deleted.

Sample Commands

  • list finished
    delete 1 2
    This combination of commands deletes the 1st and the 2nd tasks in the result of list command.
  • find 'party'
    delete 1-5
    This combination of commands deletes the first 5 tasks in the results of the find command.

3.8 Marking tasks as finished : finish

You can use the finish command to mark the specified tasks as finished.

Format: finish INDEX [INDEX...] [INDEX - INDEX]

Use the unfinish command to change the status of an already finished task to not finished. unfinish INDEX [INDEX...] [INDEX - INDEX]

Examples:

  • finish 3
  • finish 3 4 7-9
  • unfinish 3

Remarks:

  • The index refers to the index number of the task shown in the most recent listing.
  • If the task(s) at the specified INDEX is/are already finished, there will be no changes made.


Figure 3.8.1: Finished tasks have their checkboxes marked and have a green sidebar

Sample Commands

  • list pending \in this week
    finish 1 2
    This combination of commands marks the 1st and the 2nd tasks in the result of list command as finished.
  • find 'project'
    finish 1
    This combination of commands marks the 1st task in the results of the find command as finished.

3.9 Undoing previous commands : undo, redo

You can use undo to undo previous commands. Undo as many times as you wish!

Format: undo
Keyboard Shortcut: Ctrl + Z

If you regret undoing a command, you can use redo to restore your changes.

Format: redo
Keyboard Shortcut: Ctrl + Y

3.10 Setting an alias for a command word : alias, view_alias, remove_alias, reset_alias

Do you feel that our default command words are too lengthy and will like to set your own command words?
You can use alias to set an alias for an existing command word. You will then be able to use the alias to trigger the command!

Format: alias ALIAS \for COMMAND_WORD

Examples:

  • alias a \for add

Remarks:

  • ALIAS should have no spaces, we suggest you use underscores to replace spaces.
  • If you are unable to set an alias, your alias is an existing command word.
  • If you try to set the same alias to two different command words, the alias will only be set for the second command word.

Viewing aliases
You can use view_alias to view the current list of aliases! There are already some default aliases set for you. For example, do can be used in place of add and ls can be used in place of list.

Format: view_alias

Removing an alias
To remove an existing alias for a command word, simply use remove_alias!

Format: remove_alias ALIAS

Resetting aliases
To remove all the aliases you have set and reset to the default aliases that was set for you, use the reset_alias command.

Format: reset_alias

3.11 Loading an external data file : load

You can use load to load an external data file (.xml) to replace the current tasks. Note that you can undo this loading of tasks later if you wish to.

Format: load PATH

Examples:

  • load C:\Users\admin\Desktop\todolist.xml
  • load /data/todoList.xml

Remarks:

  • You can provide a relative path for this command.
  • To go up a directory, use ../
  • Both / and \ are acceptable as the director separator, that is, the symbol between the folders in a path

3.12 Changing the storage location : save_at

You can use save_at to change the place that Doist would store its data at.

Format: save_at PATH

Examples:

  • save_at C:\Users\admin\Desktop
  • save_at /doist_data
  • save_at data

Remarks:

  • This is similar to 3.11 Loading an external data file
  • You can provide a relative path for this command.
  • To go up a directory, use ../
  • Both / and \ are acceptable as the director separator, that is, the symbol between the folders in a path

3.13 Changing themes

Click on Theme on the menu bar to change the look and feel of Doist! For now, there are two themes for you to choose. The default theme is LightTheme.


Figure 3.13.1: Changing the theme


Figure 3.13.2: Doist Dark Theme

3.14 Saving the data

Doist will automatically save! There is no need to save manually.

3.15 Clearing all tasks : clear

Done with all your tasks? Need an empty to-do list? You can simply use clear to clear all tasks.

Format: clear

3.16 Exiting the program : exit

Use exit to exit Doist.

Format: exit

4. FAQs

Q: How do I transfer my data to another Computer?
A: Install the app in the other computer and overwrite the empty data files (namely, todolist.xml and aliaslistmap.xml) it creates with the old data files that contains the data of your previous Doist folder.

Q: Do I need to save my data before I exit Doist?
A: You do not need to explicitly save your data, as Doist automatically does this for you!

Q: Why does Doist not recognise the date / time that I typed?
A: See Figure 3.2.1 for acceptable date and time formats. Note that we use the US Date Format of MM/DD/YYYY.

Q: Why am I unable to give an alias?
A: If you are unable to alias, your alias is an existing command word.

Q: What happens if I give an existing alias to another command word?
A: The alias will only be set for the current command word specified. It will no longer be set for the previous command word.

Q: How to I remove the timings associated with an existing task?
A: For example, if the task has an index of 1, you can simply type: edit 1 \by or edit 1 \from \to

Q: How to I remove the tags on an existing task?
A: For example, if the task has an index of 1, you can simply type: edit 1 \under

5. Command Summary


Figure 5.1: Doist Command Summary