PlanMySem - User Guide

By: Team T08-3 Since: Jan 2019 Licence: MIT

1. Introduction
2. About this User Guide
3. Quick Start
4. Features
5. FAQ
6. Command Summary

1. Introduction

Welcome to PlanMySem!

PlanMySem is a text-based (Command Line Interface) scheduling/calendar application that caters to NUS students and staff who prefer to use a desktop application for managing their schedule/calendar. PlanMySem automatically creates a planner that is synchronised according to the NUS academic calendar for the current semester and enables easy creation, editing and deleting of items. Special weeks such as recess week and reading week are taken into account within our unique recursion system. Items can then be efficiently managed via the intuitive tagging system.

PlanMySem is optimized for those who prefer to work with a Command Line Interface (CLI) and/or are learning to work more efficiently with CLI tools. Additionally, unlike traditional calendar/scheduling applications, PlanMySem utilizes minimal resources on the user’s machine while still allowing the user to view their schedules swiftly and efficiently.

2. About this User Guide

This user guide provides a quick start guide for you to easily setup and install PlanMySem, documentation of all the various features PlanMySem offers, frequently asked questions and a summary of the available commands. To navigate between the different sections, you could use the table of contents above.

For ease of communication, this document will refer to lessons/activities/events/appointments that you might add into the planner as slots.

Additionally, throughout this user guide, there will be various icons used as described below.

💡	This is a tip. Follow these suggested tips to make your life much simpler when using PlanMySem!

ℹ️	This is a note. These are things for you to take note of when using PlanMySem.

❗	This is a sign-post dictating important information. These are information that you will surely need to know to use PlanMySem efficiently.

🔥	This is a sign-post informing caution. Please take note of these items and exercise some care.

⚠️	This is a rule. Ensure that you follow these rules to ensure proper usage of PlanMySem.

3. Quick Start

This section guides you through the installation of PlanMySem and provides a few example commands you may try.

Ensure you have Java version 9 or later installed in your Computer.
Download the latest planmysem.jar here.
Copy the file to the folder you want to use as the home folder for your planner.
Double-click the file to start the app. You should see the GUI appear in a few seconds.

Figure 1. GUI screen upon start-up
Type the command in the command box and press Enter to execute it.
E.g. typing help and pressing Enter will open the help window.
Some example commands you can try:
- addn/CS2113T d/mon st/08:00 et/09:00 des/Topic: Sequence Diagram t/CS2113T t/Tutorial :
  Add a slot, named "CS2113T" on the coming monday, from 0800hrs to 0900hrs with the tags "CS2113T" and "Tutorial".
- listn/CS2113T : list all slots named "CS2113T"
- delete3 : delete the 3rd slot shown in the current list
- exit : exit the app
Refer to Section 4, “Features” for details of each command.

4. Features

This section displays the available features of PlanMySem together with examples for you to refer to.

Tagging System

Unlike other commercial calendar/scheduling/planner software, PlanMySem makes use of a tagging system to manage slots.

Using tags to tag slots will make tasks easier for you in the future. Performing tasks such as viewing, deleting and editing slots will be more efficient.

Recommended uses for tags:

Tag modules. E.g. "CS2113T", "CS2101".
Tag type of lesson. E.g. "Lecture", "Tutorial", "Lab".
Tag type of activities. E.g. "Sports", "Seminar", "Talk".
Tag difficulty of task. E.g. "Tough", "Simple", "Trivial".

Recursion System

Recursion facilitates quick addition of multiple slots, similar to Microsoft Outlook’s series of appointments.

In NUS, academic semesters are split into weeks of several types. Recursion allows you to add slots to these types of weeks with ease through the use of the r/(recursion) parameter.

Command Format

Words in UPPER_CASE are the parameters to be supplied by the user. E.g. in t/TAG, TAG is a parameter which can be used as the name of the tag.
Items in square brackets are optional. e.g in add [l/LOCATION], LOCATION is a parameter that may be omitted.
Items with … after them can be used multiple times including zero times. E.g. [t/TAG]… can be used 0 times, or as t/lab, t/lecture, t/tutorial etc.
Parameters can be in any order. E.g. if the command specifies st/START_TIME et/END_TIME d/DATE, then both et/09:00 st/08:00 d/2-13-2019 and et/09:00 d/2-13-2019 st/08:00 are acceptable.

💡	You can save time by utilizing the alternate and shortcut commands. E.g. instead of using `delete`, you may also use `del` or simply `d`.

Identifiers and Parameters

Identifiers in PlanMySem are designed to be, short and easy to memorise. Once you are familiarised with them, they should be intuitive to use to add your parameters. The table of Identifiers and Parameters and their descriptions (Table 1) below is useful for your reference as you jump right into grasping the system.

Table 1. Identifiers and their Parameters and descriptions.

Identifier	Parameter	Description	Format	Example
`n/`	`NAME`	Name of a slot	Text	`n/CS2113T`
`n/`	`KEYWORD`	Text that are part of the name of a slot	Text	`n/CS`
`l/`	`LOCATION`	Location of a slot	Text	`l/COM2 04-22`
`des/`	`DESCRIPTION`	Description of a slot	Text	`des/Topic: Abstraction`
`t/`	`TAG`	Tag of a slot	Text	`t/Lab`
`d/`	`DATE`	Date	`dd-mm-yyyy`	`d/01-02-2019`
	`DATE`	Date	`dd-mm`	`d/01-02`
	`DAY`	Day of week	Name of day	`d/Monday`
	`DAY`	Day of week	Name of day (short-form)	`d/mon`
`st/`	`START_TIME`	Start time	Time in 24-Hour format, `hh:mm`	`st/23:00`
`st/`	`START_TIME`	Start time	Time in 12-Hour format, form of `hh:mm+AM\|PM`	`st/11:00 PM`
`et/`	`END_TIME`	End Time	Time in 24-Hour format, `hh:mm`	`et/23:00`
	`END_TIME`	End Time	Time 12-Hour format, `hh:mm+AM\|PM`	`et/11:00 PM`
	`DURATION`	Duration from Start Time	Number of minutes	`et/60`
`r/`	`RECURRENCE`	Recurse slot on normal academic weeks	`normal`	`r/normal`
		Recurse slot on recess week	`recess`	`r/recess`
		Recurse slot on reading week	`reading`	`r/reading`
		Recurse slot on examination weeks	`exam`	`r/exam`
		Recurse slot on past dates	`past`	`r/past`

💡	You may order identifiers and parameters in any fashion and you will still be able to achieve what you want! So, do not bother thinking about where to place parameters as ordering does not matter, instead become more efficient and save your time!

❗	Identifiers may be appended with a `n` to dictate "new". E.g. `nt/NEW_TAG` signifies new tags in which you want to replace existing tags with.

🔥	While table 1 shows you all the identifiers and parameters that PlanMySem uses, there are some commands that do not make use of identifiers nor parameters. The view command is one such exception that make use of keywords that must be typed in a specific order.

4.1. Viewing help : `help`

Displays all the available commands with the syntax and examples.
Format: help

Figure 2. Output after entering help

4.2. Adding Slots : `add` / `a`

Add slot(s) to the planner.
Format: add n/NAME d/DATE_OR_DAY_OF_WEEK st/START_TIME et/END_TIME_OR_DURATION [l/LOCATION] [des/DESCRIPTION] [r/normal] [r/recess] [r/reading] [r/exam] [r/past] [t/TAG]…

Examples:

add n/CS2113T Lecture d/mon st/8:00 am et/9:00 am des/Topic: Software Engineering t/CS2113T t/Lecture r/normal r/past
Add a single slot, named "CS2113T Lecture" with description "Software Engineering" on all mondays, from 0800hrs to 0900hrs with the tags "CS2113T" and "Tutorial". Here, the recursion parameters enable a single command to place 13 slots on all "normal" weeks that lectures take place on.

Figure 3. Output after entering add n/CS2113T Lecture d/mon st/8:00 am et/9:00 am des/Topic: Software Engineering t/CS2113T t/Lecture r/normal r/past

add n/CS2113T Lecture d/mon st/8:00 am et/9:00 am des/Topic: Software Engineering t/CS2113T t/Lecture r/recess r/reading r/past
Do the same but instead of "normal" weeks, do the opposite of the norm and recurse the slot on both recess and reading week.
add n/CS2113T Lecture d/mon st/8:00 am et/9:00 am des/Topic: Software Engineering t/CS2113T t/Lecture
Do the same but without any recursion, instead place the slot the coming monday.

💡	You may add single slots by omitting the `r/` identifiers and its parameters.

ℹ️	PlanMySem does not dictate your scheduling preferences. As such, you may even add identical slots or slots with overlapping start and end times to help plan for tentative/unconfirmed events.

4.3. Editing Slots: `edit` / `e`

Edit slot(s).

Edit slot(s) which contains certain tag(s).
Format: edit t/TAG… [nn/NEW_NAME] [nst/NEW_START_TIME] [net/NEW_END_TIME|DURATION] [nl/NEW_LOCATION] [ndes/NEW_DESCRIPTION] [nt/NEW_TAG]…
Edit specific slot via the list command.
Format: edit INDEX [nn/NEW_NAME] [nd/NEW_DATE] [nst/NEW_START_TIME] [net/NEW_END_TIME|DURATION] [nl/NEW_LOCATION] [ndes/NEW_DESCRIPTION] [nt/NEW_TAG]…

ℹ️	You will not be able to edit a slot's date when editing via tags. To edit a slot's date, you may use the `list` or `find` command and edit specific slot(s) via index.

Examples:

edit t/CS2113T t/Lecture nl/COM2 04-01
Edit slots that contain tags "Lecture" and "Tutorial", set these slot’s location to "COM2 04-01".

Figure 4. Output after entering edit t/CS2113T t/Lecture nl/COM2 04-01

edit 1 nl/ICube
Edit the first item from the previous result of the list or find command, replace it’s location with "ICube".

4.4. Delete Slots: `delete` / `del` / `d`

Delete slot(s) which contains certain tag(s).
Format: delete t/TAG…
Delete slot via the list command.
Format: delete INDEX

💡	You may delete a specific slot by using the `list` or `find` command and select the specific slot via index.

Examples:

delete t/CS2113T t/Lecture
Delete slots that contain both tags "CS2113T" and "Lecture".

Figure 5. Output after entering delete t/CS2113T t/Lecture

delete t/Lecture
Delete slots that contain the tag "Lecture".
delete 2
Delete the second slot shown via the list command.

4.5. Listing Slots: `list` / `l`

Lists all slots whose name/tag directly matches the specified keyword (not case-sensitive).
Format: list n/NAME

You can also list all slots in the planner as well.
Format: list all

💡	Keywords are not case-sensitive. (e.g. CS2113T is the same as cs2113t)

Examples:

list n/CS2113T Lecture
List all slots that is named CS2113T Lecture.
list t/Lecture
List all slots that contain the tag Lecture.
list all List all slots in the planner.

Figure 6. Output after entering list t/Lecture

4.6. Finding Slots: `find` / `f`

Find all slots whose name closely matches the specified keyword and displays them as a list. (Case-sensitive)
Format: find n/KEYWORD

🔥	Keywords are case sensitive! (e.g. CS2113T is not the same as cs2113t)

ℹ️	The `find` command will return the closest matching `Slot` which contains the specified keyword. The name/tag MUST contain the specified keyword in order for a match to occur.

💡	You may want to use short keywords (e.g CS) instead of long keywords to increase the chances of finding your desired slot. E.g. Let’s say you are finding a `Slot` named Golf. `find n/Go` will detect the slot, while `find n/Golfs` will fail to detect the slot.

Example:

find n/CS
Find all slots whose name closely matches CS (eg. CS2101, CS2113T, SOCSMeet)
find t/2113T
Find all slots that contain tags that closely matches 2113T.

Figure 7. Output after entering find n/CS

Explanation: As seen from the figure above, the output list of slots are ranked according to their degree of similarity. All of the Slots listed contain the keyword 'CS'.
Since 'JSOCS' has less characters, it is considered closest to the keyword 'CS', which has only 2 characters.
Remember the tip above when you are finding your Slots.

4.7. View the Planner : `view` / `v`

View the planner in a month/week/day view.

View the monthly calendar view of the current academic semester.
Format: view month

View the weekly calendar view of the current academic week.
Format: view week [WEEK]
[WEEK] is valid if it is:

Any number from 1 to 13 (as there is only week 1 to 13 in a semester).

Any of the following text (case-insensitive): recess, reading, exam, examination.

💡	You may add in the parameter `details` after `[WEEK]` to view the details of all slots with respect to the `[WEEK]`. E.g. `view week 13 details` will allow you to view details of all slots in week 13!

View the day view of a particular day in the academic semester.
Format: view day [DATE_OR_DAY_OF_WEEK]
[DATE_OR_DAY_OF_WEEK] is valid if it is:
- Any number from 1 to 7 (the numbers 1 to 7 corresponds to the days Monday to Sunday respectively).
- Any of the following text (case-insensitive): Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday.
  The three-letter abbreviation of the days (e.g. mon, tue) is accepted as well.
- A date in the format of "dd-mm" or "dd-mm-yyyy" (e.g. 16-04 or 16-04-2019). The date must exist in the current semester.

💡

You may omit [WEEK]/[DATE_OR_DAY_OF_WEEK] to view the calendar with respect to the current date!
E.g. view week will allow you to view the current week and view day will allow you to view the current day!
If you have added slots to the planner, the expected output after successfully running view week will be similar to the expected output shown in the figure below.

Figure 8. Expected output after entering view week

The following are some examples of the view command which you can try to run.

Month view example:

view month
View planner for the months of the current academic semester.

Week view examples:

view week details
View planner for current week of the academic calendar with details of all slots.
view week 7
View planner for week 7 of the academic calendar.
view week recess
View planner for recess week of the academic calendar.

Day view examples:

view day
View planner for the current date.
view day 01-03-2019
View planner for the first of March.
view day monday
View planner for the upcoming Monday.

4.8. Listing previous input commands : `history`

Lists all the commands that you have entered in reverse chronological order.
Format: history

An empty command history is initialised when PlanMySem is started. It will be cleared upon exiting PlanMySem.

ℹ️	Invalid commands will also be logged into the command history.

4.9. Undoing previous command : `undo`

Restores the planner to the state before the previous command was executed.
Format: undo

ℹ️	Only Add, Edit, Delete and Clear Commands are undoable.

4.10. Redoing the previously undone command : `redo`

Reverses the most recent undo command.
Format: redo

ℹ️	Only Add, Edit, Delete and Clear Commands are redoable.

4.11. Encrypting/decrypting data files

Planner data is automatically encrypted before saving and decrypted before loading. You do not need to encrypt or decrypt the data manually.

4.12. Exporting .ics formatted files: `export`

You can export the planner as a .ics file. Format: export [fn/FILE_NAME]

Figure 9. Output after entering export

ℹ️	The default name of the exported file is "PlanMySem.ics" and is saved in the main directory. The .ics file can be imported into other calendar apps that support .ics files such as Google Calendar. Figure 10. Location of PlanMySem.ics file

💡	A file with the ICS file extension is an iCalendar file. These are plain text files that include calendar event details like a description, beginning and ending times, location, etc.

4.13. Importing native .ics files `import`

You can import a .ics file generated by PlanMySem into the current planner. Format: import [fn/FILE_NAME]/

⚠️	This feature is to allow transfer of data between PlanMySem on different devices. This feature is NOT for importing non-native .ics files. Hence, only .ics files generated by PlanMySem should be imported.

4.14. Clear all data : `clear`

Clear all data stored on the planner.
Format: clear

Figure 11. Output after entering clear

ℹ️	The `clear` command cannot be undone! Your data will be permanently removed once `clear` is executed.

4.15. Exiting the program : `exit`

Exits the program.
Format: exit

4.16. Saving the data

Planner data is saved in the hard disk automatically after any command that changes the data is executed.
There is no need to save manually.

5. FAQ

Q: How do I transfer my data to another computer?
A: In order to transfer your data to another computer, you should:

Install the app on the other computer
Transfer PlanMySem.txt from your old PlanMySem folder and place it into the new PlanMySem folder.

This will overwrite the empty data file it creates with the file that contains the data of your previous PlanMySem folder.

6. Command Summary

6.1. General Commands

General commands that you might find useful in helping you to navigate and configure PlanMySem:

Task	Purpose	Command	Example
Help	Shows you the user guide	`help`	`help`
History	Shows you a history of all commands used	`history`	`history`
Undo	Undo your previous command	`undo`	`undo`
Redo	Redo your undo	`redo`	`redo`
Clear	Clear your planner	`clear`	`clear`
Exit	Exit the PlanMySem	`exit`	`exit`

6.2. Manipulating the Planner

Commands to manage slots:

Task	Purpose	Command	Example
Add slot(s)	Add slot(s) into the planner	`add`	`add n/CS2113T Tutorial d/mon st/08:00 et/09:00 t/CS2113T`
Edit slot(s)	Edit slot(s)	`edit`	`edit t/CS2113T nl/COM2 04-01`
Delete slot(s)	Delete slot(s)	`delete`	`delete t/CS2113T`

6.3. Viewing the Planner

Commands to view slots:

Task	Purpose	Command	Example
View the planner	view the planner in a chosen format/layout	`view`	`view month`
List slot(s)	list slot(s) of a certain name	`list`	`list n/CS2113T`
Find slot(s)	find slot(s) containing certain keywords	`find`	`find CS`

6.4. Import/Exporting the Planner

Commands:

Task	Purpose	Command	Example
Export your planner	Export all your slots into a .ics file	`export`	`export`
Import into your planner	Import a native .ics file into your planner from a .ics file	`import`	`import fn/PlanMySem`

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

UserGuide.adoc

UserGuide.adoc

PlanMySem - User Guide

1. Introduction

2. About this User Guide

3. Quick Start