Merge pull request #23 from ChrisHal/more_documentation

improved documentation

Author: ChrisHal

.gitignore

@@ -7,7 +7,6 @@
 /QtPMBrowser/release
 /.qmake.stash
 ui_*.h
-QtPMbrowser.pro.user.459d117
 GeneratedFiles/
 Makefile
 moc_*
@@ -22,9 +21,9 @@ QtPMbrowser.aps
 doc/_build/
 doc/doxy_html/
 QtPMbrowser/release/
-QtPMbrowser/QtPMbrowser.pro.user.e316ca4
-build-QtPMbrowser-Desktop_Qt_5_15_2_clang_64bit-Debug/
-build-QtPMbrowser-Desktop_Qt_5_15_2_clang_64bit-Release/
+.DS_Store
+out
+QtPMbrowser/.qmake.stash
 .DS_Store
 *.pro.user
 QtPMbrowser/QtPMbrowser.pro.user

QtPMbrowser/DlgTreeFilter.ui

@@ -35,13 +35,20 @@
      <x>10</x>
      <y>10</y>
      <width>211</width>
-     <height>61</height>
+     <height>71</height>
     </rect>
    </property>
    <property name="text">
-    <string>Enter filter as Perl-style
-regular expression.
-&quot;.*&quot; selects all.</string>
+    <string>&lt;html&gt;&lt;head/&gt;&lt;body&gt;&lt;p&gt;Enter filter as Perl-style&lt;br/&gt;&lt;a href=&quot;https://perldoc.perl.org/perlre&quot;&gt;&lt;span style=&quot; text-decoration: underline; color:#0000ff;&quot;&gt;regular expression&lt;/span&gt;&lt;/a&gt;.&lt;/p&gt;&lt;p&gt;&amp;quot;.*&amp;quot; selects all.&lt;/p&gt;&lt;/body&gt;&lt;/html&gt;</string>
+   </property>
+   <property name="scaledContents">
+    <bool>false</bool>
+   </property>
+   <property name="alignment">
+    <set>Qt::AlignLeading|Qt::AlignLeft|Qt::AlignVCenter</set>
+   </property>
+   <property name="openExternalLinks">
+    <bool>true</bool>
    </property>
   </widget>
   <widget class="QWidget" name="layoutWidget">

doc/Doxyfile.in

@@ -477,7 +477,7 @@ NUM_PROC_THREADS       = 1
 # normally produced when WARNINGS is set to YES.
 # The default value is: NO.
 
-EXTRACT_ALL            = NO
+EXTRACT_ALL            = YES
 
 # If the EXTRACT_PRIVATE tag is set to YES, all private members of a class will
 # be included in the documentation.

doc/index.rst

@@ -28,6 +28,7 @@ But even if you do not use :program:`IgorPro`, you might find :program:`PMbrowse
    usage/new_user_tour
    usage/menues
    usage/displayarea
+   usage/tree-view
    usage/igor_export_infos
 
 
@@ -36,8 +37,5 @@ Indices and tables
 ==================
 
 * :ref:`genindex`
-* :ref:`search`
 
-
- 
- 
+.. * :ref:`search`

doc/usage/displayarea.rst

@@ -31,3 +31,40 @@ context menue
 -------------
 
 This menue is accessed by right-click (or option click on Macs). It offers a variety of functions.
+
+Buttons and Checkboxes
+----------------------
+
+wipe
+++++
+
+:index:`Clears display <clear display>`.
+
+auto
+++++
+
+Autoscales display.
+
+v.shrink
+++++++++
+
+Vertically shrinks display (i.e. increases y-axis range twofold).
+
+h.shrink
+++++++++
+
+Horizontally shrinks display (i.e. increases x-axis range twofold).
+
+.. _overlay-feature-label:
+
+
+Checkbox *autoscale on load*
+++++++++++++++++++++++++++++
+
+If selected, display will performe autoscale when a new trace is loaded into display.
+
+Checkbox *overlay*
+++++++++++++++++++
+
+If selected, traces in persistance buffer of the display will be displayed as background
+tarces.

doc/usage/igor_export_infos.rst

@@ -19,5 +19,5 @@ Additionally, a macro will be included to create graphs for the individual serie
 is accessible from the *Macro* menue (entry *Display Waves*) within :program:`IgorPro`.
 
 You may want to restrict the traces you export using the :ref:`filter-dlg-label`
-before invoking :ref:`export-all-visible-traces-label`
+before invoking :ref:`Export -> all visible traces <export-all-visible-traces-label>`
 from the *File* menue.

doc/usage/installation.rst

@@ -42,7 +42,7 @@ The executable :file:`QtPMbrowser` in :file:`/usr/bin` .
 
 Now, start :program:`PMbrowser` with ``QtPMbrowser &``.
 
-direct instalation of the executable
+direct installation of the executable
 *************************************
 
 The executable can be found at the GitHub repository release page: https://github.com/ChrisHal/PMbrowser/releases

doc/usage/menues.rst

@@ -1,8 +1,8 @@
 Usage
 #####
 
-The Menues
-==========
+The Menus
+=========
 
 "File"
 ******
@@ -11,7 +11,7 @@ The Menues
 ------
 
 Select a :program:`PATCHMASTER` or :program:`PATCHMASTER NEXT` :file:`.dat` file. (Alternatively,
-you can open a file by dragging it onto the :program:`PMbrowser` window. Non-bundled files, which consist
+you can open a file by :index:`dragging <drag-and-drop>` it onto the :program:`PMbrowser` window. Non-bundled files, which consist
 of a collection of various files, usually :file:`.pul` and :file:`.pgf` and possibly others
 are also present.)
 
@@ -20,41 +20,52 @@ are also present.)
 
 Close currently open file.
 
-'Export Subtree for Igor'
--------------------------
-
-All traces, that are children of the node currently selected in the **tree-view** are selected for export
-as either individual :file:`.ibw`-files or as one packaged experiment file (extension :file:`.pxp`)
-which can be read by
-:program:`IgorPro`.
+'Export...' Submenu
+-------------------
 
-The export dialog will appear, which allows you to select paths and filenames as well as several options
-that pertain to exports to packed experiment files (see :ref:`export-dlg-label` and
-:ref:`igor-export-infos-label` for additional information on exports).
+Here you find options to export traces to :program:`IgorPro` and metadata as a table.
 
-This function also available from the context menue of the **tree-view**.
 
 .. _export-all-visible-traces-label:
 
-'Export All Visible Traces for Igor'
-------------------------------------
+all visible traces
+++++++++++++++++++
 
-Similar to `'Export Subtree for Igor'`_, but all traces that are currently visible (i.e. not hidden)
-in the **tree-view** are selected for export. Traces can be hidden either by *filtering* (see
-:ref:`filter-menue-label` and :ref:`filter-dlg-label`) or by using the context menue of the **tree-view**.
+	All traces that are currently visible (i.e. not hidden)
+	in the **tree-view** are selected for export. Traces can be hidden either by *filtering* (see
+	:ref:`filter-menue-label` and :ref:`filter-dlg-label`) or by using the context menue of the **tree-view**.
+	
+	This function also available from the context menue of the **tree-view**.
 
-'Export All Traces as IBW Files'
---------------------------------
+.. _export-children:
 
-Similar to `'Export All Visible Traces for Igor'`_, but all (hidden and visible) traces will be
-exported as individual :file:`.ibw`-files. Export to a packed experiment file is not support by
-this option.
+selected with children
+++++++++++++++++++++++
 
-'Select Parameters'
--------------------
+	All traces, that are children of the node currently selected in the **tree-view** are selected for export
+	as either individual :file:`.ibw`-files or as one packaged experiment file (extension :file:`.pxp`)
+	which can be read by
+	:program:`IgorPro`.
+
+The :ref:`export dialog <export-dlg-label>` will appear, which allows you to select paths and filenames as well as several options
+that pertain to exports to packed experiment files (also see :ref:`igor-export-infos-label` for additional information on exports).
+
+metadata as table
++++++++++++++++++
+
+Export :index:`metadata <export; metadata>` as tab-delimited table.
+Parameters marked for export (see :ref:`select-params-dlg-label` ) 
+will be included in export. Additionally to these parameters, the first four columns of the table will contain
+the group, series, sweep, and trace counts.
+
+You can choose per which level of the pulse tree a table row should be 
+produced.
+
+Select Parameters
+-----------------
 
 Opens the :ref:`select-params-dlg-label`. There you can select which parameters from the PatchMaster-file
-will be either *printed* to the **text-area** or *exported* in *wave-notes*.
+will be either *printed* to the **text-area** or *exported* as *wave-notes* and *tables*.
 
 
 "Edit"
@@ -94,7 +105,7 @@ selected **tree-view** item (trace or node) and its parents to the **text-area**
 'Auto Scale'
 ------------
 
-Set scaling of graph axes to extents of most recently loaded trace.
+Set :index:`scaling <auto-scale>` of graph axes to extents of most recently loaded trace.
 
 'Do Autoscale on Load'
 ----------------------
@@ -109,6 +120,8 @@ Enter *YX mode*. The currently selected trace will be used a *X* reference for
 subsequent drawing operations. This is especially usefull if you are 
 working with ramp stimuli.
 
+.. _YT-mode:
+
 'YT mode'
 ---------
 
@@ -117,7 +130,7 @@ Enter *YT mode*, which is the default mode. *Time* will be used as the abscissa
 'Wipe All'
 ----------
 
-Clear the :ref:`grapharea-label`.
+:index:`Clear <clear display>` the :ref:`grapharea-label`.
 
 'Wipe Background Traces'
 ------------------------
@@ -167,14 +180,17 @@ Checkbox *'create pxp file'*: All waves will be exported into a single packaged
 After clicking *'OK'*, a file dialog will show up that allows you to select a filename for the file to be created.
 
 Checkbox *'create folder structure'*: If you export as a :file:`pxp` file, select this to create datafolders within
-the :file:`pxp` file that match the tree structure.
+the :file:`pxp` file that match the tree structure. You can choose if the grouping level for traces should be
+*group* or *series*.
 
 .. _filter-dlg-label:
 
 'Tree-Filter' Dialog
 ********************
 
-This dialog allows you to hide nodes and traces of the data-tree that you are not interested in.
+This dialog allows you to hide nodes and traces of the data-tree that you are not interested in. It can be accessed from the *Tree* menu
+or via the *Filter...* button.
+ 
 The filtering is based on *perl* style `regular expressions <https://perldoc.perl.org/perlre>`_. Only elements that match the given expression
 will remain visible, all other elements will be hidden.
 
@@ -187,17 +203,26 @@ See section :ref:`new-user-filtering-label` from the :ref:`new-user-tour-label`
 'Select Parameters' Dialog
 **************************
 
-For each of the four tree levels *Group*, *Series*, *Sweep*, and * Trace* you can select which parameters
+For each of the four tree levels *Group*, *Series*, *Sweep*, and *Trace* you can select which parameters
 will be printed into the **text area** when a node is selected in the **tree-view** (checkbox *'print'*)
-and / or added to the *wave-note* of exported traces (checkbox *'export'*, cf. section :ref:`igor-export-infos-label`).
+and / or added to the *wave-note* of exported traces and exported 
+as metadata tables (checkbox *'export'*, cf. section :ref:`igor-export-infos-label`).
 
 All paramters that might be of relevance should be available. If you miss something, please post a *feature request* 
 on PMbrowser's `issues page <https://github.com/ChrisHal/PMbrowser/issues>`_. 
 
+.. _relative-time-info-label:
+
+Times can represented as :index:`relative times` (*Rel. time*). The time reference for calculation of the relative times
+can be set using the context menu of the **tree-view**. By default, the reference time is the start time of the
+:file:`dat`-file.
+
+
 
 .. _ranges-dlg-label:
 
 'Setting and Ranges' Dialog
 ***************************
 
-
+Here you can configure the display area: axis ranges, *autoscale on load* and the number of overlay traces to
+be kept in the internal display buffer.

doc/usage/new_user_tour.rst

@@ -23,7 +23,7 @@ The Application Window (overview)
 	:align: center
 	:alt: tour step 1
 
-The application window is divided into three sections, the *tree view*, the *graph area*, and the *text area* (see screenshot).
+The application window is divided into three sections, the *tree view*, the *graph area*, and the *text area* (see screenshot [#]_).
 
 * The **tree view** represents the tree structure stored in the `dat`-file. *Groups* (or *experiments*, the file format treats both the same),
   *series* and *sweeps* are represented as nodes, *traces* from the final leaves of the tree. Elements for which a label is stored in the file
@@ -38,7 +38,7 @@ The application window is divided into three sections, the *tree view*, the *gra
 
 * In the **text area** mainly metadata will be printed according to the element being selected in the *tree view*.
 
-  The menuitem ``File`` --> ``Select Parameters...`` calls up a dialog which lets you choose for each
+  The menuitem ``File`` --> ``Select Parameters...`` calls up the :ref:`select-params-dlg-label` which lets you choose for each
   level (*group*, *series*, *sweep* and *trace*) which metadata items :program:`PMbrowser` shall print.
 
  .. image:: Screenshot_tour_dlg_params.png
@@ -119,3 +119,5 @@ In Igor's *Macros* menu you will find the item *Display Waves*. Select this to a
 
 **Metadata** will be included in the *wavenotes* of the imported waves. ``File`` --> ``Select Parameters...`` in :program:`PMbrowser`
 will bring forth a dialog that let's you choose which metadata-items to *export* in the wavenotes.
+
+.. [#] screenshots may represent older versions of the software and differ somewhat from the current version