changes in the manual (section Mini-language moved to other sections)

TODO

@@ -1,5 +1,6 @@
-* docs: Mini-Language > Intro -> Getting Started > CLI,
-        move Mini-Language > Grammar -> Scripts
+* GUI: make \-line continuation work
+
+* docs: re-read recent changes, guilabel:`View whole` -> image
 
 * GUI: data open dialogs should make possible to explicitely pass file format,
   for instance "@+ <'/run/mw/example.xy' text"

doc/fitheme/static/fitheme.css

@@ -322,7 +322,8 @@ div.seealso {
 div.topic { background-color: #eee; }
 p.admonition-title { display: inline; }
 /*p.admonition-title:after { content: ":"; }*/
-pre, tt, code {
+pre, tt, code,
+div.admonition-cli p.last {
     font-family: 'Consolas', 'Menlo', 'Deja Vu Sans Mono', 'Bitstream Vera Sans Mono', monospace;
     font-size: 0.9em;
 }
@@ -418,6 +419,42 @@ div.admonition-in-the-gui p.admonition-title {
     background: url('mouse16.png') no-repeat 10px 0;
 }
 
+div.admonition-cli {
+    display: inline-block;
+    border-width: 0;
+    padding: 2px 3px;
+    //background-color: transparent;
+    background-color: #999;
+    border-radius: 6px 6px 6px 6px;
+    margin-top: 0;
+}
+div.admonition-cli p.admonition-title {
+    vertical-align: middle;
+    color: #f0f0f0;
+    background-color: transparent;
+    padding: 1px 8px 1px 10px;
+    font-size: 0.8em;
+    display: inline;
+}
+div.admonition-cli p.last {
+    vertical-align: middle;
+    background: #f0f0f0;
+    color: #222;
+    display: inline;
+    padding: 3px 8px 2px 10px;
+    border-radius: 5px 5px 5px 5px;
+}
+
+span.cli-title {
+    display: inline-block;
+    border-radius: 5px;
+    background-color: #999;
+    color: #f0f0f0;
+    font-size: 0.8em;
+    font-weight: bold;
+    padding: 1px 5px;
+}
+
 .quote { font-size: 0.9em; }
 .quote-author, div.body span.quote-author a { color: #888; }
 div.screenshot { clear: right; float: right; margin-left: 1em; }

doc/fityk-manual.rst

@@ -10,7 +10,6 @@ Fityk |version| - User's Manual
 
    intro
    getstarted
-   lang
    data
    model
    fit

doc/getstarted.rst

@@ -56,119 +56,207 @@ later detail in the processing is irrelevent for the time being.
 The data file used in this example is distributed with the program and
 can be found in the :file:`samples` directory.
 
-First load data from file :file:`nacl01.dat`.
-You can do this by typing::
+.. role:: cli-title
 
-   @0 < nacl01.dat 
-
-The :abbr:`CLI (Command Line Interface)` version of the program is all
-about typing commands. From time to time it is also handy to type
-a command in the :abbr:`GUI (Graphical User Interface)`,
-but usually the GUI provides more intuitive, mouse-driven way to perform
-the same operation -- it is mentioned in the the grey boxes below.
+Textual commands that correspond to performed operations are shown
+in this section in :cli-title:`CLI` boxes.
 
-.. admonition:: In the GUI
-
-   select :menuselection:`Data --> Load File`
-   from the menu (or |load-data-icon| from the toolbar) and choose the file.
+First load data from the :file:`nacl01.dat` file.
+Select :menuselection:`Data --> Load File`
+from the menu (or |load-data-icon| from the toolbar) and choose the file.
 
 .. |load-data-icon| image:: img/load_data_icon.png
    :alt: Load Data
    :class: icon
 
-If you use the GUI, you can zoom-in to the biggest peak using left mouse
-button on the residual plot (the plot below the main plot).
-To zoom out, press the :guilabel:`View whole` toolbar button.
+.. admonition:: CLI
 
-Now all data points are active. Because only the biggest peak is of
-interest for the sake of this example, the remaining points can be
-deactivated::
+   @0 < nacl01.dat 
 
-   A = (x > 23.0 and x < 26.0)
-   
-.. admonition:: In the GUI
 
-   change to the :dfn:`range` mode (toolbar: |mode-range-icon|)
-   and deactivate not needed points with the right mouse button.
+You can zoom-in to the biggest peak using left mouse
+button on the residual plot (the plot below the main plot).
+To zoom out, press the :guilabel:`View whole` toolbar button.
+
+Now all data points are active. Only the biggest peak is of
+our interest, so we want to deactivate the remaining points.
+Change to the :dfn:`range` mode (toolbar: |mode-range-icon|)
+and deactivate not needed points with the right mouse button.
 
 .. |mode-range-icon| image:: img/mode_range_icon.png
    :alt: Data-Range Mode
    :class: icon
 
+.. admonition:: CLI
+
+   A = (x > 23.0 and x < 26.0)
+
 As our example data has no background to worry about, our next step is
 to define a peak with reasonable initial values and fit it to the data.
 We will use Gaussian.
 To see its formula, type: ``info Gaussian`` (or ``i Gaussian``) or look for it
 in the section :ref:`flist`.
 
-To add a peak, either set the initial parameters manually::
-
-   F += Gaussian(~60000, ~24.6, ~0.2)
+Select :guilabel:`Gaussian` from the list of functions on the toolbar
+and press |add-peak-icon|.
 
-.. admonition:: In the GUI
-
-    it is also possible to set the initial parameters with the mouse:
-    change the GUI mode to |mode-add-icon|,
-    click on the plot and drag the mouse to select
-    the position, height and width of a new peak.
-
-.. |mode-add-icon| image:: img/mode_add_icon.png
-   :alt: Add-Peak Mode
+.. |add-peak-icon| image:: img/add_peak_icon.png
+   :alt: Auto Add
    :class: icon
 
-or let the program guess it::
+.. admonition:: CLI
 
    guess Gaussian
 
-.. admonition:: In the GUI
 
-   select :guilabel:`Gaussian` from the list of functions on the toolbar
-   and press |add-peak-icon|.
+If you'd like to set the initial parameters manually,
+change the GUI mode to |mode-add-icon|,
+click on the plot and drag the mouse to select
+the position, height and width of a new peak.
 
-.. |add-peak-icon| image:: img/add_peak_icon.png
-   :alt: Auto Add
+.. |mode-add-icon| image:: img/mode_add_icon.png
+   :alt: Add-Peak Mode
    :class: icon
 
-If the functions are not named explicitely (like in this example),
-they get automatic names ``%_1``, ``%_2``, etc.
+.. admonition:: CLI
 
+   F += Gaussian(~60000, ~24.6, ~0.2)
 
-Now let us fit the function. Type: ``fit``.
 
-.. admonition:: In the GUI
+If the peaks/functions are not named explicitely (like in this example),
+they get automatic names ``%_1``, ``%_2``, etc.
 
-    select :menuselection:`Fit --> Run` from the menu or press |fit-icon|.
+Now let us fit the function.
+Select :menuselection:`Fit --> Run` from the menu or press |fit-icon|.
 
 .. |fit-icon| image:: img/fit_icon.png
    :alt: Fit
    :class: icon
 
+.. admonition:: CLI
+
+   fit
+
 .. important::
 
     Fitting minimizes the **weighted** sum of squared residuals
     (see :ref:`nonlinear`).
     The default :ref:`weights of points <weights>` are not equal.
 
-To see the peak parameters, type: ``info prop %_1``.
+To see the peak parameters,
+move the cursor to the top of the peak
+and select "Show Info" from the context menu (right mouse button).
+Or check the parameters on the sidebar.
+
 
-.. admonition:: In the GUI
+.. admonition:: CLI
 
-   move the cursor to the top of the peak
-   and try out the context menu (the right mouse button),
-   or check the parameters on the sidebar.
+   info prop %_1
 
 That's it!
 
-You can save all the issued commands to a file::
+You can save all the issued commands to a file
+(:menuselection:`Session --> Save History`)
+
+.. admonition:: CLI
 
    info history > myscript.fit
 
-and later use it as a macro::
+and later use it as a macro (:menuselection:`Session --> Execute script`).
+
+.. admonition:: CLI
 
    exec myscript.fit
 
-.. admonition:: In the GUI
 
-   use :menuselection:`Session --> Save History`
-   and :menuselection:`Session --> Execute script`, correspondingly.
+.. _cli:
+
+Command Line
+============
+
+Fityk comes with a small domain-specific language (DSL).
+All operations in Fityk are driven by commands of this language.
+Commands can be typed in the input box in the GUI, but if all you want
+to do is to type commands, the program has a separate CLI version (cfityk)
+for this.
+
+.. admonition:: Do not worry
+
+   you do not need to learn these commands.
+   It is possible to use menus and dialogs in the GUI
+   and avoid typing commands.
+
+When you use the GUI and perform an action using the menu,
+you can see the corresponding command in the output window.
+Fityk has less than 30 commands. Each performs a single actions,
+such as loading data from file, adding function, assigning variable,
+fitting, or writing results to a file.
+
+A sequence of commands written down in a file makes a script (macro),
+which can automate common tasks. Complex tasks may need to be programmed
+in a general-purpose language. That is why Fityk has embedded Lua interpreter
+(Lua is a lightweight programming language).
+It is also possible to use Fityk library from a program in Python, C, C++,
+Java, Ruby or Perl, and possibly from other languages supported by SWIG.
+
+Now a quick glimpse at the syntax. The ``=->`` prompt below marks an input::
+
+  =-> print pi
+  3.14159
+  =-> # this is a comment -- from `#' to the end of line
+  =-> p '2+3=', 2+3  # p stands for print
+  2+3 = 5
+  =-> set numeric_format='%.9f'  # show 9 digits after dot
+  =-> pr pi, pi^2, pi^3  # pr, pri and prin also stand for print
+  3.141592654 9.869604401 31.006276680
+
+Usually, one line has one command, but if it is really needed,
+two or more commands can be put in one line::
+
+  =-> $a = 3; $b = 5  # two commands separated with `;'
+
+or a backslash can be used to continue a command in the next line::
+
+  =-> print \
+  ... 'this'
+  this
+
+If the user works simultaneously with multiple datasets, she can refer to
+a dataset using its number: the first dataset is ``@0``, the second -- ``@1``,
+etc::
+
+  =-> fit # perform fitting of the default dataset (the first one)
+  =-> @2: fit # fit the third dataset (@2)
+  =-> @2 @3: fit # fit the third dataset (@2) and then the fourth one (@3)
+  =-> @*: fit # fit all datasets, one by one
+
+Settings in the program are changed with the command ``set``::
+
+  set key = value
+
+For example::
+
+  =-> set logfile = 'C:\log.fit' # log all commands to this file
+  =-> set verbosity = 1 # make output from the program more verbose
+  =-> set epsilon = 1e-14
+
+The last example changes the *ε* value, which is used to test floating-point
+numbers *a* and *b* for equality (it is well known that due to rounding
+errors the equality test for two numbers should have some tolerance,
+and the tolerance should be tailored to the application): \|\ *a−b*\ | < *ε*.
+
+To run a single command with different settings, add ``with key=value`` before
+the command::
+
+  =-> print pi == 3.14  # default epsilon = 10^-12
+  0
+  =-> with epsilon = 0.1 print pi == 3.14  # abusing epsilon
+  1
+
+.. highlight:: none
+
+Each line has a syntax::
+
+  [[@...:] [with ...] command [";" command]...] [#comment]
 
+All the commands are described in the next chapters.

doc/index.rst

@@ -151,8 +151,8 @@ Documentation
 =============
 
 * `Manual <fityk-manual.html>`_
-  (chapters :ref:`intro`, :ref:`getstarted`, :ref:`lang`, :ref:`data`,
-  :ref:`model`, :ref:`fit`, :ref:`ref`).
+  (chapters :ref:`intro`, :ref:`getstarted`, :ref:`data`,
+  :ref:`model`, :ref:`fit`, :ref:`scripts`, :ref:`ref`).
 * PDF, ePUB and older versions of the manual can be downloaded
   `from Read the Docs <https://readthedocs.org/projects/fityk/downloads/>`_.