= Anakin - User Guide
:site-section: UserGuide
:toc:
:toc-title:
:toc-placement: preamble
:sectnums:
:imagesDir: images
:stylesDir: stylesheets
:xrefstyle: full
:experimental:
ifdef::env-github[]
:tip-caption: :bulb:
:note-caption: :information_source:
endif::[]
:repoURL: https://github.com/CS2103-AY1819S1-T09-2/main

By: `Team T09-2`      Since: `Aug 2018`      Licence: `MIT`

== Introduction
Welcome to the *Anakin* User Guide!

*Anakin*  was built for those who *want to make heavy use of flashcards without the hassle of managing physical copies*. More importantly, Anakin 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).

Anakin started from our desire to help users organize their flashcards better, and to reduce the paper waste generated by flashcards. As students ourselves, we believe that studying should be effective and easy to plan. Thus, we have built
in a scheduling system into Anakin which will help you plan out when to review your flashcards for optimal studying performance. Our scheduler uses spaced repetition which is the result of years
of https://www.supermemo.com/help/smalg.htm[psychology research]. Spaced repetiton embodies the idea that last minute studying has little effect. Instead, study sessions should be spread out to allow a student to best absorb infromation.

With this studying tool, we hope to not just decrease paper wastage but also to create a fun environment which can help students sustain their motivation to study
throughout the semester.

To get started, head over to <<Quick Start>>!

For a quick review of commands, check out <<Command Summary>>.
== How to Use This Guide
This document is designed for users with varying levels of proficiency. Most command in the guide can be read standalone, but there are
occasional references to other related commands.

To assist you, we have added sample use cases of each command in the document

//tag::quickStart[]
== Quick Start

.  Ensure you have Java version `9` or later installed in your Computer.
.  Download the latest `Anakin.jar` link:{repoURL}/releases[here].
.  Copy the file to the folder you want to use as the home folder for your copy of Anakin.
.  Double-click the file to start the app. The GUI should appear in a few seconds.
+
image::Ui.png[width="790"]
+
.  Type the command in the command box and press kbd:[Enter] to execute it. +
e.g. typing *`help`* and pressing kbd:[Enter] will open the help window.
.  Some example commands you can try:

* *`list`* : lists all decks
* **`newdeck`** : creates a new deck.
* **`delete`**`3` : deletes the 3rd deck shown in the current list
* *`exit`* : exits the app

Refer to <<Features>> for more details on the available commands.
//end::quickStart[]
[[Features]]
== Features

====
*Command Format*

* Words in `UPPER_CASE` are the parameters to be supplied by the user e.g. in `newdeck n/NAME`, `NAME` is a parameter which can be used as `newdeck n/John Doe`.
* Items in square brackets are optional e.g `newdeck [n/NAME]` can be used as `newdeck n/My Deck` or as `newdeck`.
* Optional items separated by - e.g. `editdeck 1 [q/Question?]-[a/Answer]` denote that at least one of the optional
 parameters are needed minimally to execute the command.
* Parameters can be in any order e.g. if the command specifies `q/QUESTION a/ANSWER`, `a/ANSWER q/QUESTION` is also acceptable.
====

=== Viewing help : `help`

Lists all available commands and their respective formats. +
Format: `help`

=== Lists all decks (or all cards) : `list`

Displays a list of all available decks. If inside a deck displays all cards in that deck. +
Format: `list`


=== Navigating into a deck : `cd`
To enter a deck identified by the INDEX_OF_DECK in the visible deck list. +
Format: `cd INDEX_OF_DECK`

****
* Enters the deck at the specified `INDEX_OF_DECK`.
* INDEX_OF_DECK must be a positive integer from 1 onwards and is based on the currently displayed list.
****

Examples:

* `cd 2` +
Enter the 2nd deck in the currently displayed deck list.

****
* Note: User can `cd` into another deck while being inside a deck.
****

=== Navigating out of the current deck : `cd ..`
Exit the current deck and returns the user to the list of decks. +
Format: `cd ..`

Examples:

* `cd 1` +
 `cd ..` +
Enter the 1st deck in the currently displayed deck list.
then return back to the Anakin's deck list (get out of the 1st deck)

// tag::newdeck[]
=== Adding a deck: `newdeck`

Adds a new deck with the given name to Anakin +
Format: `newdeck n/NAME`

****
* This deck will contains an empty list of cards.
* This operation is disabled when user is currently inside a deck.
* If multiple arguments are given (i.e. `newdeck n/My First Deck n/My Second Deck` only the last valid argument is accepted for each respective field.
* User should be under Anakin's deck list to perform this operation (not inside any decks).
****

Examples:

* `newdeck n/My First Deck`
// end::newdeck[]

=== Editing the name of a deck : `editdeck`

Edits the name of the deck at the specified index in the list. +
Format: `editdeck INDEX_OF_DECK n/NAME`

****
* INDEX_OF_DECK must be a positive integer from 1 onwards and is based on the currently displayed list.
* The new deck will maintain the card list of the old one.
* This operation is disabled when user navigates into a deck.
* If multiple arguments are given (i.e. `editdeck 1 n/My First Deck n/My Second Deck` only the last valid argument is accepted for each respective field.
* User should be under Anakin's deck list to perform this operation (not inside any decks).
****

Examples:

* `editdeck 1 n/My Deck` +
Edits the name of the first deck in the list to be `My Deck` and keeps the card list intact.

=== Deleting a deck : `deldeck`

Deletes the specified deck from Anakin. +
Format: `deldeck INDEX_OF_DECK`

****
* Deletes the deck at the specified `INDEX_OF_DECK`.
* `INDEX_OF_DECK` must be a positive integer from 1 onwards and is based on the currently displayed list.
* User should be under Anakin's deck list to perform this operation (not inside any decks).
****

Examples:

* `list` +
`deldeck 2` +
Deletes the 2nd deck that appears in the currently displayed list of decks.

// tag::newcard[]
=== Adding a card : `newcard`

Add a new card with given question and answer to the current card list. +
Format: `newcard q/QUESTION a/ANSWER`

****
* `q/QUESTION` and `a/ANSWER` can be in any order.
* User should be inside a deck to perform this operation.
****

Examples:

* `newcard q/Who are you? a/I'm Batman`
* `newcard a/Ding ding ding q/What does the fox say?`

// end::newcard[]

// tag::editcard[]
=== Editing a card : `editcard`

When user is inside a deck, edits an existing card at the specified index.If multiple arguments are given for question or answer, only the last valid argument is accepted for each respective field +
Format: `editcard INDEX_OF_CARD [q/QUESTION]-[a/ANSWER]`

****
* Edits the card at the specified INDEX_OF_CARD inside the deck. The index refers to the index number shown in the list of displayed cards. The index must be a positive integer e.g. 1,2,3.
* Existing values will be updated to the input values.
* If any of 2 fields: [q/QUESTION] [a/ANSWER] is left empty, the old value for that field will be retained
* At least one of the optional fields must be provided.
* User should be inside a deck to perform this operation.
****

Examples:

* `editcard 1 a/New Answer` +
Edits the answer of the first card in the current card list to be "New Answer". If multiple arguments are given for question or answer, only the last valid argument is accepted for each respective field.
// end::editcard[]

=== Deleting a card : `delcard`

When user is inside a deck, deletes the existing card at the specified index. +
Format: `delcard INDEX_OF_CARD`

****
* Deletes the card at the specified `INDEX_OF_CARD`.
* INDEX_OF_CARD must be a positive integer from 1 onwards and is based on the currently displayed list.
* User should be inside a deck to perform this operation.
****

Examples:

* `cd 1` +
`delcard 2` +
Get into the first deck then deletes the 2nd card that appears in the card list.

// tag::review[]
=== Review the cards in a deck : `review`
Starts a review of the deck specified. +
Format: `review INDEX_OF_DECK`

****
* INDEX_OF_DECK must be a positive integer from 1 onwards and is based on the currently displayed list.
* While in review mode, disable commands that operate on decks and cards (except: `endreview`,
`flipcard`, ``nextcard, `prevcard`, `help`, `history`, `exit`).
* The application's data will only be stored after execute `endreview` command.
****

=== Flip a card in a review : `flipcard`
View the flipside of the current card during a review. +
Format: `flipcard`

Examples:

* `review 1` +
`flipcard` +
`flipcard` +
Reviews the first deck on the list. You will see the first question card. Upon first `flipcard`, you will see the
answer on the back of the card. When you execute `flipcard` again, you will see the question card once more.

=== Go to the next card in a review : `nextcard`
Views the subsequent card in the deck. +
Format: `nextcard`

****
* Note: When you are at the last card of the deck, executing `nextcard` will loop back to the first card.
****

=== Go to the previous card in a review : `prevcard`
Views the previous card in the deck. +
Format: `prevcard`

****
* Note: When you are at the first card of the deck, executing `prevcard` will loop back to the last card.
****

=== Exit review mode : `endreview`
Exits the review and returns to the editing menu +
Format: `endreview`

****
* Note: Executing `undo` after reviewing will undo all the changes made in that review session
(all `classify` commands).
****

// end::review[]

=== Card difficulty classification : `classify`
Allocates a difficulty (easy, normal, hard) to the card currently being reviewed. +
This indicates how you felt about the difficulty of the card, relative to your performance. This rating will be taken
into consideration when scheduling cards for review. For example, a card rated `easy` will show up less often compared
to a card rated `hard`. +
Format: `classify DIFFICULTY`

****
* The *DIFFICULTY* parameter should be one of the strings: {`easy`, `normal`, `hard`}
* The *DIFFICULTY* parameter is case-insensitive
* By default, cards are assigned a `normal` difficulty
****

*Example*

1.  You decide to review a deck.
+
image::classifyExample1.png[width="500"]

2. You encounter a difficult question. You would like to document this for future revision. Simply type in
`classify`, followed by the desired difficulty (in this case, `hard`).
+
image::classifyExample2.png[width="500"]
+
image::classifyExample3.png[width="500"]

3. Upon ending the review, you should be able to see the updated difficulty classification on your cards.
+
image::classifyExample4.png[width="500"]

// tag::sort[]
=== Sort : `sort`
Sort the current list in lexicographical order.

* If user is currently inside a deck, sort all cards according to their question. +
* If user is not in a deck, sort all decks according to the their name. +

Format: `sort`

// end::sort[]

// tag::showDue[]
=== Show cards that should be reviewed on a particular date : `showDue` [coming in v1.4]
Show cards due on a particular date

* Shows the cards which require a review for a particular date based on past card performance. +

Format: `showDue c/10 m/12 y/14`
****
* Note: User must be inside a deck to perform this command.
* The above command will display the cards due on the 10th December, 2014. If no arguments are given for date
* If no day, month or year is given, showDue will default to showing the cards due for today
****
// end::showDue[]

// tag::find[]
=== Search for a deck or card : `find`

Search decks by names or cards by questions.

* If user is currently in a deck, find all cards which contain the specific keywords.

* If user is not in a deck, find decks.

Format: `find KEYWORD [MORE_KEYWORDS]…`

****
* The search is case insensitive. e.g `hans` will match `Hans`
* The order of the keywords does not matter. e.g. `Hans Bo` will match `Bo Hans`
* Only the name of the deck or the question of the card is searched.
* Decks or cards matching at least one keyword will be returned
(i.e. `OR` search). e.g. `Hans Bo` will return `Hans Gruber`, `Bo Yang`
* If user inputs 1 keyword, partial word will be matched. e.g 'Han' will match `Hans'
* If user inputs multiple keywords, only full words will be matched
e.g. 'Han Solo' will match 'Han non-solo' but will not match 'Hans Soooolo'
****

Examples:

* `find Algo` +
Returns `algo` and `Easy Algo`
* User is not inside any decks:
** `find Bio Chem Physics` +
Returns any decks containing `Bio`, `Chem`, or `Physics` in their name.
** `find insert` +
  Returns `insert`, `inserted`, `inserting` or any decks of which name contains these words.
* User is inside a deck: `find John Snow` +
Returns any cards containing `John` or `Snow` in their questions.
// end::find[]

// tag::importexport[]
=== Export deck to xml file : `export`
To create an `xml` file of the deck at INDEX_OF_DECK. +
Format: `export INDEX_OF_DECK`

****
* INDEX_OF_DECK must be a positive integer from 1 onwards and is based on the currently displayed list.
* This operation is disabled when user navigates into a deck.
* The xml file will be created in the same directory as the Anakin.jar file.
****

Example:

* 1. First, display all the decks in Anakin using `list`. +

image::exportScreenshot1.png[width="500"]

* 2. Say you want to export "Geography" (the 3rd deck), simply enter the command: `export 3`. You should see the following message: +

image::exportScreenshot2.png[width="500"]

"Geography.xml" will be created in the same directory as the Anakin.jar file. +

image::exportScreenshot3.png[width="300"]

=== Import deck from xml file : `import`
To import a deck from the `xml` file at the specified FILEPATH. +
Format: `import FILEPATH`

****
* You must include the filename of the target file in `FILEPATH`.
* This operation is disabled when you navigate into a deck.
* The default base directory is the same directory as the Anakin.jar file.
****

Examples:

Say you want to import a deck called "Geography" and you have the `Geography.xml` file in the same directory as Anakin.jar. +

image::exportScreenshot3.png[width="300"]

* Simply  enter `import Geography.xml` +

Before:

image::importScreenshot1.png[width="500"]

After:

image::importScreenshot2.png[width="500"]

Anakin imports the deck "My Deck" if it is in the same directory as the Anakin.jar file.
* `import C:/Users/Admin/Desktop/My Deck2.xml` +
Anakin imports the deck "My Deck2".

// end::importexport[]

=== Listing entered commands : `history`

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

[NOTE]
====
Pressing the kbd:[&uarr;] and kbd:[&darr;] arrows will display the previous and next input respectively in the command box.
====

// tag::undoredo[]
=== Undoing previous command : `undo`

Restores Anakin to the state before the previous _undoable_ command was executed. +
Format: `undo`

[NOTE]
====
Undoable commands: those commands that modify the state of Anakin.
(`newdeck`, `editdeck`, `deldeck`, `newcard`, `editcard`, `delcard`,
`sort`, `classify`, `cd`, `cd ..`).
====

Examples:

* `deldeck 1` +
`undo` (reverses the `deldeck 1` command) +

* `history` +
`undo` +
The `undo` command fails as there are no undoable commands executed previously.

* `deldeck 1` +
`clear` +
`undo` (reverses the `clear` command) +
`undo` (reverses the `deldeck 1` command) +

=== Redoing the previously undone command : `redo`

Reverses the most recent `undo` command. +
Format: `redo`

Examples:

* `deldeck 1` +
`undo` (reverses the `deldeck 1` command) +
`redo` (reapplies the `deldeck 1` command) +

* `delcard 1` +
`redo` +
The `redo` command fails as there are no `undo` commands executed previously.

* `delcard 1` +
`clear` +
`undo` (reverses the `clear` command) +
`undo` (reverses the `delcard 1` command) +
`redo` (reapplies the `delcard 1` command) +
`redo` (reapplies the `clear` command) +
// end::undoredo[]

=== Clearing all entries : `clear`
Clears all entries from Anakin. +
Format: `clear`


=== Exiting Anakin : `exit`
Exits the program. +
Format: `exit`

// start::autocompletion[]
=== Autocompletion : Hit `<TAB>`

Provides autocompletion for existing text. If there is an available autocompletion for the text in the textbox then hitting <TAB> will replace the text in the command box with the autocompletion text of the existing command
which is lexicographically closest to what is in the text box. If the command box is empty autocompletion will default to ``cd 1``. Unfortunately, this feature does not work with trailing or preceeding whitespace currently.

// end::autocompletion[]


== FAQ

*Q*: How do I transfer my data to another Computer? +
*A*: Export all your decks, copy the .xml files to the other Computer, then use the import command to import your decks.

*Q*: Why is it called *Anakin*? +
*A*: Because using CLI is as cool and mysterious as using the Force.

//tag::cmdsummary[]
== Command Summary

A convenient cheat sheet of commands

[width="100%",cols="20%,<30%",options="header",]
|=======================================================================
|Command | What does it do?
|`help` | Lists all available commands and their respective formats.
|`list` | Displays a list of all available decks. If inside a deck displays all cards in that deck.
|`cd INDEX` | Navigates into the deck at INDEX. +
Use `cd ..` to navigate out of the deck.
|`newdeck n/NAME` | Adds a new deck.
|`editdeck INDEX n/NAME` | Edits the name of the deck at INDEX.
|`deldeck INDEX` | Deletes the deck at INDEX.
|`newcard q/QUESTION a/ANSWER` | Adds a new card in the current deck. +
You must be inside a deck to perform this operation.
|`editcard INDEX [q/QUESTION]-[a/ANSWER]` | Edits the details of the card at INDEX. +
At least one parameter must be present. +
You must be inside a deck to perform this operation.
|`delcard INDEX` | Deletes the card at INDEX. +
You must be inside a deck to perform this operation.
|`review INDEX` | Review the cards of the deck at INDEX.
|`flipcard` | View the flipside of the current card during a review.
|`nextcard` | Views the subsequent card in the deck.
|`prevcard` | Views the previous card in the deck.
|`endreview` | Exits the review.
|`classify DIFFICULTY` | Classifies the current card into one of the following categories: {‘easy’, ‘normal' , ‘hard’}
|`sort` | Sorts the displayed list of decks by name. +
When you are inside a deck, sorts the displayed list of cards by question.
//|`rank` | Sort the list of cards by performance
|`find KEYWORD [MORE_KEYWORDS]...` | Finds decks with names that contain any of the given keywords. +
When you are inside a deck, finds cards with questions that contain any of the given keywords.
|`export INDEX` | Exports the deck at the specified INDEX. (Default location is the same folder as Anakin)
|`import FILEPATH` | Imports a deck from the `xml` file at the specified FILEPATH.
|`history` | List all entered commands in reverse chronological order.
|`undo` | Undo previous command.
|`redo` | Redo previously undone command.
|`clear` | Clear all decks and cards.
|`exit` | Exits the program.

|=======================================================================
//end::cmdsummary[]
