WhereTourGo: A Tour Guide’s Best Friend!

WhereTourGo (WTG) is a desktop app for managing your tour contacts, optimized for use via a Command-Line Interface (CLI) while still having the benefits of a Graphical User Interface (GUI).

The app helps you easily collate and access contacts of a variety of several services such as F&B, accommodations, attractions etc. It is also enhanced with many functionalities to make modification and navigation a smooth experience.

A CLI processes your commands in the form of lines of text, while a GUI is another form of user interface that allows you to interact with our app through graphical icons.

Once you are familiar with our commands, typing fast in CLI allows you to get your contact management tasks done faster and more efficiently than traditional GUI apps. Handling repetitive tasks also becomes easier as we offer access to input history, allowing you to access past commands conveniently.

This User Guide will help you set up your contact list and familiarise yourself with the features of WhereTourGo.

Can’t wait to get started? Check out the Quick Start to get going!

Table of Contents

• Quick Start
• About
  • Structure of this document
  • Orienting to WhereTourGo
  • Reading this document
    • Technical Terms
    • General Symbols and Syntax
    • Format of commands
    • Restrictions for Commands
• Features
  • Modifying Contacts
    • Adding a contact: add
    • Editing a contact: edit
    • Deleting a contact: delete
  • Retrieving Contacts
    • Listing all contacts: list
    • Locating contacts: find
    • Filtering contacts: filter
    • Sorting contacts: sort
    • Summarizing contacts: sum
    • Viewing a contact : view
  • Navigating WhereTourGo
    • Navigating input history
    • Clicking on contacts
  • Undoing and Redoing
    • Undoing operations : undo
    • Redoing operations : redo
  • Managing Data
    • Exporting data: export
    • Clearing all entries : clear
    • Saving the data
    • Editing the data file
    • Exiting the program : exit
  • Help
    • Viewing help: help
    • Displaying commands: cmd
• FAQ
• Command Summary

Quick Start

1. Ensure you have Java 11 or above installed in your Computer. You may install it here

2. Download the latest WhereTourGo.jar from here

3. Copy the file to the folder you want to use as the home folder for your WhereTourGo

For Windows

1. Simply double-click the file to start the app

For Mac

1. Open Terminal

2. Navigate to the home folder you have chosen for your WhereTourGo.
   For example, if you have moved the app to Desktop, simply run:

cd Desktop

1. Run the following command:

java -jar WhereTourGo.jar

After launching the app, GUI similar to the below should appear in a few seconds. Note how the app contains some sample data.

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:

• list : Lists all contacts

• addc/att n/Mandarin Oriental p/98765432 e/Mandarin_Oriental@example.com a/Marina Bay Sands, Singapore 123432 : Adds a contact named Mandarin Oriental

• delete3 : Deletes the 3rd contact shown in the current list

• clear : Deletes all contacts

• exit : Exits the app

You can refer to the Features below for details of every command.

Back to top

About

Structure of this document

This User Guide is crafted to assist you in finding what you need easily.

In the subsection Reading this document, there are several tips on how to read this guide.

The following section, Features, details the features in WhereTourGo and how to use them.

To make your navigation easier, click Back to top located throughout this document to navigate back to the table of contents.

Orienting to WhereTourGo

Below is the Home screen of WhereTourGo, with its key components marked out for easy reference:

Reading this document

This section introduces some technical terms, symbols and syntax used in this guide. Do try to familiarize yourself with them before moving on to the subsequent sections.

Technical Terms

The table below explains some technical terms frequently used throughout this User Guide.

General Symbols and Syntax

The table below explains the general notations used throughout the user guide.

Syntax	What it means
command	A grey highlighted block specifies an executable command, or parameters that can be entered into the command box.
italics	Italicised text indicates that the text has a definition specific to WhereTourGo, or it is a caption for a Figure in the guide.
	A light bulb indicates that the following text is a useful tip.
	A warning sign indicates that the following text is important.

Format of Commands

The following points explain the format of a command. More examples will be provided for each command in Features.

• Words in UPPER_CASE are the parameters to be supplied by the user
  e.g. in add n/NAME, NAME is a parameter which can be used as add n/Mandarin Oriental.

• Items in square brackets are optional
  e.g n/NAME [t/TAG] can be used as n/Mandarin Oriental t/hotel or as n/Mandarin Oriental.

• Items with …​ after them can be used multiple times including none
  e.g. [t/TAG]…​ can be used as ` ` (i.e. 0 times) t/food, t/wine t/food or not at all

• Parameters can be in any order
  e.g. if the command specifies n/NAME p/PHONE_NUMBER, p/PHONE_NUMBER n/NAME is also acceptable.

• If a parameter is expected only once in the command, but you specify it multiple times, only the last occurrence of the parameter will be taken
  e.g. if you specify p/12341234 p/56785678, only p/56785678 will be taken.

• Duplicate contact names are not allowed e.g. if there exists a contact named ‘Marina Bay Sands’, adding or editing a contact with the name ‘Marina Bay Sands’ is not allowed.
  

• Contact names are case-sensitive e.g. VivoCity is not the same as vivocity

Restrictions for Commands

• For each contact, there are maximum field sizes:
  • Name has a limit of 100 characters.
  • Address has a limit of 150 characters.
  • Emails must have a domain name i.e. @gmail.com, @yahoo.com etc.
  • Phone number has a limit of 15 digits.
  • Review has a limit of 500 characters.
• Category Codes only accept the following 6 inputs:
  • Attraction: att
  • F&B: fnb
  • Commerce: com
  • Accommodation: acc
  • Transport: tpt
  • Others: oth
• Ratings only accept the following 5 inputs:
  • 1-star : ra/1
  • 2-star : ra/2
  • 3-star : ra/3
  • 4-star : ra/4
  • 5-star : ra/5

Back to top

Features

Modifying Contacts

Adding a contact: add

Adds a contact to the contact list.

Category codes and ratings can be found here.

Usage scenario:

• You discover a new attraction to record.

Format: add c/CATEGORY_CODE n/CONTACT_NAME p/PHONE_NUMBER e/EMAIL a/ADDRESS [rv/REVIEW] [ra/RATING] [t/TAG]…​​

Tip: A contact can have any number of tags, or none at all! Similarly, reviews and ratings are optional.

Examples:

• add c/att n/Singapore Flyers p/92345678 e/123@example.com a/30 Raffles Ave, Singapore 039803 ra/4

Expected Outcome for add c/att n/Singapore Flyers p/92345678 e/123@example.com a/30 Raffles Ave, Singapore 039803 ra/4 :

Back to top

Editing a contact: edit

Edits an existing contact in the contact list.

Category codes and ratings can be found here.

Usage scenario:

• You realise you entered the name of a restaurant wrongly, and want to rectify it.

Format: edit INDEX [n/CONTACT_NAME] [p/PHONE] [e/EMAIL] [a/ADDRESS] [rv/REVIEW] [c/CATEGORY_CODE][ra/RATING] [t/TAG]…​

• Edits the contact at the specified INDEX. The index refers to the index number shown in the displayed contact list. The index must be a positive integer 1, 2, 3, …​
• At least one of the optional fields must be provided.
• Fields will be updated based on input values.
• When editing tags, the existing tags of the contact will be removed (i.e. adding of tags is not cumulative).

Tip: You can remove all of a contact’s tags by typing t/ without specifying any tags after it.

Examples:

• edit 1 p/92345678 e/Mandarin_Oriental@example.com Edits the phone number and email address of the 1st contact to be 92345678 and Mandarin_Oriental@example.com respectively.
• edit 2 n/Marina Bay Sands t/ Edits the name of the 2nd contact to be Marina Bay Sands and clears all existing tags.
• edit 3 ra/3 Edits the rating of the 3rd contact to be 3.

Expected Outcome for edit 1 p/92345678 e/Mandarin_Oriental@example.com:

Before:

After:

Back to top

Deleting a contact: delete

Deletes the specified contact from the contact list, either by name or index.

Usage scenario:

• You want to remove a hotel’s contact information from WhereTourGo, as it has closed down.

Format: delete INDEX

• Deletes the contact at the specified INDEX.
• The index refers to the index number shown in the displayed contact list.
• The index must be a positive integer 1, 2, 3, …

Examples:

• list followed by delete 2 deletes the 2nd contact in the contact list.
• find Marina Bay Sands followed by delete 1 deletes the 1st contact in the results of the find command.

Expected Outcome for find Marina Bay Sands followed by delete 1:

Format: delete n/CONTACT_NAME

• Deletes the contact specified by CONTACT_NAME
• The name must refer to a contact’s full name in the displayed contact list.
• The name is case-sensitive and must match the contact’s name exactly.

Examples:

• list followed by delete n/Singapore DUCKTours deletes the contact with name ‘Singapore DUCKTours`.
• filter c/fnb followed by delete n/Green on Earth Vegetarian Cafe deletes the contact with name ‘Earth Vegetarian Cafe’.

Expected Outcome for filter c/fnb followed by delete n/Green on Earth Vegetarian Cafe:

Back to top

Retrieving Contacts

Listing all contacts: list

Shows a list of all contacts in the contact list.

Usage scenario:

• You would like to have an overview of all your existing contacts in WhereTourGo.

Format: list

Back to top

Locating contacts: find

Finds all contacts whose names, addresses, phone numbers, email addresses or reviews contain any of the given keywords.

Usage scenario:

• You would like to find any places of interest which are along Orchard Road (have ‘Orchard Road’ contained within their address field).
• You remember leaving a positive review on the room service of a particular hotel, but have forgotten which hotel it was for. You would like to find which contact this review was written for.

Format: find KEYWORD [MORE_KEYWORDS]

• The search is case-insensitive, e.g., hotel will match Hotel.
• The order of the keywords does not matter. e.g. Park Hyatt will match Hyatt Park.
• Fields searched are: name, phone, email, address and review.
• Contacts matching at least one keyword will be returned . e.g. Park will return Park Hyatt Singapore, Park Royale.

Examples:

• find hotel returns D’ Hotel and The Fullerton Hotel.
• find bay returns Gardens by the Bay and Marina Bay Sands.

Expected Outcome for find bay:

Back to top

Filtering contacts: filter

Shows a list of all contacts in the specified category, with the specified rating and/or with the specified tag.

Usage scenario:

• You want to filter for all hotels (in category ‘acc’) which have a 5-star rating.
• You would like to filter all restaurants (in category ‘fnb’) which are affordable (with the tag ‘cheap’).

Format: filter [c/CATEGORY] [ra/NUMBER] [t/TAGS] ...

Category codes and ratings can be found here.

• Tags:
  • Any custom tags you’ve added into your contacts!

Tip: You can add multiple category and tag filters in a single command, but only a single rating filter!

Examples:

• filter c/fnb returns McDonald’s, KFC, and Burger King (all F&B contacts).
• filter c/acc c/fnb returns Mandarin Oriental, and KFC (all accommodation and F&B contacts).
• filter ra/3 t/outdoor returns all contacts with 3-star rating and outdoor tag from all categories.
• filter c/fnb ra/3 t/fun t/outdoor returns all F&B contacts with 3-star rating, and with fun and/or outdoor tags.

Expected Outcome for filter c/fnb:

Back to top

Sorting the contacts: sort

Sorts the list of contacts in a specified order. The sort feature sorts by Contact name (in lexicographical order) or by Rating (in descending order).

Usage scenario:

• You want to see all the highest rated contacts at one glance.
• You want to arrange a messy list of contacts by lexicographical order.

Format : sort FIELD

Examples :

• sort name returns the same list of contacts displayed in lexicographical order.
• sort rating returns the same list of contacts displayed, sorted from highest to lowest rating.

Back to top

Summarizing contacts: sum

Shows a summary of the content of WhereTourGo. The data presented as a summary are as follows:

• total number of contacts in the contact list.
• the proportion of contacts for each rating (Does not include unrated contacts).
• the proportion of contacts for each category defined by Category code.

Usage scenario:

• You want to improve on the quality of your tours. You would like to review the database to see which category of tour contacts lacks diversity.
• You would like to assess the quality of your contacts by viewing the proportion of contacts with high ratings.

Format: sum

Expected Outcome for sum:

Back to top

Viewing a contact: view

Displays the specified contact from the contact list.

Usage scenario:

• You want to zoom in on a particular contact to obtain all the information.

Format: view INDEX

• Displays the contact at the specified INDEX.
• The index refers to the index number shown in the displayed contact list.
• The index must be a positive integer 1, 2, 3, …

Examples:

• list followed by view 2 displays the 2nd contact in the contact list.
• find Mandarin Oriental followed by view 1 displays the first contact in the results of the find command.

Format: view n/CONTACT_NAME

• Displays the contact specified by CONTACT_NAME.
• The name must refer to a contact’s full name in the displayed contact list.
• The name is case-sensitive and must match exactly.

Examples:

• list followed by view n/Marina Bay Sands displays the contact with name ‘Marina Bay Sands’.
• find Gardens By The Bay followed by view n/Gardens By The Bay displays the contact with name ‘Gardens By The Bay’.

Back to top

Navigating WhereTourGo

Navigating input history

When typing commands, you can use the up and down arrow keys to access previously entered inputs.

Back to top

Clicking on contacts

Click on any contact in the Contacts Pane to view more information about the contact. This is equivalent to using a view command.

Back to top

Undoing and Redoing

Undoing operations: undo

Undoes the last change made to the list of contacts stored.

Usage scenario:

• You deleted an important contact by mistake and would like to restore this contact.

Format: undo

Examples :

• If you execute the command delete Marina Bay Sands, then execute the command undo, the Marina Bay Sands contact will be restored.

Back to top

Redoing operations: redo

Redoes the last change undone on the list of contacts stored.

Usage scenario:

• You edited a contact’s rating and used undo to revert your changes. However, you decided that you want to edit the contact’s rating again.

Format: redo

Examples :

• If you execute the command delete n/Marina Bay Sands, then execute the command undo , the Marina Bay Sands contact will be restored. If you then execute redo , the Marina Bay Sands contact will be deleted again

Tip: Only commands that directly change the stored data can be redone and undone. These commands include add, delete, edit, sort and clear.

Back to top

Managing Data

Exporting data: export

Exports all the contacts from the contact list to a well-formatted .txt file.

Usage scenario:

• You need to forward tour information quickly to someone else (i.e. the tour bus driver, an anxious tour participant).

Format: export

• Exports the specified contact from the contact list.
• The text file will be written with the path [JAR file location]/data/export.txt.

Format: export INDEX

• Exports the contact at the specified INDEX.
• The index refers to the index number shown in the displayed contact list.
• The index must be a positive integer 1, 2, 3, …

Examples:

• list followed by export 2 exports the second contact in the contact list.
• find Mandarin Oriental followed by export 1 exports the first contact in the results of the find command.

A sample of the exported text file:

Back to top

Clearing all entries: clear

Clears all entries from the contact list.

Usage scenario:

• You want to wipe out the current database and start afresh.

Format: clear

Back to top

Saving the data

WhereTourGo data is saved in the hard disk automatically after any command that changes the data. You do not need to save your changes manually!

Back to top

Editing the data file

WhereTourGo data is saved as a JSON file at [JAR file location]/data/addressbook.json. Advanced users are welcome to update data directly by editing that data file.

Back to top

Help

Viewing help: help

Open the User Guide in your default Browser.

Usage scenario:

• You are new to the app and want to find basic commands to get started with.

Format: help

Caution: If the User Guide cannot be opened in the Browser, a link to the User Guide will be provided.

Please refer to the FAQ for more information.

Back to top

Displaying commands: cmd

Open the command list in your default Browser.

Usage scenario:

• You want to view a command and its syntax as you have forgotten how it should be used.

Format: cmd

Caution: If the command list cannot be opened in the Browser, a link to the User Guide will be provided.

Please refer to the FAQ for more information.

Back to top

Exiting the program: exit

Exits the program.

Format: exit

Back to top

FAQ

Q: How do I save my data?
A: Your contact list is saved in your hard disk automatically for each command that modifies the list.

Q: Where is my data saved?
A: When our app is first opened, it will create a folder named data in the same folder where the JAR file is located. This folder contains a file called addressbook.json which contains all of your contacts with the corresponding details.

Q: Where can I find my text file after executing the export command? A: You can find the nicely-formatted text file called export.txt in the folder named data. (Path: data/export.txt)

Q: How do I transfer my data to another computer?
A: Install the app in the other computer. Overwrite the empty data file it creates with the data file from your previous WhereTourGo home folder.

Q: What do I do if I forget the format of all the commands?
A: You can type either cmd to show the command summary or help to open our User Guide.

Q: Why does cmd/help command open a backup window with a link instead of my browser?
A: Check to ensure that your browser installed has been upgraded to the latest version. Restart the app and try again. If the issue still isn’t resolved, please contact us at “WhereTourGo@gmail.com”.

Back to top

Command summary

Back to top