=========
Reference
=========
******
Launch
******
* Bundle types

  ME-Mydoc is distributed in two modes: platform independent and platform dependent.  The platform dependent package contains the JRE on that platform whereas independent package can be executed on any platform as long as JRE/JDK 8 is installed.  

* For platform dependent package, unzip it and execute corresponding launcher

  On Windows, launch :command:`mydoc.exe` or :command:`mydoc.bat`

  On Linux or Mac, launch :command:`mydoc.sh`.  Likely you need to invoke :command:`chmod +x mydoc.sh`.

* For platform independent package, an extra step of setting up java command into PATH is required

  On Windows, :command:`set PATH=<your java path>;%PATH%`
  
  On Linux or Mac, :command:`export PATH=<your java path>:$PATH`.  You may need to invoke :command:`chmod +x -R <jre folder>`.

*************
Configuration
*************

* Setup path on first use
.. image:: images/mydoc/mydoc-install.jpg
..

  By default, user can click :guilabel:`Install` button to proceed.  The directories will be created before the application starts.  User can also change one or all directories according to his need.

+----------------------+-----------------------------------------------------------------+
+ Note path            | directory where note files are stored                           |
+----------------------+-----------------------------------------------------------------+
| Doc path             | directory where document files are stored                       |
+----------------------+-----------------------------------------------------------------+
| Bookshelf path       | directory where book files are stored                           |
+----------------------+-----------------------------------------------------------------+
| Code path            | directory where code files are stored                           |
+----------------------+-----------------------------------------------------------------+
| Search cache path    | directory where search index caches are stored                  |
+----------------------+-----------------------------------------------------------------+
| Temp path            | directory where temporary files are stored                      |
+----------------------+-----------------------------------------------------------------+
| Trash path           | directory where deleted files are transferred to                |
+----------------------+-----------------------------------------------------------------+

*************
Search Window
*************
*  Global hot key that pops up/hides :guilabel:`Floating Search Window`

  :kbd:`Ctrl + Alt + O` : Show/Hide :guilabel:`Floating Search Window`


* Keys in text input of floating window

+---------------------------------------+-----------------------------------------------------------------+
| :kbd:`ESC`                            | Clear text if any.  Hide window if text is empty.               |
+---------------------------------------+-----------------------------------------------------------------+
| :kbd:`Arrow Down`                     | Goto result list if visible, or force to show result list.      |
+---------------------------------------+-----------------------------------------------------------------+
| :kbd:`Enter`                          | Launch first item in the result list.                           |
+---------------------------------------+-----------------------------------------------------------------+
| :kbd:`Double Click` an item           | Launch first item in the result list.                           |
+---------------------------------------+-----------------------------------------------------------------+
| :kbd:`Ctrl + Double Click` an item    | Show property window for the item.                              |
+---------------------------------------+-----------------------------------------------------------------+
| :kbd:`Ctrl + Enter` an item           | Show property window for the item.                              |
+---------------------------------------+-----------------------------------------------------------------+

******************
Search Query Rules
******************
* Use :kbd:`,` to separate AND conditions.  For example, **java,programming** searches all items whose title has both **java** and **programming**.
* Types can be specified.  Currently, there are following types. 

+------------+-----------+
| :kbd:`b:`  | Book      |
+------------+-----------+
| :kbd:`n:`  | Note      |
+------------+-----------+
| :kbd:`d:`  | Doc       |
+------------+-----------+
| :kbd:`c:`  | Code      |
+------------+-----------+
| :kbd:`t:`  | Tag       |
+------------+-----------+
  
  By default, items of only enabled types (in menu :menuselection:`View --> Doc`, :menuselection:`View --> Note`, :menuselection:`View --> Book`) are listed.

  For example, **java,security,b:** lists all books containing **java** and **security**.  It is also equivalent to **b:java,b:security** or **b:java,security**.
  
* Use **##** to specify full text search.  For example, **#java#** searches all entities having **java** in its content.  **d:#java#** searches Doc having **java** in its content.  Actually, the query string inside **##** follows Lucene query parser syntax.

* Multiple types are not valid except tag.  For example, **t:alg,b:math** searches all books that belong to any tag having substring of **alg** and whose title has substring of **math**.

***********
Manage Tags
***********
* All books, notes and docs can be tagged.

* Upon installation, there are pre-defined tags.  "Ebook" tag is for Book categories and "Programming Languages" is for Code feature.

*  User can of course create his own tags by right clicking a tag node
  
.. image:: images/mydoc/mydoc-tag-menu.jpg
..

  Note that deleting a tag requires no items are associated with the tag.


*********
Add a Doc
*********
* You can **drag and drop** a file from OS file manager to the :guilabel:`Floating Search Window` to create a new Doc or select menu  :menuselection:`File --> Add Doc` or press :kbd:`Ctrl + Alt + D` when main mydoc window is activated.

.. image:: images/mydoc/mydoc-new-doc.jpg

* Multiple files can be committed by clicking :guilabel:`Choose` button.

* Modify tags by clicking :guilabel:`edit` link in  :guilabel:`Tags` field

.. image:: images/mydoc/mydoc-tag.jpg

* :guilabel:`Published Time` follows format **YYYY**, or **YYYY-MM** or **YYYY-MM-DD**

* In case that an existing file to be committed is identified (md5 match), you are given a chance to cancel.  You can double click an item in the list and its property window is popped up.
.. image:: images/mydoc/mydoc-dup-doc.jpg


**********
Add a Note
**********

* There is a global hot key :kbd:`Ctrl + Alt + N` that triggers creating a new note

* There are 4 components in the note editing window.  On the right hand side is the source code view.  On the left hand side are property view, toolbar and html view respectively.
.. image:: images/mydoc/mydoc-note-src-editing.jpg

* User can toggle between a minimal mode and a normal mode.  In the minimal mode, only html view is displayed, providing user largest editing view.
.. image:: images/mydoc/mydoc-note-cross-ref.jpg
.. 
  
* Or normal mode with property and toolbar
.. image:: images/mydoc/mydoc-note-normal-mode.jpg
..

* Special toolbar buttons
.. image:: images/mydoc/mydoc-note-button.jpg
..

 They are described as below 

+----------------------------------------------+---------------------------------------------------------------+
| .. image:: images/mydoc/note_render_code.png | Switch to source editing mode.  Highlight source code         |
+----------------------------------------------+---------------------------------------------------------------+
| .. image:: images/mydoc/note_math_16.png     | Switch to source editing mode.  Render AsciiMath              |
+----------------------------------------------+---------------------------------------------------------------+
| .. image:: images/mydoc/note_full_16.png     | Switch to minimal mode                                        |
+----------------------------------------------+---------------------------------------------------------------+
| .. image:: images/mydoc/note_prop_16.png     | Toggle property area                                          |
+----------------------------------------------+---------------------------------------------------------------+
| .. image:: images/mydoc/note_src_16.png      | Toggle source editing area                                    |
+----------------------------------------------+---------------------------------------------------------------+
| .. image:: images/mydoc/note_link_16.png     | Convert selected text to a hyper link                         |
+----------------------------------------------+---------------------------------------------------------------+
| .. image:: images/mydoc/note_image_16.png    | Insert image link                                             |
+----------------------------------------------+---------------------------------------------------------------+
| .. image:: images/mydoc/note_code_16.png     | Convert selected text to code                                 |
+----------------------------------------------+---------------------------------------------------------------+
| .. image:: images/mydoc/note_sync_view_16.png| Sync html view with html source code ( left-> right)          |
+----------------------------------------------+---------------------------------------------------------------+
| .. image:: images/mydoc/note_refresh_16.png  | Refresh all views.                                            |
+----------------------------------------------+---------------------------------------------------------------+
| .. image:: images/mydoc/note_sync_src_16.png | Sync html source code with its view ( right-> left)           |
+----------------------------------------------+---------------------------------------------------------------+


* In html view, there are following shortcuts.

+------------------------------+--------------------------------------------------------------------------------------------+
| :kbd:`ESC`                   | Close the window and discard changes.  If the note is newly created, it's not saved at all.|
+------------------------------+--------------------------------------------------------------------------------------------+
| :kbd:`Alt + S`               | Save changes but keep window                                                               |
+------------------------------+--------------------------------------------------------------------------------------------+
| :kbd:`F2`                    | Switch minimal/full mode                                                                   |
+------------------------------+--------------------------------------------------------------------------------------------+
| :kbd:`F5`                    | Refresh                                                                                    |
+------------------------------+--------------------------------------------------------------------------------------------+
| :kbd:`F6`                    | Insert entity reference                                                                    |
+------------------------------+--------------------------------------------------------------------------------------------+
| :kbd:`F9`                    | Decrease font size                                                                         |
+------------------------------+--------------------------------------------------------------------------------------------+
| :kbd:`F10`                   | Increase font size                                                                         |
+------------------------------+--------------------------------------------------------------------------------------------+

* In html source editing view, there are following shortcuts.

+------------------+------------------------------------+
| :kbd:`Alt + S`   | Save changes and refresh html view |
+------------------+------------------------------------+
| :kbd:`F5`        | Refresh html view                  |
+------------------+------------------------------------+

* Entity Cross Reference
  The search input is triggered by :kbd:`F6`.  You can launch the entity referenced by clicking it.

.. image:: images/mydoc/mydoc-note-trigger-cross-ref.jpg
.. 

.. note::
  You need to refresh html view once link, image, or entity cross reference is inserted before clicking to launch it.

* Code highlighting and `AsciiMath`_ representation
.. _AsciiMath: http://asciimath.org
  
.. image:: images/mydoc/mydoc-note-render-math.jpg
.. image:: images/mydoc/mydoc-note-render-code.jpg
.. 

  You can mix both of them
.. image:: images/mydoc/mydoc-note-render-math-code.jpg
.. 
  
  The saved html node can be rendered by common web browser.

.. note::
  Once either of them is enabled, the html view becomes read only and you can only edit in html source editing view.



**********
Add a Code
**********
* A code entity can have multiple snippets associated with it.  Each snippet is just some text, highlighted in the editing view by a programming language specified.  
.. image:: images/mydoc/mydoc-code.jpg

* To create a new snippet, click :guilabel:`New` in :guilabel:`Snippets` field.

* By default, Java is the programming language for a newly created snippet.  To change it, click :guilabel:`edit` in :guilabel:`Languages` field.

.. image:: images/mydoc/mydoc-code-pl.jpg

* To activate a snippet, select :menuselection:`Snippets --> <the snippet>`.

.. image:: images/mydoc/mydoc-code-snippets.jpg

* To toggle property view, select :menuselection:`Config --> Show Property`.

* To change keymap, select :menuselection:`Config --> Default Keymap` or :menuselection:`Config --> Vim Keymap`

**********
Add a Book
**********
* To create a new Book,  follow menu  :menuselection:`File --> Add Book` or press :kbd:`Ctrl + Alt + B` when main mydoc window is activated.
.. image:: images/mydoc/mydoc-new-book.jpg

* In case that an existing book file to be committed is identified (md5 match), you are given a chance to cancel.  You can double click an item in the list and its property window is popped up.
.. image:: images/mydoc/mydoc-dup-book.jpg

* In the field :guilabel:`Title`, input in format **Title:Subtitle** so that title and subtitle can be recognized automatically.
.. image:: images/mydoc/mydoc-book-title.jpg
.. 

  Double clicking an existing title, you can tweak other parts.  To delete one, select and press :kbd:`DEL`.
.. image:: images/mydoc/mydoc-book-title-detail.jpg
.. 

* In :guilabel:`Tag` list, double clicking the blank line brings up :guilabel:`Select Tags` window.  :guilabel:`Switch to All Tags` switches to all-tag tree.  Double click a tag in list and the candidate tag is removed. 
.. image:: images/mydoc/mydoc-tag-book.jpg

* In :guilabel:`Authors` field, input full name and its first name, middle name and last name are parsed.  If an author with same first name and last name exist, :guilabel:`Select an existing author` dialog is popped up.  Clicking :guilabel:`Cancel` creates a new author,  
.. image:: images/mydoc/mydoc-author-select.jpg

* If you want to have a deep search of existing author, click :guilabel:`Select Existing`.
.. image:: images/mydoc/mydoc-author-window.jpg

* :guilabel:`Published Date` follows format **YYYY**, or **YYYY-MM** or **YYYY-MM-DD**

* In :guilabel:`Publishers` list, double clicking the blank line brings up :guilabel:`Select Publishers` window.
.. image:: images/mydoc/mydoc-publisher-filter.jpg

* To add new publishers, select :menuselection:`Edit --> Publishers` 
.. image:: images/mydoc/mydoc-publisher-window.jpg

* A Book item can comprise more than one files.  Press :guilabel:`Add Files` to add more.

***********************
Search Hit Highlighting
***********************
.. image:: images/mydoc/mydoc-highlighter.png
.. 

************
View Control
************
  In menu :menuselection:`View`, there are options described below

.. image:: images/mydoc/mydoc-view-menu.jpg
..

+-----------------------------------------+-------------------------------------------------------------------------------------+
| :menuselection:`View --> Show Tag`      | Show items only associated with selected tag                                        |
+-----------------------------------------+-------------------------------------------------------------------------------------+
| :menuselection:`View --> Show Sub Tags` | Show items that belong to any decendents of the selected tag                        |
+-----------------------------------------+-------------------------------------------------------------------------------------+
| :menuselection:`View --> Show Favourite`| Show favourite items.  Note changing tag will not change                            |
+-----------------------------------------+-------------------------------------------------------------------------------------+
| :menuselection:`View --> Show No Tag`   | Show items that do not have any tag                                                 |
+-----------------------------------------+-------------------------------------------------------------------------------------+
| :menuselection:`View --> Show All`      | Show all items                                                                      |
+-----------------------------------------+-------------------------------------------------------------------------------------+
| :menuselection:`View --> Doc`           | Show Doc items.  Also controls items listed in :guilabel:`Floating Search Window`   |
+-----------------------------------------+-------------------------------------------------------------------------------------+
| :menuselection:`View --> Note`          | Show Note items.  Also controls items listed in :guilabel:`Floating Search Window`  |
+-----------------------------------------+-------------------------------------------------------------------------------------+
| :menuselection:`View --> Book`          | Show Note items.  Also controls items listed in :guilabel:`Floating Search Window`  |
+-----------------------------------------+-------------------------------------------------------------------------------------+
| :menuselection:`View --> Code`          | Show Code items.  Also controls items listed in :guilabel:`Floating Search Window`  |
+-----------------------------------------+-------------------------------------------------------------------------------------+

*******
Options
*******
.. image:: images/mydoc/mydoc-option.jpg
..

* :guilabel:`Enable Full Text Search` : When enabled, new entities will be indexed once managed.  It triggers indexing confirmation dialog, allowing user to perform full indexing or incremental indexing immediately.
.. image:: images/mydoc/mydoc-dialog-index-option.jpg
..

* :guilabel:`Copy before opening` : When selected, the launched Doc will be copied to temp directory configured by user and then default program is invoked to open the shadow file, in order to avoid damage to the file.

* :guilabel:`Show hidden` : Users can mark hidden property of Doc or Note so that they will not be listed in main window or floating search window if :guilabel:`Show hidden` is disabled.

* :guilabel:`Move to Trash` : When enabled, deleted items are moved to trash folder in stead of vanishing completely.

***********
Launch item
***********

* Opening an item can be triggered by pressing :kbd:`Enter` or :kbd:`Double Click` an item in either search popup list or main window list.

* Property window can be triggered by pressing :kbd:`Ctrl + Enter` or :kbd:`Ctrl + Double Click` an item in either search popup list or main window list.

* Doc property window
.. image:: images/mydoc/mydoc-doc-property.jpg

* Note property window
.. image:: images/mydoc/mydoc-note-property.jpg

* Book property window
.. image:: images/mydoc/mydoc-book-property.jpg
..

  Double clicking a file in :guilabel:`Files` list launches the book file.

****
Misc
****

* Favourite

  Items can be added into favourite list by selecting menu item :menuselection:`Action --> Favourite`


* Deleting items

  Items can be deleted by selecting :menuselection:`Action --> Delete`.  The deleted items are moved to trash directory if configured by user.
  
* Enlarge floating search input
  
  Drag floating search window right edge, the input will be enlarged or shrinked accordingly.

