Equiped xorriso-tcltk with help texts and enabled it to start xorriso by itself

libisoburn/trunk/frontend/README-tcltk

@@ -24,16 +24,38 @@ See man xorriso for a documentation of xorriso concepts and commands.
 See man xorrecord for details of the burn image file feature.
 
 
-Quick start:
+                             Quick start
 
-  xorriso -launch_frontend $(which xorriso-tcltk) --stdio --
+In the xorriso build directory, without installation of xorriso:
 
+  xorriso/xorriso -launch_frontend frontend/xorriso-tcltk --stdio --
+
+After installation of xorriso by make install:
+
+  xorriso-tcltk
+
+
+                            Overview of GUI
+
+The window is separated into three main areas:
+- Connection to xorriso.
+- Management of drives and image files.
+- Inspection, manipulation, and exploitation of xorriso ISO image model.
+
+Click the rightmost mouse button while being over any of the GUI elements
+in order to get the particular help text for that element.
+There is no need to close the help window. Just click another element to
+get another help text.
+
+
+                         Program start options
 
 The Tcl shell "wish" is allergic to options which start by "-h".
 So here is the output of  xorriso-tcltk --help :
 ------------------------------------------------------------------------
+
 Usage:
-  xorriso-tcltk [options]
+  frontend/xorriso-tcltk [options]
 Options:
  All options must be given with two dashes ("--option") in
  order to distinguish them from any options of the Tcl shell.
@@ -51,6 +73,9 @@ Options:
      It is important that the parent of xorriso and of this
      tcl/tk frontend opens the named pipe for commands before
      it opens the named pipe for replies. This avoids deadlock.
+ --silent_start
+     Do not issue the start message xorriso-tcltk-version.
+     This works only if --silent_start is the first argument.
  --geometry {+|-}X{+|-}Y
      Sets the position of the main window.
  --click_to_focus
@@ -63,229 +88,12 @@ Options:
      Set a file address for logging of xorriso commands and
      reply messages. The log lines will be appended.
 
-Either --stdio or --named_pipes must be given for a program run.
+If neither --stdio nor --named_pipes is given, then this script
+will try to locate itself in the filesystem and start a xorriso
+run that launches it again.
+
+In the running GUI, click with the rightmost mouse button on
+any GUI element to get its particular help text.
 
 ------------------------------------------------------------------------
 
-
-                         Overview of GUI elements
-
-The window is separated into three main areas:
-- Connection to xorriso.
-- Management of drives and image files.
-- Inspection, manipulation, and exploitation of xorriso ISO image model.
-
-------------------------------------------------------------------------
-
-                         Connection to xorriso
-
-The "End" button leads to the end of frontend and xorriso process.
-
-The ready/busy field indicates whether a xorriso command is being executed
-and the frontend is still waiting for its reply messages.
-
-The "Command:" field can be used to send commands to xorriso.
-
-The "Refresh state display" button causes the other two main areas to update
-their display after manually transmitted commands may have changed the state
-of drives or ISO model.
-
-The "Log pipes" switch controls whether all xorriso commands and replies
-shall be logged to standard error resp. to the file that has been iven
-with program argumen --log_file. Caution: This log is verbous.
-
-The message box displays commands sent to xorriso and messages recieved
-from xorriso.
-Many commands which are emitted by the GUI will hide themselves and their
-replies from this display.
-All event messages with severity WARNING or higher will show up, nevertheless.
-
-The "Recent problem:" field shows the most severe event message that occured
-during the execution of the most recent command. It also displays the most
-recent problem message from the frontend program itself.
-Several commands emitted by the GUI will not clear this display. But any
-manually transmitted command and the major GUI gestures will do.
-
-The "Worst problem:" field shows the most severe event message that occured
-since last time the "Clear" button was hit. It will not clear automatically.
-
-
-------------------------------------------------------------------------
-
-                    Management of drives and image files
-
-The "Scan for drives" button executes command -devices and puts the list
-of found optical drives into the box underneath the button.
-
-The "Pick input drive" button executes command -indev and obtains some
-information about the medium status. This info is displayed in the 
-"Input drive or image" line.
-Further it causes the display of the ISO image model to be updated.
-
-The "Pick output drive" button executes command -outdev and displays the
-related info in the "Output drive or image" line.
-
-The "Pick drive for both roles" button executes command -dev and displays
-info in both "... drive or image" lines.
-
-The "Give up drives" executes commands -indev "" -outdev "" and clears
-both "... drive or image" lines, as well as the ISO model.
-
-The "Calm drives" button executes command -calm_drives which tells the
-aquired optical drives to stop spinning until the next drive activity
-gets triggered.
-
-The "Rollback" button excutes command -rollbackwhich drops all pending
-changes of the ISO model and reloads it from the input drive, if one is
-aquired.
-
-The box underneath these buttons shows the optical drives found by the
-"Can for drives" button.
-A double-click on a drive item has the same effect as button "Pick drive
-for both roles".
-
-The line "Input drive or image" displays address and medium status of
-the input drive.
-Its "Eject" button excutes command -eject "in".
-Editing the drive address and pressing the Return key causes the execution
-of command -indev with the field content as drive address. Use this to
-load the model from ISO image data files on hard disk.
-
-The line "Output drive or image" does about the same for the output drive.
-The text input field can be used to address an existing ISO image data
-file or to address a data file that does not yet exist. In the latter
-case, the ,edium status will be blank.
-
-The "Blank" button executes command -blank "as_needed" on the output drive.
-This also applies to ISO image data files, which will get invalidated by
-a small write operation.
-
-The "Format" button executes -format "as_needed".
-This only applies to real optical drives and s of interest only with DVD-RW
-or BD-R media, which both can be used formatted and unformatted. Other media
-types which mandatorily need formatting will be formatted by the write
-commands.
-
-The "Write ISO session" executes command -commit, which writes a session
-with all pending changes to the output drive. The output drive must be
-either blank or it must be the same as the input drive.
-
-The "Close" switch controls whether command -close "on" is emitted with
-"Write ISO session" or whether -as cdrecord option -multi is omitted with
-"Burn image file:".
-
-The "TAO" switch controls whether an incremental write type shall be
-enforced with write commands. Normally xorriso will decide by medium status
-and job parameters which write type to choose.
-
-The "Defect Mgt" switch controls whether slow and error-prone drive internal
-check reading shall be enabled with formatted BD-R or with BD-RE.
-
-The "Burn image file:" button executes command -as "cdrecord" with the
-content of its text field  as disk file address of a data file that is
-to be written to the output drive.
-The medium in the drive may be blank or appendable.
-
-
-------------------------------------------------------------------------
-
- Inspection, manipulation, and exploitation of xorriso ISO image model
-
-The "Extract to disk:" button executes command -extract with the whole
-tree of the current ISO directory or with the selected items of the box
-underneath "ISO directory:".
-This copies the selected files or directory trees from the input drive
-to the address on hard disk which is given by the text filed right of
-the button.
-
-The "Underneath" switch controls the effective hard disk address of an item
-if the address in the text field points to a directory. If "Underneath"
-is enabled, then the file object from the ISO filesystem will be copied to its
-name underneath the hard disk directory.
-If "Underneath" is disabled then an ISO directory tree item will be merged
-with the disk directory tree at the given address.
-Example:
-Selected are "/iso_dir" and "/iso_file".
-Address for hard disk is "/tmp/from_iso". Switch "Selected" is enabled.
-"Underneath" enabled causes commands:
-  -extract /iso_dir /tmp/from_iso/iso_dir 
-  -extract /iso_file /tmp/from_iso/iso_file 
-"Underneath" disabled:
-  -extract /iso_dir /tmp/from_iso
-  -extract /iso_file /tmp/from_iso
-The last command will fail because /tmp/from_iso already exists as directory.
-
-The "Selected" switch controls whether the whole current ISO directory,
-or only the selected items shall be copied to to hard disk.
-
-The "Overwrite files" switch controls whether existing files may be
-overwritten in the ISO image or by extraction on hard disk.
-The frontend program will only detect the most obvious name collisions,
-but xorriso will reliably refuse to overwrite files if this is banned.
-
-The "Overwrite ISO dirs" switch controls whether it is allowed to replace
-an ISO directory by a non-directory file.
-If a directory is copied to a directory, then both directory trees will
-be merged. So this switch applies only to situations where non-directories
-hit directories.
-
-The "Enforce disk dir write access" switch enables the options "auto_chmod_on"
-and "sort_lba_on". "auto_chmod_on" allows xorriso to give itself temporariy
-w-permission to all disk directories which are owned by the xorriso user.
-This is not without dangers, of course, but comes in handy with restoring of
-backups.
-Option "sort_lba_on" reduces head-moves of optical drives and thus can
-speed up extraction substantially. It is bound to "auto_chmod_on" because
-else it might get in trouble when restoring ISO directories which offer
-no w-permission.
-
-The "Refresh avail:" button triggers a time consuming exact prediction
-of the free space on the medium in the output drive. For this purpose,
-the size of an ISO session with the pending changes is computed.
-With image files rather than real optical drives, the free space of
-the hosting filesystem is displayed.
-
-The "Insert from disk:" button executes command -map with the disk file
-address that is given by the text field right to the button.
-
-The switch "Underneath" has the same effect as with file extraction:
-If enabled, a directory from disk will not be unpacked to its single files
-but put underneath the target address by its own leaf name.
-If the switch "Selected" is enabled, then the given disk file or tree will
-be inserted at or underneath the only selected item in the box inderneath
-"ISO directory:".
-
-The text field in the "ISO directory:" line displays the current ISO
-directory and can be used to toggle its path directly. Hitting the
-Return key causes the current directory to change and the display in
-the box underneath to be refreshed.
-
-The "Up" buttons move the current ISO directory one directory level up.
-
-The "Verify" button executes -md5_check_r "SORRY" with the current ISO
-directory. ISO images bear MD5s for each data file if they were produced
-by xorriso with -md5 "on" resp. -for_backup. This frontend enables this
-feature on startup.
-
-The list box underneath the "ISO directory:" line displays the files in
-the current ISO directory. One or more item can be selected and play a
-role with extraction or insertion of files.
-Most of the buttons underneath the box operate on the selected items
-unconditionally.
-
-The "Verify" button in the "ISO selection:" line executes command
--md5_check_r "SORRY" with each of the selected items.
-
-The "Delete" button executes command -rm_r with each of the selected items.
-
-The "Rename to:" button iuses command -mv to move each of the selected
-items to the address that is given by the text field right to the button.
-If this address points to an existing ISO directory, then the items will
-be moved underneath that directory and keep their leaf names.
-Else there may be only one selected item which will be renamed to the
-given address.
-
-The "Make dir" button executes command -mkdir with the address in the
-text field to its left (the same as used by "Rename to:"). Useful to
-create a target directory before moving the selection.
-