From bb6ccf155d7552f16720c50460b6e104c51aa2b8 Mon Sep 17 00:00:00 2001 From: Titus Chew <39845485+tituschewxj@users.noreply.github.com> Date: Mon, 8 Apr 2024 21:46:48 +0800 Subject: [PATCH 1/3] Fix autocomplete docs Let's * Tweak image sizes * Update keyboard format macro * Add more stuff in UG for autocomplete * Add icon for autocomplete --- docs/UserGuide.md | 121 ++++++++++++++++++++++++++++---------- docs/_markbind/_macros.nj | 5 ++ 2 files changed, 96 insertions(+), 30 deletions(-) diff --git a/docs/UserGuide.md b/docs/UserGuide.md index a643163567a..16e17270e32 100644 --- a/docs/UserGuide.md +++ b/docs/UserGuide.md @@ -3,9 +3,9 @@ title: "User Guide" pageNav: 3 --- +{% import "_markbind/_macros.nj" as macros %} # TAPro User Guide - TAPro is a **Contact Book application** that is made for Computer Science Tutors for managing their students contact and attendance details. TAPro is optimized for use via a **Command Line Interface** (CLI) while still having the benefits of a Graphical User Interface (GUI). @@ -43,12 +43,12 @@ The latest version is compatible with older versions. A GUI similar to the below image should appear in a few seconds. Note how the app contains some sample data. -Main Window UI on first launch +Main Window UI on first launch
-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 window. +5. Type the command in the command box and press {{ macros.keyFormat('Enter') }} to execute it. e.g. typing **`help`** and pressing {{ macros.keyFormat('Enter') }} will open the help window. @@ -159,9 +159,9 @@ The help window is resizable, so you can **easily reposition and resize** it to **Switching quickly between the help and main window:** -* On Windows and most Linux distributions, you can use the keyboard shortcut: Alt + Tab, to switch between windows quickly. +* On Windows and most Linux distributions, you can use the keyboard shortcut: {{ macros.keyFormat('Alt') }} + {{ macros.keyFormat('Tab') }}, to switch between windows quickly. -* On macOS, you can use the keyboard shortcut: Cmd⌘ + Tab, to switch between windows quickly. +* On macOS, you can use the keyboard shortcut: {{ macros.keyFormat('Cmd⌘') }} + {{ macros.keyFormat('Tab') }}, to switch between windows quickly. @@ -314,7 +314,7 @@ Format: `find KEYWORD [MORE_KEYWORDS]` #g#Example:## `find alex david` returns `Alex Yeoh`, `David Li`, as seen in the image below. -result for 'find alex david +result for 'find alex david @@ -386,46 +386,109 @@ Format: `exit` ### Autocomplete -Autocompletes a word or a set of words, based on the current input. +The autocomplete feature autocompletes a parameter or command, based on the current command box input and the current data in TAPro. This means that if an attribute value is not present, it will not be present in the autocompletion of that corresponding parameter. - +{{ macros.definitionBox('Autocompletion', 'The autocomplete feature\'s suggested autocomplete result(s).') }} + +We can autocomplete both command names and parameters after their prefixes by pressing {{ macros.keyFormat('Tab') }}, when an autocompletion is available. -**Autocomplete doesn't work on week number:** + -This is because week number is short, -and it is much faster just typing out the number. +**Autocompletes the first word as a command name:** +The first word, will be autocompleted as a command name, instead of a parameter, if an autocompletion can be found for the current word that is in the command box input. + + +The command input box must not be empty for autocomplete to work. - + #g#Example:## -We have three students with NUSNet IDs `e0123456`, `e1234567` and `e2345678`. -If we type `mark nn/` into the command input box and press Tab, -we can see that the text in the command input box autocompletes to become `mark nn/e01234567`. +If we type `a` into the command input box and press {{ macros.keyFormat('Tab') }}, we see that the text in the command input box autocompletes to become `addstu`. -Pressing Tab again, causes the text to update to `mark nn/e1234567`, -followed by `mark nn/e2345678`. +The last parameter `TAG` is autocompleted. + - + + +**Autocompletes the last parameter in the input:** + +Autocomplete works on the last parameter (if any) in the command box, which is the text directly after a recognized prefix. + + +A parameter can only be autocompleted if it is not the first word, and has a recognized prefix. + -**Using autocomplete to scroll through all possible autocomplete suggestions:** + -Autocomplete will scroll through all possible options, based on the existing data in your contact list. +#g#Example:## + +We have some students in TAPro, such that the first tag alphabetically is `friends`. +If we type `edit 1 n/John Doe t/` into the command input box and press {{ macros.keyFormat('Tab') }}, +we see that the text in the command input box autocompletes to become `edit 1 n/John Doe t/friends`. + +The last parameter `TAG` is autocompleted. + + + + -When reaching the end of the possible options list, pressing -Tab will wrap +**Autocomplete scrolls through all autocompletions:** + +Autocomplete will scroll through all possible suggestions, based on the existing data in your contact list. + +When reaching the end of the all possible suggestions, pressing {{ macros.keyFormat('Tab') }} will wrap the possible options back to the start of that list again. + + + +#g#Example:## + +We have three students with NUSNet IDs `E0123456`, `E1234567` and `E2345678`. +If we type `mark nn/` into the command input box and press {{ macros.keyFormat('Tab') }}, +we can see that the text in the command input box autocompletes to become `mark nn/E0123456`. + +Every press of {{ macros.keyFormat('Tab') }}, causes the command input box text to update to the next autocompletion: +* from `mark nn/E0123456` to `mark nn/E1234567`, +* then to `mark nn/E2345678`, +* and then back to `mark nn/E0123456`. + - + + +**Autocomplete does not work on week number.** This is because `WEEK` is at most two digits, so it is much faster just typing out the number. + -**Sorted autocomplete suggestions:** + + +**Sorted autocompletions:** + +The autocompletions will be listed in [ASCIIbetical order](https://en.wikipedia.org/wiki/ASCII#Character_order), which is when all uppercase letters come before lowercase letter, and digits and most punctuations come before letters. + + + +#g#Example:## +If we have only the following tags in our contact list: `abc`, `123` `BCD`, `234`, `bcd`, autocompleting a `TAG` will give autocompletions in this order: `123`, `234` `BCD`, `abc`, `bcd`. -The autocomplete suggestions will be listed in alphabetical order, meaning if you have two possible options -`abc` and `abd`, autocomplete will give `abc` before `abd`. + + + + + +**Quickly clear an attribute with autocomplete:** + +We can autocomplete the placeholder value, if it is present for that parameter in our contact list. When a placeholder value is inputted as the parameter, it means that attribute for that student will be reset, after entering the command. + + + +#g#Example:## + +If the placeholder for the `MAJOR` parameter, `Major not provided`, is present in the contact list, then in the autocompletion for the `MAJOR` parameter, the value `Major not provided` is available. + --- @@ -434,9 +497,7 @@ The autocomplete suggestions will be listed in alphabetical order, meaning if yo ### Retrieving command history -TAPro saves successful commands input, so you can retrieve them later, using the -Up and -Down keys. +TAPro saves successful commands input, so you can retrieve them later, using the {{ macros.keyFormat('Up') }} and {{ macros.keyFormat('Down') }} keys. @@ -444,7 +505,7 @@ TAPro saves successful commands input, so you can retrieve them later, using the We have entered `mark nn/e0123456` as the previous command, and it was successful. Now the command input box is empty. -Pressing Up will update the text in the command input box to +Pressing {{ macros.keyFormat('Up') }} will update the text in the command input box to the previous command `mark nn/e0123456`. diff --git a/docs/_markbind/_macros.nj b/docs/_markbind/_macros.nj index f73737ff964..85cc568a1a7 100644 --- a/docs/_markbind/_macros.nj +++ b/docs/_markbind/_macros.nj @@ -12,3 +12,8 @@ {% endmacro %} + + + +{# Keyboard key formatting #} +{% macro keyFormat(name) %}{{ name }}{% endmacro %} From 656a6b11e396d2f2c6618289be853ec27dbf1c17 Mon Sep 17 00:00:00 2001 From: Titus Chew <39845485+tituschewxj@users.noreply.github.com> Date: Mon, 8 Apr 2024 21:53:03 +0800 Subject: [PATCH 2/3] Add page break --- docs/UserGuide.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/UserGuide.md b/docs/UserGuide.md index 16e17270e32..a48a9c53563 100644 --- a/docs/UserGuide.md +++ b/docs/UserGuide.md @@ -433,6 +433,7 @@ we see that the text in the command input box autocompletes to become `edit 1 n/ The last parameter `TAG` is autocompleted. +
From 9b179b46f73162c9429fc9d8cfabdc12608f0196 Mon Sep 17 00:00:00 2001 From: Titus Chew <39845485+tituschewxj@users.noreply.github.com> Date: Wed, 10 Apr 2024 12:04:44 +0800 Subject: [PATCH 3/3] Allow keyFormat to support icon --- docs/_markbind/_macros.nj | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/_markbind/_macros.nj b/docs/_markbind/_macros.nj index 85cc568a1a7..cb5f5474438 100644 --- a/docs/_markbind/_macros.nj +++ b/docs/_markbind/_macros.nj @@ -16,4 +16,4 @@ {# Keyboard key formatting #} -{% macro keyFormat(name) %}{{ name }}{% endmacro %} +{% macro keyFormat(name, icon='') %}{% if icon %}{{ icon }} {% endif %}{{ name | upper }}{% endmacro %}