X-Git-Url: http://git.tremily.us/?p=hooke.git;a=blobdiff_plain;f=doc%2Ftutorial.txt;h=58cb57f3bbfb847aafbc0441a55a96265226812c;hp=b1a450c67b9a9ca5edfd3fe36a796ebeca7a2075;hb=f62e16fe46b8f19137120a10332a64569ba3a3ad;hpb=fbfd4fa3626a59eacdba98afbb287cc4e5c79915 diff --git a/doc/tutorial.txt b/doc/tutorial.txt index b1a450c..58cb57f 100644 --- a/doc/tutorial.txt +++ b/doc/tutorial.txt @@ -46,14 +46,19 @@ If you are running hooke from the source directory (see You may need to give the full path for Python on Windows systems, and also check that the current working directory (`.`) is in your -`PYTHONPATH`. See `python(1)` for details. +`PYTHONPATH`. See :manpage:`python(1)` for details. As Hooke launches, you should see something like the following in your terminal:: - Hooke version 0.8.0 Seinei + Hooke version 0.9.0.devel (Kenzo) - COPYRIGHT + Copyright (C) 2006-2010 A. Seeholzer, Alberto Gomez-Casado, Allen + Chen, Fabrizio Benedetti, Francesco Musiani, Marco Brucale, Massimo + Sandal, Pancaldi Paolo, Richard Naud, Rolf Schmidt, W. Trevor King + + Hooke comes with ABSOLUTELY NO WARRANTY and is licensed under the GNU + Lesser General Public License. For details, run `license`. ---- hooke> @@ -76,9 +81,16 @@ Or see specific help on ``TOPIC`` with:: for example:: - hooke> help current + hooke> help load_playlist + +will give help on the ``load_playlist`` command. + +Leaving Hooke +------------- -will give help on the ``current`` command. +When you're done with an interactive Hooke session, you can close the +session with ``exit`` or its aliases ``quit`` and ``EOF`` (``EOF`` is +the end of the stdin stream, which is Ctrl-d in many shells). Creating a playlist ------------------- @@ -94,7 +106,7 @@ and you want to analyze them all. You then can ``cd`` (change directory) to the directory:: - hooke> cd c:\curves + hooke> cd --path c:\curves Type ``pwd`` (print working directory) to check the directory is correct.:: @@ -105,38 +117,58 @@ You can list the files in the directory using ``ls`` or ``dir`` (they’re synonyms).:: hooke> ls - [’mycurve.000’, ’mycurve.001’, ... - ] + mycurve.000 + mycurve.001 + ... + +Now you are ready to generate the playlist. First, create a blank playlist:: + + hooke> new_playlist --name mylist -Now you are ready to generate the playlist. The command to use is -``genlist``.:: +Ensure that the new playlist is active:: - hooke> genlist mycurve.* + hooke> jump_to_playlist -- -1 + hooke> get_playlist + -You can also generate a playlist containing all what you find in the -directory by typing: +The ``--`` in the ``jump_to_playlist`` command lets +``jump_to_playlist`` know that ``-1`` is an argument and not an +option. Using the bare ``--`` is a POSIX specification [#POSIX]_ +supported by the `optparse module`_. - hooke> genlist c:\curves +.. _optparse module: + http://docs.python.org/library/optparse.html#callback-example-6-variable-arguments -If you want to select what curves to see, based on the filename, you -can use wildcards. For example:: +.. [#POSIX] `Guideline 10 of POSIX:2008's section 12.2 `_ states: - hooke> genlist mycurve.05* + "The first ``--`` argument that is not an option-argument should be + accepted as a delimiter indicating the end of options. Any + following arguments should be treated as operands, even if they + begin with the ``-`` character." + +Then glob your curves onto the new list:: + + hooke> glob_curves_to_playlist mycurve.* + +You can also be more specific with wildcards. For example:: + + hooke> glob_curve_to_playlist mycurve.05* will take only curves from :file:`mycurve.050` to :file:`mycurve.059`. -Note that by using ``genlist`` you just generate the playlist in the -local session. To save your playlist to a file for future reuse, -type:: +Note that by using ``glob_curves_to_playlist`` you just generate the +playlist in the local session. To save your playlist to a file for +future reuse, type:: - hooke> savelist mylist + hooke> save_playlist --output mylist In this example, the list will be saved in the file :file:`mylist.hkp`. Hooke will add the extension ``.hkp`` (Hooke playlist) to the playlist if you forget to. The ``.hkp`` file is an XML file you can read and edit with any text editor (i.e. Wordpad), if -needed. If you want to load it, simply issue ``loadlist mylist.hkp`` -or ``loadlist mylist``, Hooke will add ``.hkp`` if necessary. +needed. If you want to load it, simply issue ``load_playlist +mylist.hkp`` or ``load_playlist mylist``, Hooke will add ``.hkp`` if +necessary. If, generating the playlist, you are including by chance a non-force curve file that Hooke cannot open, Hooke will print an error and @@ -145,67 +177,67 @@ continue on. Navigating the playlist ----------------------- -Now you can navigate through your playlist using the commands `next` -and `previous` or, their aliases `n` and `p`. You don’t need to -type `n` every time to run along a list of curves. If you press -Return to an empty prompt, Hooke will repeat the last command you -issued explicitly. You can also navigate through the command history -by using the up and down arrows. From the last curve of your -playlist, `n` will wrap around to the first curve. Analogously, -issuing `p` at the first curve will jump to the last. +Now you can navigate through your playlist using the commands +``next_curve`` and ``previous_curve``. You don’t need to type +``next_curve`` every time to run along a list of curves. You can +navigate through the command history by using the up and down arrows, +or auto-complete partial commands with TAB. From the last curve of +your playlist, ``next_curve`` will wrap around to the first curve. +Analogously, issuing ``previous_curve`` at the first curve will jump +to the last. You can also jump to a given curve:: - hooke> jump c:\curves\mycurve.012 + hooke> jump_to_curve 14 -where the path can be either an absolute path, or a path relative to -the directory holding the playlist file. +will jump to the 14th curve in the playlist. TODO: jump_to_curve +, where the path can be either an absolute path or a path +relative to the directory holding the playlist file. Taking notes ------------ You can take notes about the curves you are looking at. Just type -`note` followed by the text you want to append to that curve. Hooke -will save the text in your current playlist and in an external log -file. The output will look like this:: +``set_note`` followed by the text you want to attach to that curve. +Hooke will save the text in your current playlist and in an external +log file (TODO: no external file yet. Is this important?). The +output will look like this:: Notes taken at Sun Sep 17 20:42:07 2006 - /home/cyclopia/work/tris/20060620a.041 | This is a note - /home/cyclopia/work/tris/20060620a.207 | This is another note - /home/cyclopia/work/tris/20060620a.286 | This is a third one + /home/cyclopia/work/tris/20060620a.041 | This is a note + /home/cyclopia/work/tris/20060620a.207 | This is another note + /home/cyclopia/work/tris/20060620a.286 | This is a third one The log file name can be configured (:doc:`config`), but it defaults to :file:`hooke.log`. -Usually curves you annotated are useful later. You can copy the curves -you annotated to a different directory by using the ``copylog`` -command. +Usually curves you annotated are useful later. You can create a +playlist for only annotated curves with - hooke> copylog c:\nicecurves + hooke> note_filter_playlist --name c:\curves\nice.hkp -will copy all curves you have annotated to the :file:`c:\nicecurves` -directory. Make sure that the directory already exists before doing -that. TODO: replace with:: +will create sub-playlist :file:`c:\curves\nice.hkp`. Make sure that +the target directory (here :file:`c:\curves\`) already exists before +doing that. - hooke> copylist --log c:\curves\nice.hkp +If you change your mind about a note, you can remove it by setting a +blank note string with ``set_note ''``. Exporting curves ---------------- You can export Hooke curves as images and as text columns. To export -as images, issue the ``export`` command followed by the filename. -Supported formats are PNG (raster) and EPS (Encapsulated Postscript, -vector). The export format is determined by the filename extension, -so ``export foo.png`` and ``export foo.eps`` will save PNG and EPS -files respectively. - -To export as text, use the ``txt`` command, followed by the -filename. The output is a text file containing columns (first two are -X and Y of extension, second two are X and Y of retraction). +as images or text, use the ``export_block`` command. Supported +formats are PNG (Portable Network Graphic, raster) and EPS +(Encapsulated Postscript, vector). The export format is determined by +the filename extension, so ``export_block foo.png``, ``export_block +foo.eps``, and ``export_block foo.txt`` will save PNG, EPS, and +TAB-delimited text files respectively. TODO: multiple cycles? Solution: blank lines for "breaks", add option to extract specific sections using Python's slice notation. +If you don't want the entire block, try the ``cut`` command. Interacting with the plot ------------------------- @@ -276,7 +308,7 @@ Configuring Hooke ----------------- You can set environment variables to influence the behaviour of -Hooke. The command to use is ``set``. +Hooke. The command to use is ``set_config``. You can alter permanently the behaviour of Hooke by setting these variables in a Hooke configuration file. See :doc:`config` for