By: Team Notably Since: Feb 2020 Licence: MIT

1. Introduction

Notably is for those who prefer to use a desktop app for managing notes. More importantly, Notably 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, Notably can get your notes taken down faster than traditional GUI apps.

1.1. An Introduction to Notably

The following 3 diagrams (Figure 1, Figure 2, Figure 3) highlight key sections of Notably’s user interface. Refer to the description below each diagram for more information.

Legends1
Figure 1. Notably GUI legends

  1. As shown in the top-left hand corner of the diagram above, Notably’s Sidebar allows you to systematically organise your notes in a hierarchical manner.

  2. As shown in the centre of the diagram above, Notably allows you to view the content of your notes in a structured way.

  3. As shown in the top-centre of the diagram above, you can interact with Notably by typing certain commands.

Legends2
Figure 2. Notably GUI legends (continued)

  1. As highlighted in diagram above, Notably’s response text provides you with constant feedback and guidance with every keystroke.

  2. Notably helps you to find what you’re looking for by intelligently providing you with a list of suggestions.

Legends3
Figure 3. Notably GUI legends (continued)

  1. As shown in the diagram above, Notably allows you to edit and customise your notes in a fuss free manner.

1.2. Symbols used in this guide

Denotes something that you may want to take note of.
Denotes something that may be helpful if you are having any difficulties.
Denotes a warning for something critical.

2. Getting started

  1. Ensure you have Java 11 or above installed in your Computer.

  2. Download the latest notably.jar

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

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

  5. Type the command in the command box and press Enter to execute it.
    e.g. typing help and pressing Enter will open the help modal.

3. Features

Command Legend

  • Words in UPPER_CASE are the parameters to be supplied by the user e.g. in open NAME, NAME is a parameter which can be used as open Notably.

  • Items in square brackets are optional e.g open [-t] TITLE can be used as open -t TITLE or as open TITLE, where TITLE is the title of the note.

  • Parameters can be in any order e.g. if the command specifies new -t TITLE [-o], new [-o] -t TITLE is also acceptable.

Paths

  • Paths are used to specify the location of a note you want the Command to be pointed at.

  • There are 2 types of Path namely:

    • AbsolutePath (which takes reference from the root, as shown in Figure 2 below)

    • RelativePath (which takes reference from the current note)

/ represents a root note

The RelativePath operates similarly to the command line input that you may be familiar with. Listed below are the notations used to define a RelativePath.

  • . (Point to current note)

  • .. (Point to parent note)

  • exampleNote (Point to child node)

Validity of Paths

  • AbsolutePath

    • Must start with the root note.

    • After every / you can provide a Title (Valid Title).

    • /Workspace/2103T is a valid AbsolutePath, Workspace/2103T is not.

  • Relative Path

    • Starts with . or .. or a Title (Valid Title).

    • ./CS2103T/../CS2101 is a valid RelativePath.

Example

The picture below helps to illustrate the use of RelativePath and AbsolutePath

UGPathDiagram
Figure 4. Example to illustrate Path

The AbsolutePath /Workspace/CS2101 is equivalent to RelativePath ../CS2101

Thus open /Workspace/CS2101 and open ../CS2101 would yield the same result.

Paths are used by the open and delete command
The Root simply serves as a way for Notably to hierarchically organise your notes. It will not be visible to you while you are using the application.
You cannot delete the root note. e.g Delete ../.. is invalid. An error message will be displayed to remind you of this.

3.1. View help : help

If you can’t remember the commands or you are unsure about what a particular command does, type help and hit Enter. Figure 5 below shows you what this will look like on your screen.

Format: help

Help1
Figure 5. Demo for the help command

You will then see a Help window on your screen, as seen in Figure 4 below, which will include a summary of the commands and a link to Notably’s User Guide.

Help2
Figure 6. Demo for the help command (continued)

  • While the help modal is open, you can hold the Up and Down keys to scroll through it’s contents. This is a more efficient solution than using your mouse!

3.2. Exit the program: exit

If you’re done with taking notes, use exit to close Notably straight from the command line.

Format: exit

Exit
Figure 7. Demo for the exit command

3.3. Create a new note: new

If you want to add a new note (to the path of the currently open note), use the new command and specify the TITLE of the note.

Format: new -t TITLE [-o]

  • Don’t forget the -t flag!

  • The TITLE for the note MUST be specified.

  • The TITLE for the note can only contain alphabets, numbers, symbols (except / and -) and whitespaces.

  • The TITLE for the note cannot begin with whitespaces or the period . characer.

  • Duplicate notes are not allowed under the same note.

    • This is explained here

  • Use the optional -o flag to immediately open the note after creating it.

  • Leaving out the -o open flag can be useful if you want to create multiple notes quickly for future use, but you don’t need to edit them right away!

  • Want to save some time? Use the n shorthand instead of new

    • n -t TITLE [-o]

3.3.1. Creating duplicate notes

Creating duplicate notes are not allowed as mentioned 3.3. What are considered duplicate notes?

  • Two notes are considered duplicates IF their TITLEs are the same while ignore their case. For example:

    • Hello, hello, HELLO and HeLLo are considered duplicates

    • hello world!, helloworld! and helloworld@ are not considered duplicates, because whitespaces and allowed symbols are not ignored

  • Two notes are considered duplicate IF they have the same TITLE under the same note. This can be seen in the following diagrams below:

    PathDuplicates1
    Figure 8. INVALID as there are duplicate notes under /Workspace/CS2103
    PathDuplicates2
    Figure 9. VALID as they are not both directly under /Workspace/CS2103
    PathDuplicates3
    Figure 10. VALID as one exists in /Workspace/CS2103 and the other in /Workspace/CS2101

3.3.2. Example: Creating new notes

  1. Let’s first create a note (with a TITLE), and open it immediately after. Type this command:

    new -t Notably -o

  2. Due to the -o flag, the currently open note is now Notably (as seen in the sidebar). Let’s add a new note to the currently opened note, (Step 2) with a TITLE as follows:

    new -t CS2103T

    • Observe that the (Absolute) Path to the currently open note is now changed from /Workspace in step 1 to /Workspace/Notably in step 2.

      • Not sure where to see this path? Check it out here

      • Not sure what Absolute Paths are or why the new note is created in this way? Check it out here

  3. The new note CS2103T has been created successfully!

    • Observe that the note CS2103T was not opened immediately as seen in step 3

      • This is because the -o open flag was not specified, so the note CS2103T was created without opening it immediately.
New1
Figure 11. Step 1 - Create a new note with the title "Notably" (with the -o open flag)
New2
Figure 12. Step 2 - Create a new note with the title "CS2103T" (without the -o open flag)
New3
Figure 13. Step 3 - Final state after creating both notes

3.4. Open an existing note: open

You can open an existing note by specifying its absolute or relative path).

Format: open [-t] AbsolutePath/Relativepath

  • If you want to save some keypresses, omit the optional -t flag. It still works fine!

3.4.1. Example: Opening a note

  1. Let’s open the note Notably that exists in the currently opened note Workspace (Step 1) with the command:

    open -t Notably

  • Notably gives you some useful suggestions on other paths that are similar or related to your input!
Open
Figure 14. Step 1 - Demo for the open command (with suggestions)

3.5. Edit an existing note: edit

If you want to change the BODY content of the currently opened note, use the edit command. This command opens an editing window where you can update the existing BODY of the note.

Format: edit

3.5.1. Example: Editing the currently opened note

  1. As shown in Step 1, let’s update the BODY content of the currently opened note Workspace with the command:

    edit

  2. An Edit modal will appear on your screen, as shown in Step 2. You will now be able to edit the content of the currently open note.

  3. Once done, press Esc to close the modal. Any changes made to the content of the note are automatically saved when you do so.

Edit1
Figure 15. Step 1 - Demo for the edit command (Typing the edit command)
Edit2
Figure 16. Step 2 - Demo for the edit command (Interacting with the Edit modal)

  • Instead of editing a note in plain text, leverage Notably’s Markdown feature to better organise the text in your note!

  • You can copy and paste text in the edit modal, as per the conventional keyboard shortcuts CMD/CTRL + c and CMD/CTRL + v respectively.

  • You are not allowed to edit the root note, i.e when your currently opened path is "/"

3.6. Delete a note: delete

If you no longer need a note, or if you have accidentally created a wrong note, don’t worry! You can always delete that note.

Format: delete [-t] AbsolutePath/RelativePath

  • Requires prior understanding of AbsolutePath and RelativePath. You can refer here for an explanation

  • Deleting a note will also delete its child notes. Be very careful! You can refer to the example below for an illustration

  • Deleting the root note (i.e. delete /) is prohibited.

  • You can delete the currently open note using the command delete .

  • Want to save some time? Drop the optional -t flag and use the d shorthand instead of delete

    • d AbsolutePath/RelativePath

3.6.1. Example: Deleting a note under the currently open note

  1. Let’s delete the Notably note using this command:

    delete -t Notably

    • The currently open note is Workspace

    • The above example uses RelativePath. You can achieve the same result as above by using an AbsolutePath instead by executing delete -t /Workspace/Notably.

      • Not sure about AbsolutePath and RelativePath? You can refer here for a clearer explanation

  2. The note with the title Notably is deleted successfully since it exists!

    • Another Note, CS2103 and ST2334 are immediately deleted as well since they are notes under Notably
    Delete1
    Figure 17. Step 1 - Key in the example command
    Delete2
    Figure 18. Final state after deletion

3.6.2. Deleting the currently open note

  1. In this example, Notably is the currently open note. Let’s delete it using the command:

    delete .

    • The . in the command is a RelativePath that points to the path of the currently open note

  2. Notably note is deleted and the currently open note is now Workspace

    • This will change the currently open note to the deleted note’s parent note
    Delete3
    Figure 19. Step 1 - Key in the example command
    Delete2
    Figure 20. Final state after deletion

3.7. Find a note based on certain keywords: search

If you need to look for a note that contains a specific keyword in its content, use the search command and Notably will show you the search results sorted by the number of matches in the note. The note with the highest number of match will be at the top of the list, so that you can access it faster.
Format: search [-s] KEYWORD

  • search looks through all the notes that you have

  • Partial matches work as well! It means that when you have a set of notes containing the word "lecture" but no "lect" as a word on its own, you can just type search lect and Notably will still show you a list of notes containing the word "lecture", as "lect" is part of the word "lecture".

  • Matches are case insensitive, meaning it will find the word no matter if it is in uppercase or lowercase or even mixed-case

3.7.1. Example: Searching for the keyword "Computer science"

Let’s look for the keyword "Computer science" if it exists in any of the notes that you have saved in Notably.

search -s Computer science

If the word "Computer science" exists, a list of suggestions will be generated. This list will be sorted in descending order of the number of matches, i.e. the note with the highest number of matches will be at the top of the list, as seen in the figure below.

Search
Figure 21. Demo for the search command: keyword found

Let’s say the first option /Workspace/Notably/CS2103/Project is the note you are looking for. You may press ↓ and Enter to open the note. The figure below illustrates how the note chosen will be opened and the command line box is cleared.

Search1
Figure 22. Demo for the search command: open a note with the searched keyword

If the keyword you are looking for does not exist in any of your notes, no suggestions will be generated, as seen in the figure below.

Suggestions4
Figure 23. Demo for the search command: keyword not found

3.8. Save the data

Your notes are saved in the hard disk automatically after any command that changes the data. There is no need for you to save manually!

Also, your currently opened note and window size (of Notably) is also saved every time it changes so that you can continue where you left off the next time you start Notably!

3.9. Auto suggestions

As you type, Notably will provide you with suggestions. You can press the keyboard ↓ button followed by Enter to select any suggestion in the list.

For example, as you type open -t Notably, a list of suggestions will be generated as seen in the figure below.

Suggestions
Figure 24. Demo for the suggestions feature: Suggestions are generated as the user keys in his input

Let’s say you would like to choose the option /Workspace/Notably/Another Note. After pressing ↓ to reach that suggestion and pressing Enter, the command input line will be auto-filled by the suggestion, as seen in the figure below.

Suggestions2
Figure 25. Demo for the suggestions feature: The user input is auto-completed when the user selects a suggestion

If no suggestion list is generated for the command open, delete or search, it means the path, title, or keyword cannot be found anywhere in Notably, as seen in the figures below.

Suggestions3
Figure 26. Demo for the suggestions feature: The user inputs a path/ title that does not exist in his Notably app, thus no suggestion list is generated
Suggestions4
Figure 27. Demo for the suggestions feature: The user inputs a keyword that does not exist in any of his notes, thus no suggestion list is generated

3.9.1. (Coming in v2.0) Suggestion response text when opening or deleting a parent note

Variations of path with ../ (e.g. open ../, open Note/../Note, etc.) will not generate a comprehensive response text. Currently, typing open ../ will generate a response text of Open a note titled "../" instead of Open a parent note.

3.10. Auto correction

Notably will try its best to correct your mistypes automatically, as long as your mistyped inputs are not too far away from the understood commands. This provides you with a more fluid typing experience!

Notably’s auto correction feature works on two aspects of your typing:

  1. It auto corrects command names, where command names refers to open, search, delete, edit, and others. For example, Notably will correct the mistyped command name opne to open.

  2. It auto corrects the Paths of notes. For example, depending on the notes that exist in your database, Notably might correct /Notaby to /Notably.

See the example below for more information.

3.10.1. Example: Auto correcting user input

Even though the user types in the command name opne, Notably is still able to recognise this as an open command.
In addition, the inputted RelativePath Notaby is understood by Notably, even though there’s no note in the database with the title Notaby. Instead, there exists a note in the database with the RelativePath Notably.
After corrections are done, a list of suggestions will be generated as if the user has inputted open -t Notably!
Correction
Figure 28. Demo for the auto correction feature

3.11. Response text

Notably also displays a response text which enables you to understand the meaning of the input you type and shows an error message when your input is invalid.

For example, if you type open /CS, the response text will indicates that you are trying to Open a note titled "/CS", as seen in the figure below.

ResponseText1
Figure 29. Demo for the response text feature: open command

On the other hand, if you key in an invalid command, the response text will display an error message as seen in the figure below.

ResponseText2
Figure 30. Demo for the response text feature: invalid command

3.12. Markdown (GitHub Flavored Markdown)

We use the term Markdown and GitHub Flavored Markdown interchangably in this document.

Notably supports basic GitHub Flavored Markdown (GFM) as the BODY content of a note. By supporting Markdown, we hope to enhance your typing experience even further. You can simply type your note in Markdown, and it’ll take care of displaying the content of your note in a nice layout for you.

Currently supported syntax of GitHub Flavored Markdown in Notably consists of:

# Level 1 header
## Level 2 header
### Level 3 header
#### Level 4 header
##### Level 5 header
###### Level 6 header

  • Lists and List items

    Currently, only unordered lists are supported. In addition, only the hyphen - symbol is supported to be used as the list bullets.
    		 
- List item
- Another list item
  - A nested list item
    - A deeper nested list item
- Last list item
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Proin dictum accumsan nunc sed feugiat.

3.12.1. Example: Writing your note in Markdown

For example, you might write your note as follows:

# Hello Notably

Notably is for those who prefer to use a desktop app for managing notes.
More importantly, Notably 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).

## Getting started

- Ensure you have Java `11` or above installed in your Computer.
- Download the latest https://github.com/AY1920S2-CS2103T-W17-2/main/releases[notably.jar]
- Double-click the file to start the app. The Application should start in a few seconds.

3.12.2. (Coming in v2.0) More complete support of Markdown syntax

In our v2.0 release, we’ll be supporting the following additional Markdown syntax:

*This text will get italicised*
**This text will get bold**
~~This text will get a strikethrough treatment~~

The sidebar is where you can see your notes in a neatly organised way, reminiscent of a file browser in an Operating System.

  • The sidebar only shows up to 3 levels of notes at a single time.

    • The 3 levels will compromise of the:

      • currently open note and its siblings

      • its parent note

      • its children notes

    • This will be demonstrated in the following diagrams, with Workspace as the level 1 note

      • There is no level 0 note (root) that is displayed in the sidebar
Sidebar
Figure 31. Before and after opening a level 2 note
Sidebar2
Figure 32. Before and after opening a level 3 note

4. 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 Notably folder.

5. Command Summary

  • View help: help

  • Exit the program: exit

  • Create a new note: new -t TITLE [-o]

  • Open an existing note: open [-t] AbsolutePath/Relativepath

  • Opens an editing window to edit the currently opened note: edit

  • Delete a note: delete [-t] AbsolutePath/Relativepath

  • Find a note based on certain keywords: search [-s] KEYWORD