Skip to content

Latest commit

 

History

History
1047 lines (721 loc) · 26.6 KB

UserGuide.adoc

File metadata and controls

1047 lines (721 loc) · 26.6 KB
Raw

SGTravel - User Guide

By: Team SGTravel Since: Aug 2019 Licence: MIT

1. Introduction

SGTravel is for those who prefer to use a desktop app for scheduling travel plans. SGTravel is also able to provide all sort of information about Singapore. Regardless whether you are a tourist or a local, SGTravel is the best application for planning your vacation plans in Singapore! More importantly, SGTravel is optimized for those who prefer to work with a Command Line Interface (CLI) while still having the benefits of a Graphical User Interface (GUI). If you can type fast, SGTravel can get your tasks done faster than traditional GUI apps. Interested? Jump to the Section 3, “Quick Start” to get started. Enjoy!

2. How to use this user guide

2.1. Basic information

To jump to a specific topic immediately, simply click on the topic in the Table of Contents at the top

To improve the navigability and readability of this user guide, multiple styles will be used, which will include the following:

  • User commands and parameters will displayed as: format

  • Important keywords will be displayed as: format

  • Keyboard buttons will be displayed as: format

Additionally, the following annotations will be used throughout this user guide:

💡

This symbol denotes a tip which you may find useful when using the application.
⚠️

This symbol denotes a warning which you will need to be careful of when using the application.
ℹ️

This symbol denotes some information or caveats that you will need to take note of when using the application.

Now that you have familiarized yourself with the style used in this guide, lets move on to how to setup SGTravel!

3. Quick Start

  1. Ensure you have Java 11 (revision 11 or later) installed in your Computer.

    ℹ️
    		 Only Java 11+ is supported.
    This app may not work with older major Java releases such as Java 10, 9, 8 etc.

  2. Download the latest SGTravel.jar here.

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

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

    Ui

  5. Type the command in the command box and press Enter to execute it.

  6. Some example commands you can try:

    • list : lists all events

    • mapJurong Regional Library : Shows the map area of Jurong Regional Library on SGTravel.

    • delete3 : deletes the 3rd event shown in the current list

    • bye : exits the app

  7. Refer to Section 4, “Features” for details of each command.

4. Features

Command Format

  • Words in UPPER_CASE are the parameters to be supplied by the user e.g. in find KEYWORD, KEYWORD is a parameter which can be used as find Zoo.

  • Items with …​ after them can be used multiple times including zero times e.g. TAG…​ (i.e. 0 times), friend, friend family fish etc.

4.1. Help: help

SGTravel shows the available commands to the user.
Format: help

Examples:

  • help

4.2. Setting a profile: profile

Setup a profile in SGTravel
Format: profile NAME BIRTHDAY

profile

Examples:

  • profile James 01/01/00

💡

Entering profile will initiate the multi-step version of this command

4.3. Showing a profile: profileShow

SGTravel shows the current profile.
Format: profileShow

profileShow

Examples:

  • profileShow

4.4. Set the preference in profile: profileSet

SGTravel sets the preferences of activity the user prefers to do in the profile.
Format: profileSet CATEGORY STATE

profileSet
ℹ️

Vaild CATEGORY:

  • sports

  • arts

  • entertainment

  • lifestyle

Vaild STATE:

  • true

  • false

Examples:

  • profileSet sports true

4.5. Adding an event: event

Adds an event to SGTravel.
Format: event VENUE between DATE and DATE

Examples:

  • event Geylang between Mon and Wed

ℹ️

  • The Dates should be entered in the following format: dd/mm/yy, dd/MM/yy HHmm, HHmm, dd/mm/yyyy, dd/MM/yyyy HHmm or DAY_OF_THE_WEEK

  • e.g. 21/12/20, Mon, Friday, 11/12/2019 2359, etc

4.6. Deleting an event : delete

Deletes the specified event from SGTravel.
Format: delete INDEX

ℹ️

  • Deletes the event at the specified INDEX.

  • The index refers to the index number shown in the displayed event list.

  • The index must be a positive integer 1, 2, 3, …​

  • The index cannot be ridiculously large 9999999999999999999999…​

Examples:

  • list
    delete 2
    Deletes the 2nd event in SGTravel.

💡

Entering delete will initiate the multi-step version of this command

4.7. Marking an event : done

Mark the specified event as done on SGTravel.
Format: done INDEX

ℹ️

  • Marks the event done at the specified INDEX.

  • The index refers to the index number shown in the displayed event list.

  • The index must be a positive integer 1, 2, 3, …​

  • The index cannot be ridiculously large 9999999999999999999999…​

Examples:

  • list
    done 2
    Marks the 2nd event as done in SGTravel.

💡

Entering done will initiate the multi-step version of this command

4.8. Editing places of visit: edit

Panel will automatically select an initial location and the current location will be glowing green in color.

edit1

Users will use up+down+left+right+ESC+Enter keys to then select the place of visit they want to edit.
Enter selects and ESC deselects.
Once an event is selected (orange), simply type in the new VENUE/DATE into the CLI depending on what is currently highlighted.

edit2

Examples:

  • Orchard road if updating the VENUE

  • Mon or 12/12/22 if updating a DATE

To save the edits, type save or done.
To discard the changes, type close or end.

💡

  • Users can type x to save changes.

  • Users can type X to discard changes.
⚠️

  • Other commands will not work while in edit mode to avoid conflicts

  • Changes will not be saved if user attempts to store 2 or more events at the same location

Examples:

  • 2 Events sharing the same Venue: Marina Bay Sands
💡

  • Alternatively, user can use the single step command:
    e INDEX LOCATION START_DATE END_DATE

  • Where INDEX is the index of the original event, LOCATION is the new location of the event, the START_DATE is the start date of the event, the END_DATE of the end date of the event.
⚠️

Single step command does not allow for locations with spaces in between them.
This is intended and is not a bug.
It is to encourage user to use the faster and more powerful edit command.
It will be treated as invalid format if user attempts to introduce spaces.

4.9. Listing all places to visit : list

SGTravel shows a list of all the places to visit in SGTravel.
Format: list

4.10. Finding certain events you have: find

SGTravel shows the events whose names contain any of the given keywords.
Format: find KEYWORD

ℹ️

  • The search is case sensitive. e.g Changi Airport will match Changi Airport

Examples:

  • find Singapore
    Returns Singapore and Singapore Bishan

💡

Entering find will initiate the multi-step version of this command

4.11. Searching for a location in Singapore: search

SGTravel finds the location with the given keywords.
Format: search KEYWORD

Examples:

  • find Bishan mrt

💡

Entering search will initiate the multi-step version of this command

4.12. Searching for the map of a location in Singapore: map

SGTravel finds the map of a location with the given keywords.
Format: map KEYWORD

Examples:

  • map ntu

    map

4.13. Recommend an Itinerary: recommend

Gets a recommended itinerary list from SGTravel.
Format: recommend itinerary between START_DATE and END_DATE

ℹ️

  • 23/04/20 to 25/04/20 is regarded as a 3 day trip.

  • Dates entered can only be in the future and valid with respects to each other. (Start date must be before End date etc.)
⚠️

This command still works if you enter 23/04/20 and 31/04/20 (invalid date). This is just the Java Library automatically changing 31/04/20 to 01/05/20. Hence, do not enter invalid dates (This is not a bug, the smart feature is enabled by default).
RecommendationsCommand

Examples:

  • recommend itinerary between 23/04/20 and 25/04/20

4.14. Save a Recommended Itinerary: addThisList

After SGTravel shows a recommended list, you can save this list using this command.
Format: addThisList NEW_ITINERARY_NAME

ℹ️

  • You must rename your list before you add it to storage.
⚠️

  • You must enter this command only after the app has recommended you a list.

  • You cannot save the same recommendation list twice, this will result in an error.
AddThisListCommand

Examples:

  • recommend between 23/04/20 and 25/04/20 then afterwards addThisList Sunday Vacation!

💡

  • Spaces in the new name are allowed.

4.15. Create new Itinerary: newItinerary

Creates a new itinerary from scratch and stores it.
Format: newItinerary START_DATE END_DATE ITINERARY_NAME DAY_NUMBER /venue VENUE_NAME /do TODO1 /and TODO2 /venue VENUE_NAME /do TODO1 /and TODO2 …. DAY_NUMBER ….

ℹ️

  • Each itinerary day can have any number of venues and todos.

  • Every venue must come with at least 2 todos.

  • Dates must be valid with respect to each other and be in the future.

  • If you enter dates with 5 days in between them. A list containing the acitivities for 5 days must be specified.
⚠️

  • You cannot re-enter a list with the same name.

  • You cannot have an itinerary name with spaces.

  • Adding 2 of the same day numbers results in an error. (Putting two day 1’s for example)

  • Adding identical venues twice in the same day will show only one instance but is still a valid input.
NewItineraryCommand

Examples:

An itinerary with multiple days.

  • newItinerary 23/04/20 24/04/20 TwoDayHoliday 1 /venue Orchard /do dancing /and singing /and swinging 2 /venue Changi /do running /and jumping /and playing

An itinerary with multiple venues in 1 day.

  • newItinerary 23/04/20 23/04/20 SundayVacay 1 /venue Bedok /do swimming /and jumping /and swinging /venue Simei /do jogging /and running

4.16. List Saved Itineraries: listItinerary

Shows the list of saved itineraries and their names.
Format: listItinerary

ℹ️

  • Enter the command exactly with no whitespaces.

Example Output:

ListItineraryCommand
💡

Use this command in order to refer to itinerary names before using the showItinerary command

4.17. Show a saved Itinerary: showItinerary

Displays a specific saved Itinerary.
Format: showItinerary ITINERARY_NAME

⚠️

  • You cannot enter an invalid name!
ShowItineraryCommand

Examples:

  • showItinerary SundayVacay

Will print the SundayVacay Itinerary.

4.18. Delete an Itinerary: doneItinerary

Removes a specified Itinerary.
Format: doneItinerary ITINERARY_NAME

ℹ️

  • You cannot enter an invalid name!
⚠️

  • The command effectively erases the list from storage. Be careful before using the command!
DoneItineraryCommand

Examples:

  • doneItinerary SundayVacay

Will mark the SundaVacay Itinerary as done (removes it from storage).

💡

If you wish to see an itinerary even after entering this command, consider adding it as a favourite!

The addToFav command will archive your favourite itineraries.

4.19. Add favourite itinerary: addToFav

Adds an itinerary to favourite list in profile.
Format: addToFav ITIERARY_NAME

addToFav

Examples:

  • addToFav SundayVacay

ℹ️

Itinerary must exist in itinerary list before it can be added to favourite list

4.20. Delete favourite itinerary: deleteFav

Removes itinerary from favourite list in profile.
Format: deleteFav ITIERARY_NAME

deleteFav

Examples:

  • deleteFav SundayVacay

4.21. List favourite itineraries: listFav

Shows the list of itinerary in favourite list.
Format: listFav

listFav

Examples:

  • listFav

💡

List of favourite itinerary can also be found in profile by using profileShow

4.22. Show favourite itinerary: showFav

Shows the details of itinerary in favourite list.
Format: showFav ITINERARY_NAME

showFav

Examples:

  • showFav my3DayTrip

  • showFav SundayVacay

4.23. Creating a new Route: routeAdd

Adds a new Route to SGTravel.
Format: routeAdd NAME

ℹ️

  • Creates a Route with the specified NAME.

  • Routes can contain different RouteNodes, which are points on the Route.
⚠️

  • You cannot create a Route that has the same name as an existing one.
routeAdd1

Examples:

  • routeAdd Day trip to Sentosa

  • routeAdd 2 Week staycation at Pulau Tekong

💡

Entering routeAdd will initiate the multi-step version of this command

4.24. Creating a new RouteNode: routeNodeAdd

Adds a new RouteNode to an existing Route.
Format: routeNodeAdd INDEXROUTE INDEXNODE at LOCATION by CONSTRAINT

ℹ️

  • Creates a RouteNode with the specified LOCATION at the Route with specified 'INDEXROUTE'.

  • Shows the information and an image of the map at the RouteNode upon creation.

  • RouteNodes are specific bus stops (BusStop), mrt stations (TrainStation) or locations in a Route (CustomNode).

  • If INDEXNODE is not specified, the RouteNode is added to the end of the Route, else it is added to position INDEXNODE.

  • If CONSTRAINT is bus, the LOCATION must correspond to the bus stop’s number. This creates a BusStop.

  • If CONSTRAINT is mrt instead, the LOCATION must correspond to the name of the MRT station, and is not case-sensitive. This creates a TrainStation.

  • If CONSTRAINT is custom instead, a CustomNode is created with the specified 'LOCATION'.
⚠️

  • You cannot add duplicate RouteNodes into a Route.

  • If there is no internet connection, the image is not shown.

Valid CONSTRAINT:

  • bus

  • mrt

  • custom

routeNodeAdd1

Examples:

  • routeNodeAdd 1 1 at 17009 by bus

  • routeNodeAdd 1 at 46431 by bus

  • routeNodeAdd 1 1 at ang mo kio by mrt

  • routeNodeAdd 1 at Bishan by mrt

  • routeNodeAdd 1 1 at jurong bird park by custom

  • routeNodeAdd 1 at Bishan Park by custom

💡

Entering routeNodeAdd will initiate the multi-step version of this command

4.25. Automatically generates a Route: routeGenerate

Automatically creates a new Route between 2 given locations with RouteNodes in it.
Format: routeGenerate STARTLOCATION to ENDLOCATION by CONSTRAINT

ℹ️

  • Creates a Route between the two locations STARTLOCATION and ENDLOCATION.

  • CONSTRAINT refers to the mode of transport.

Valid CONSTRAINT:

  • bus

routeGenerate1

Examples:

  • routeGenerate amk hub to clementi by bus

💡

Entering routeGenerate will initiate the multi-step version of this command

4.26. Listing the information of all the Routes: routeListAll

Lists the information about each Route.
Format: routeListAll

ℹ️

  • Information includes the name and description of all Routes.
routeListAll1

Examples:

  • routeListAll

4.27. Listing the information of a Route: routeList

Lists the information about a Route.
Format: routeList INDEX_ROUTE

ℹ️

  • Lists the information of the Route at index INDEX_ROUTE.

  • Information includes the name, description and all RouteNodes in the Route.
routeList1

Examples:

  • routeList 1

4.28. Showing the map image of a Route: routeShow

Shows a Route on the Singapore map.
Format: routeShow INDEX_ROUTE

ℹ️

  • Shows the map of the Route at INDEX_ROUTE in the Singapore Map.
routeShow1
routeShow2

Examples:

  • routeShow 1

💡

Entering routeList will initiate the multi-step version of this command

4.29. Showing the information of a RouteNode with image: routeNodeShow

Shows information and a map image of a RouteNode.
Format: routeNodeShow INDEX_ROUTE INDEX_NODE

ℹ️

  • Shows the information and map of the RouteNode at INDEX_NODE in Route at INDEX_ROUTE.

  • The RouteNode being shown is colored in green.

  • Nearby RouteNodes in the Route are also shown, and are colored in orange.
routeNodeShow1

Examples:

  • routeNodeShow 1 1

  • routeNodeShow 4 8

4.30. Showing the information of nearby RouteNodes with image: routeNodeNearby

Shows information of nearby bus stops and MRT stations to a RouteNode, in an image.
Format: routeNodeNearby INDEX_ROUTE INDEX_NODE

ℹ️

  • Shows the map of the RouteNode at INDEX_NODE in Route at INDEX_ROUTE and its nearby neighbours.

  • Nearby neighbours are colored in black.
routeNodeNearby1

Examples:

  • routeNodeNearby 1 1

  • routeNodeNearby 9 6

4.31. Editing a Route: routeEdit

Edits a specific field in a Route.
Format: routeEdit INDEX_ROUTE FIELD VALUE

ℹ️

  • Edits FIELD in the Route at INDEX_ROUTE and sets the new value to VALUE.

Valid FIELD:

  • name

  • description

routeEdit1
routeEdit2
routeEdit3

Examples:

  • routeEdit 1 name Go to Sentosa for the beach

  • routeEdit 3 description stop at MBS for lunch

💡

Entering routeEdit will initiate the multi-step version of this command

4.32. Deleting a Route: routeDelete

Deletes a Route.
Format: routeDelete INDEX_ROUTE

ℹ️

  • Deletes a Route at INDEX_ROUTE.
routeDelete1

Examples:

  • routeDelete 1

💡

Entering routeDelete will initiate the multi-step version of this command

4.33. Deleting a RouteNode: routeNodeDelete

Deletes a RouteNode in a Route.
Format: routeNodeDelete INDEX_ROUTE INDEX_NODE

ℹ️

  • Deletes a RouteNode at INDEX_NODE in Route at INDEX_ROUTE.
routeNodeDelete1
💡

Entering routeNodeDelete will initiate the multi-step version of this command

Examples:

  • routeNodeDelete 1 1

  • routeNodeDelete 3 10

4.34. List nearby bus stops of destination: busStop

SGTravel shows the information of a bus stop.
Format: busStop BUSCODE

busStop1

Examples:

  • busStop 17009

  • busstop 17001

💡

Entering busStop will initiate the multi-step version of this command

4.35. Shows the bus route of a bus service: busRoute

SGTravel finds the bus route of a given bus service given the bus service number.
Format: busroute BUS_NUMBER

busRoute1

Examples:

  • busRoute 96

  • busRoute 193

4.36. Viewing calendar : view

SGTravel will display a calendar containing the events. Click or hover to view other events on the same day.
Format: view

cal

4.37. Exiting the program : bye

Exits the program.
Format: bye

4.38. Saving the data

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

4.39. Viewing Singapore map

SGTravel will automatically display Singapore map when the relevant commands are invoke.

4.40. Viewing of information

All relevant information will be displayed on a side panel of the SGTravel application when the relevant commands are invoke.

5. Features that are coming in version 2.0!

5.1. List the fastest bus route, time and cost from a given location to destination: busride

SGTravel provides fastest bus route, time and cost to destination.
Format: busride START DESTINATION

Examples:

  • busride J-Cube Sentosa

5.2. List the fastest mrt route, time and cost from a given location to destination: mrtride

SGTravel provides fastest mrt route, time and cost to destination.
Format: mrtride START DESTINATION

Examples:

  • mrtride J-Cube Sentosa

5.3. Undo: undo

SGTravel undos the last command.

Examples:

  • undo

5.4. Redo: redo

SGTravel redos the last undo.

Examples:

  • redo

5.5. PSI alerts: psi

SGTravel provides user with information on PSI-levels of all destinations in Singapore.

Examples:

  • psi

5.6. UVI alerts: uvi

SGTravel provides user with information on Ultra-violet Index of Singapore.

Examples:

  • uvi

5.7. PM2.5 alerts: pm2.5

SGTravel provides user with information on PM2.5-levels of all destinations in Singapore.

Examples:

  • pm2.5

5.8. Weather alerts: weather

SGTravel provides user with information on weather of all destinations in Singapore.

Examples:

  • weather

5.9. Create a travel plan for user: worldtour

SGTravel recommends a travelling plan (short path) based on the user’s input of destinations.
Format: worldtour

Examples:

  • worldtour

5.10. Weather forecast of destinations: weather

SGTravel provides weather forecast for all destinations (including outside of Singapore) user have added.
Format: weather

Examples:

  • weather

5.11. Exchange rate: rate

SGTravel provides the currency exchange rate of the 2 currency user stated.
Format: rate CURRENCY /to CURRENCY

Examples:

  • rate SGD /to RMB

5.12. Listing popular places of a destination: recommend

SGTravel recommends popular places of visit at a given location.
Format: recommend LOCATION

Examples:

  • recommend Toronto

5.13. Listing nearby hotels of a destination: recommendhotel

SGTravel recommends hotels to stay at a given location.
Format: recommendhotel LOCATION

Examples:

  • recommendhotel Disneyland Tokyo

5.14. Listing flight information from home location to destination: flight

SGTravel recommends flights from current home location to the given destination.
Format: flight LOCATION

Examples:

  • flight Los Angeles

6. FAQ

Q: How do I transfer my data to another Computer?
A: Install the app in the other computer and overwrite the empty data file it creates with the file that contains the data of your previous SGTravel folder.

Q: Why is the Ui not refreshing by itself? A: Our Ui only updates itself when user inputs something.

Q: Why can’t I zoom into the map? A: You will be able to do so in v2.0!

Q: Why are some error messages not very informative? A: This is due to flexibility of our design and sometimes its impossible to identify the root cause.

7. Command Summary

  • Help : help
    e.g. help

  • Setting a profile : profile NAME BIRTHDAY
    e.g. profile James 01/01/00

  • Showing a profile : profileShow
    e.g. profileShow

  • Set the preference in profile : profileSet CATEGORY STATE
    e.g. profileSet sports true

  • Adding an event : event VENUE between DATE and DATE
    e.g. event Geylang between Mon and Wed

  • Deleting an event : delete INDEX
    e.g. list , delete 2

  • Marking an event : done INDEX
    e.g. list, done 2

  • Editing places of visit : edit
    e.g. Orchard road if updating the VENUE Mon or 12/12/22 if updating a DATE

  • Listing all places to visit : list
    e.g. list

  • Finding certain events you have : find KEYWORD
    e.g. find Singapore

  • Searching for a location in Singapore : search KEYWORD
    e.g. Multistep version of find

  • Searching for the map of a location in Singapore : map KEYWORD
    e.g. map ntu

  • Recommend an Itinerary : recommend itinerary between START_DATE and END_DATE
    e.g. recommend itinerary between 23/04/20 and 24/04/20

  • Save a Recommended Itinerary : addThisList NEW_ITINERARY_NAME
    e.g. addThisList MyBestVacation

  • Create new Itinerary : newItinerary START_DATE END_DATE ITINERARY_NAME DAY_NUMBER /venue VENUE_NAME /do TODO1 /and TODO2 /venue VENUE_NAME /do TODO1 /and TODO2
    e.g. newItinerary 23/04/20 23/04/20 SundayVacay 1 /venue Bedok /do swimming /and jumping /and swinging /venue Simei /do jogging /and running

  • List Saved Itineraries : listItinerary
    e.g. listItinerary

  • Show a saved Itinerary : showItinerary ITINERARY_NAME
    e.g. showItinerary SundayVacay

  • Delete an Itinerary : doneItinerary ITINERARY_NAME
    e.g. doneItinerary SundayVacay

  • Add favourite itinerary : addToFav ITIERARY_NAME
    e.g. addToFav SundayVacay

  • Delete favourite itinerary : deleteFav ITIERARY_NAME
    e.g. deleteFav SundayVacay

  • List favourite itineraries : listFav
    e.g. listFav

  • Show favourite itinerary : showFav ITINERARY_NAME
    e.g. showFav my3DayTrip

  • Creating a new Route : routeAdd NAME
    e.g. routeAdd Day trip to Sentosa

  • Creating a new RouteNode : routeNodeAdd INDEXROUTE INDEXNODE at LOCATION by CONSTRAINT
    e.g. routeNodeAdd 1 1 at 17009 by bus

  • Automatically generate a Route : routeGenerate STARTLOCATION to ENDLOCATION by CONSTRAINT
    e.g. routeGenerate amk hub to clementi by bus

  • Listing the information of all the Routes : routeListAll
    e.g. routeListAll

  • Listing the information of a Route : routeList INDEX_ROUTE
    e.g. routeList 1

  • Showing the map image of a Route : routeShow INDEX_ROUTE
    e.g. routeShow 1

  • Showing the information of a RouteNode with image : routeNodeShow INDEX_ROUTE INDEX_NODE
    e.g. routeNodeShow 4 8

  • Showing the information of nearby RouteNodes with image : routeNodeNearby INDEX_ROUTE INDEX_NODE
    e.g. routeNodeNearby 9 6

  • Editing a Route : routeEdit INDEX_ROUTE FIELD VALUE
    e.g. routeEdit 1 name Go to Sentosa for the beach

  • Deleting a Route : routeDelete INDEX_ROUTE
    e.g. routeDelete 1

  • Deleting a RouteNode : routeNodeDelete INDEX_ROUTE INDEX_NODE
    e.g. routeNodeDelete 3 10

  • List nearby bus stops of destination : busStop BUSCODE
    e.g. busStop 17009

  • Shows the bus route of a bus service : busroute BUS_NUMBER
    e.g. busRoute 96

  • Viewing calendar : view
    e.g. view

  • Exiting the program : bye
    e.g. bye