Commit efdf1fb7 authored by Aaron R. Larson's avatar Aaron R. Larson
Browse files

Update manpage. Add "--help-options" command line argument to

list available options.  Generate better diagnostics for malformed
"--options", and permit boolean options to be specified as "true"
or "false" in addition to 0 and 1. (#496872)


svn path=/trunk/; revision=3471
parent a5745d26
2008-03-22 Aaron Larson <alarson@aaron2>
* Update manpage. Add "--help-options" command line argument to
list available options. Generate better diagnostics for malformed
"--options", and permit boolean options to be specified as "true"
or "false" in addition to 0 and 1. (#496872)
2008-03-22 Aaron Larson <alarson@aaron2>
* Eliminate most compiler redifintion warnings for "_" (#519254).
......
......@@ -3,7 +3,7 @@ man_MANS = dasher.1
EXTRA_DIST = dasher.1.in
DISTCLEANFILES=dasher.1
dasher.1:
sed s/PACKAGE_VERSION/$(PACKAGE_VERSION)/ <$(srcdir)/dasher.1.in >dasher.1
dasher.1: $(srcdir)/dasher.1.in
sed -e s/PACKAGE_VERSION/$(PACKAGE_VERSION)/ -e s:DOCDIR:$(docdir): <$< >$@
.TH DASHER "1" "January 2004" "PACKAGE_VERSION" "User Commands"
\" URL macro from http://people.debian.org/~branden/talks/wtfm/wtfm.pdf
.de URL
\\$2 \(laURL: \\$1 \(ra\\$3
..
.if \n[.g] .mso www.tmac
.TH dasher "1" "2008-02-28" "PACKAGE_VERSION" "User Commands"
.SH NAME
dasher \- graphical predictive text entry system
.SH SYNOPSIS
.B "less [-wop] [\fIfilename\fP]"
.BR dasher " [" OPTIONS "] [" filename "]"
.SH DESCRIPTION
.B dasher
.B Dasher
is an information-efficient text-entry interface, driven by
natural continuous pointing gestures. Dasher is a competitive
text-entry system wherever a full-size keyboard cannot be used.
.SH OPTIONS
.B dasher
takes the following options:
.IP "-o"
Dasher will appear without a text edit box and will default to entering
text into other windows.
.IP "-p"
Dasher will open a preferences window and not the main window.
.IP "-s"
Dasher will output the entered text to stdout whenever stopped. Only text
entered since the last stop will be output.
.IP "-w"
Whenever Dasher is stopped, the time taken, number of characters
entered, and number of bits of information will be displayed, along
with ratios of these quantities.
.TP
.BR \-a ", " \-\-appstyle = \fISTYLE\fR
Application style. \fISTYLE\fR can be any of
.BR traditional ", " direct ", " compose ", or " fullscreen .
The default is whatever was specified on the previous invocation of
Dasher, or \fBtraditional\fR when Dasher is started for the first
time.
.TP
.BR \-? ", " \-\-help
Describe command line options.
.TP
.B \-\-help-options
Describe the options available with \fB\-\-options\FR.
.TP
.BR \-o ", " \-\-options " [" option = value [, option = value ...]]
Override stored options.
Options values are remembered for subsequent invocations of Dasher.
.SH USAGE
After startup, Dasher will present the user with a window containing two major
sections. The top portion is the edit box - text entered via Dasher will appear
here, and the text may also be edited directly. The bottom portion is the main
Dasher interface and will display a blank background with a column of letters
on the right hand side. Clicking the mouse button will start the model, and the
screen will zoom towards the point underneath the mouse pointer. To select a
letter, move the mouse pointer into it and watch how it zooms underneat the
crosshair. Within the selected letter, a new column of letters will appear.
Move the pointer over one of these letters to select it as the next letter. To
correct mistakes, move the mouse pointer to the left of the crosshair and
Dasher will zoom out allowing you to select new letters.
The main Dasher interface is a window with a blank background
containing a column of letters on the right hand side.
Click the mouse button to start.
When the pointer is to the right of the crosshair the screen will zoom
towards the point underneath the mouse pointer.
To select a letter, move the mouse pointer into it and watch how it
zooms underneath the crosshair.
A new column of letters will appear.
Staying within the box for the selected letter, move the pointer over
one of these letters to select it as the next letter.
Moving the mouse pointer to the left of the crosshair, or outside of
the box for previously selected letters, allows you to change
previously selected letters.
.PP
.SH Application Styles
.TP
.B traditional
Dasher displays an \fIedit box\fR above the main window.
Text entered via Dasher will appear in the edit box allowing the text
to be edited directly.
.TP
.B direct
The edit box is not displayed.
Dasher runs without focus and the text goes into whatever window does have
focus.
This way you can use it more practically to run your desktop.
\".TP
\".B compose
\" Don't know.
.TP
.B fullscreen
dasher expands to the entire screen.
.SH MENUS
.SS File
.IP New
Restore Dasher to the state it was in when started
Clear the edit box and associated a random filename with it.
.IP Open
Read a text file into the Dasher edit box for further editting
Read a text file into the edit box for further editing.
.IP Save
Save the contents of the Dasher edit box to a file
Save the contents of the edit box to it's associated file.
.IP "Save as"
Save the contents of the Dasher edit box to a file chosen by the user
Save the contents of the edit box to a selected file.
.IP "Append to file"
Add the contents of the Dasher edit box to the end of a file chosen by the user
Add the contents of the edit box to the end of a selected file.
.IP "Import training text"
Use a file to further train Dasher (for instance, a training file containing
scientific terms to add to the initial English training). Training files must
be UTF-8 encoded.
.IP Exit
Quit Dasher
Use a file to further improve Dasher's prediction of the next letters
to present (for instance, a training file containing scientific terms
to add to the initial English training).
Training files must be UTF-8 encoded.
.IP Quit
Exit Dasher.
.SS Edit
.IP Cut
Remove the highlighted text from the edit box and copy it to the clipboard
Remove the highlighted text from the edit box and copy it to the clipboard.
.IP Copy
Copy the highlighted text from the edit box to the clipboard but don't remove
it
it.
.IP Paste
Paste the contents of the clipboard into the edit box at the position of the
cursor
cursor.
.IP "Copy all"
Copy the entire contents of the edit box to the clipboard
Copy the entire contents of the edit box to the clipboard.
.IP "Select all"
Highlight all of the text in the edit box
Highlight all of the text in the edit box.
.SS Options
.IP "Preferences"
Opens the preferences dialog (see
.SM
.B "THE PREFERENCES DIALOG"
below)
.IP "Edit font"
Choose the font used in the edit box
.IP "Dasher font"
Choose the font used in the Dasher canvas
.IP "Dasher font size"
Choose the size of the font used in the Dasher canvas
.IP "Reset fonts"
Reset the fonts back to the defaults
.IP "Enter text into other windows"
Make Dasher enter text into the currently focused window. Requires Dasher to
have been built with
.B--with-a11y.
Note that some languages will only work correctly if XFree 4.0.2 or higher is
being used.
.IP "Control mode"
Provides a control node at the bottom of the screen. This allows various tasks
to be performed inside Dasher, such as editing the text written, speaking
entered text and stopping or pausing Dasher. If compiled with
.B--with-a11y
and using a desktop supporting the ATK accessibility framework, compliant
applications will have their menu trees exported to Dasher and these may be
accessed via this node.
Opens the preferences dialog.
\".SM
\".B "THE PREFERENCES DIALOG"
\".IP "Edit font"
\"Choose the font used in the edit box
\"
\".IP "Dasher font"
\"Choose the font used in the Dasher canvas
\"
\".IP "Dasher font size"
\"Choose the size of the font used in the Dasher canvas
\"
\".IP "Reset fonts"
\"Reset the fonts back to the defaults
\"
\".IP "Enter text into other windows"
\"Make Dasher enter text into the currently focused window. Requires Dasher to
\"have been built with
\".B--with-a11y.
\"Note that some languages will only work correctly if XFree 4.0.2 or higher is
\"being used.
\"
\".IP "Control mode"
\"Provides a control node at the bottom of the screen. This allows various tasks
\"to be performed inside Dasher, such as editing the text written, speaking
\"entered text and stopping or pausing Dasher. If compiled with
\".B--with-a11y
\"and using a desktop supporting the ATK accessibility framework, compliant
\"applications will have their menu trees exported to Dasher and these may be
\"accessed via this node.
.SS Help
.IP "About Dasher"
Display information about the current version of Dasher
.SH THE PREFERENCES DIALOG
The preferences dialog is split into several panes.
.SS Alphabet
Choose a different alphabet. Dasher will automatically retrain itself if the
alphabet specified training file is present
alphabet specified training file is present.
.SS Colour
Choose a different colour scheme.
.SS Control
Alter various control options
.IP "One dimensional mode"
Map the Y position of the mouse to a 2 dimensional position on the Dasher
canvas (useful for limited mobility users)
.IP "Eyetracker mode"
Similar to one dimensional mode, but behaves normally except at the right-hand
side of the canvas. Designed for eyetracker users.
.IP "Start on left mouse button"
The left mouse button will toggle Dasher between running and paused state
.IP "Start on space bar"
The space bar will toggle Dasher between running and paused state
.IP "Start with mouse position"
When paused, Dasher will display a red box. If the pointer is held in the red
box until a yellow box appears, and then in the yellow box until it vanishes,
Dasher will start. This allows users with no button input to start and stop
Dasher.
.IP "Copy all on stop"
Toggle whether the current text is automatically copied to the clipboard when
Dasher is stopped
.IP "Speak on stop"
Toggle whether the newly entered text should be spoken when Dasher is stopped.
Requires
.B --with-speech
to have been used during Dasher configuration and building.
.IP "Pause outside window"
Toggle whether Dasher pauses if the mouse cursor is moved outside the Dasher
window
.SS View
.IP Orientation
Change the relative position of the letters to the crosshairs.
.B Alphabet Default
will allow alphabets to set this automatically.
.IP "Show toolbar"
Toggle whether or not the row of buttons at the top of the window is displayed
.IP "Show speed slider"
Toggle whether or not the speed slider at the bottom of the window is displayed
.IP "Show mouse position"
Toggle whether Dasher should draw a box showing the logical position of the
mouse cursor
.IP "Draw line between crosshairs and mouse"
Toggle whether Dasher should draw a line between the crosshairs and the logical
mouse position
.IP "Draw box outlines"
Toggle whether Dasher should draw a box outline around every box it draws
.IP "Change colour scheme automatically"
Alphabets may provide a preferred colour scheme. If this option is enabled,
Dasher will automatically change to it.
.SS Advanced
.IP "Smoothing"
The greater the smoothing value, the greater the uniformity of the box sizes.
This will reduce the predictive capabilities of Dasher, and so may reduce
writing speed.
.IP "Timestamp new files"
Include the time at which a file is saved in the filename
.IP "Distance from centreline for start on mouse position"
Controls the distance from the centre of the Dasher screen that the mouse
position start boxes will appear.
.IP "Number of pixels that should cover the entire y range"
Controls how many pixels of input should correspond to complete coverage of
the Dasher canvas. Only used in one dimensional mode.
\" .IP "Start on left mouse button"
\" The left mouse button will toggle Dasher between running and paused state
\"
\" .IP "Start on space bar"
\" The space bar will toggle Dasher between running and paused state
\"
\" .IP "Start with mouse position"
\" When paused, Dasher will display a red box. If the pointer is held in the red
\" box until a yellow box appears, and then in the yellow box until it vanishes,
\" Dasher will start. This allows users with no button input to start and stop
\" Dasher.
\"
\" .IP "Copy all on stop"
\" Toggle whether the current text is automatically copied to the clipboard when
\" Dasher is stopped
\"
\" .IP "Speak on stop"
\" Toggle whether the newly entered text should be spoken when Dasher is stopped.
\" Requires
\" .B --with-speech
\" to have been used during Dasher configuration and building.
\"
\" .IP "Pause outside window"
\" Toggle whether Dasher pauses if the mouse cursor is moved outside the Dasher
\" window
\" .SS View
\"
\" .IP Orientation
\" Change the relative position of the letters to the crosshairs.
\" .B Alphabet Default
\" will allow alphabets to set this automatically.
\"
\" .IP "Show toolbar"
\" Toggle whether or not the row of buttons at the top of the window is displayed
\"
\" .IP "Show speed slider"
\" Toggle whether or not the speed slider at the bottom of the window is displayed
\"
\" .IP "Show mouse position"
\" Toggle whether Dasher should draw a box showing the logical position of the
\" mouse cursor
\"
\" .IP "Draw line between crosshairs and mouse"
\" Toggle whether Dasher should draw a line between the crosshairs and the logical
\" mouse position
\"
\" .IP "Draw box outlines"
\" Toggle whether Dasher should draw a box outline around every box it draws
\"
\" .IP "Change colour scheme automatically"
\" Alphabets may provide a preferred colour scheme. If this option is enabled,
\" Dasher will automatically change to it.
\"
\" .SS Advanced
\"
\" .IP "Smoothing"
\" The greater the smoothing value, the greater the uniformity of the box sizes.
\" This will reduce the predictive capabilities of Dasher, and so may reduce
\" writing speed.
\"
\" .IP "Timestamp new files"
\" Include the time at which a file is saved in the filename
\"
\" .IP "Distance from centreline for start on mouse position"
\" Controls the distance from the centre of the Dasher screen that the mouse
\" position start boxes will appear.
\"
\" .IP "Number of pixels that should cover the entire y range"
\" Controls how many pixels of input should correspond to complete coverage of
\" the Dasher canvas. Only used in one dimensional mode.
.SH CONVERTING TRAINING FILES TO UTF-8
Dasher requires that training files be in the UTF-8 format, whereas most text
files are likely to be in ISO-8859 format. This doesn't matter for plain text,
but accented characters are encoded differently. In order to convert them, use
......@@ -231,38 +227,34 @@ the
.BR iconv (1)
program. For instance, if your training file is in ISO-8859-1 format (Western
European), run
.B iconv -f ISO-8859-1 -t UTF-8 trainingfile >newtrainingfile
.SH FILES
.I /usr/share/dasher/
.RS
System-wide configuration files
.RE
.I ~/.dasher
.RS
User configuration files
.RE
.B dasher
will utilise data from both of these directories. Training texts from both will
be used, allowing users to add their own training data to the system wide data
.I alphabet*.xml
.RS
The files defining the alphabets available to Dasher
.RE
.I colour*.xml
.RS
The files defining the colour schemes available to Dasher
.RE
.I train*txt
.RS
Files containing the training data used by Dasher. These are UTF-8 encoded
text and should contain a representative sample of the relevant language.
.TP
.B DOCDIR
Directory containing system-wide configuration files.
.TP
.B ~/.dasher
Directory containing user specific configuration files.
.PP
.B Dasher
will utilise files of the following form from both of these directories:
.TP
.RI alphabet. ALPHABET .xml
The files defining the alphabets available to Dasher.
.TP
.RI colour. SCHEME .xml
The files defining the colour schemes available to Dasher.
.TP
.RI training_ LANGUAGE* .txt
Files containing the training data used by Dasher.
These are UTF-8 encoded text and should contain a representative
sample of the relevant language.
User specific training files can be used to augment system wide data.
.PP
Refer to the Dasher manual for more information regarding the format
and editing of these files.
.SH AUTHOR
The Dasher Project <dasher@mrao.phy.cam.ac.uk> -
http://www.inference.phy.cam.ac.uk/dasher/
The Dasher Project <dasher@mrao.phy.cam.ac.uk>.
.SH SEE ALSO
The Dasher project web page is
.URL http://www.inference.phy.cam.ac.uk/dasher/
......@@ -1131,7 +1131,9 @@ void CDasherInterfaceBase::EnterState(EState iState) {
}
int CDasherInterfaceBase::AddLock(const std::string &strDisplay) {
#ifdef DEBUG
std::cout << "Adding lock " << strDisplay << std::endl;
#endif
SLockData sNewLock;
sNewLock.strDisplay = strDisplay;
......@@ -1149,7 +1151,9 @@ int CDasherInterfaceBase::AddLock(const std::string &strDisplay) {
}
void CDasherInterfaceBase::ReleaseLock(int iLockID) {
#ifdef DEBUG
std::cout << "Releasing Lock" << std::endl;
#endif
std::map<int, SLockData>::iterator it = m_mapCurrentLocks.find(iLockID);
if(it != m_mapCurrentLocks.end()) {
......@@ -1192,9 +1196,11 @@ void CDasherInterfaceBase::SetControlOffset(int iOffset) {
m_pDasherModel->SetControlOffset(iOffset);
}
void CDasherInterfaceBase::ClSet(const std::string &strKey, const std::string &strValue) {
// Returns 0 on success, an error string on failure.
const char* CDasherInterfaceBase::ClSet(const std::string &strKey, const std::string &strValue) {
if(m_pSettingsStore)
m_pSettingsStore->ClSet(strKey, strValue);
return m_pSettingsStore->ClSet(strKey, strValue);
return 0;
}
......
// DasherInterfaceBase.h
//
// Copyright (c) 2007 The Dasher Team
// Copyright (c) 2008 The Dasher Team
//
// This file is part of Dasher.
//
......@@ -362,9 +362,9 @@ public:
void SetControlOffset(int iOffset);
/// Set a key value pair by name - designed to allow operation from
/// the command line
/// the command line. Returns 0 on success, an error string on failure.
///
void ClSet(const std::string &strKey, const std::string &strValue);
const char* ClSet(const std::string &strKey, const std::string &strValue);
void ImportTrainingText(const std::string &strPath);
......
......@@ -2,7 +2,7 @@
//
/////////////////////////////////////////////////////////////////////////////
//
// Copyright (c) 2002 Iain Murray
// Copyright (c) 2008 Iain Murray
//
/////////////////////////////////////////////////////////////////////////////
......@@ -69,30 +69,39 @@ void CSettingsStore::LoadPersistent() {
}
void CSettingsStore::ClSet(const std::string &strKey, const std::string &strValue) {
// Return 0 on success, an error string on failure.
const char * CSettingsStore::ClSet(const std::string &strKey, const std::string &strValue) {
for(int i(0); i < NUM_OF_BPS; ++i) {
if(strKey == s_oParamTables.BoolParamTable[i].regName) {
if(strValue == "0")
if ((strValue == "0") || (strValue == _("true")))
SetBoolParameter(s_oParamTables.BoolParamTable[i].key, false);
else if(strValue == "1")
else if((strValue == "1") || (strValue == _("false")))
SetBoolParameter(s_oParamTables.BoolParamTable[i].key, true);
return;
else
// Note to translators: This message will be output for a command line
// with "--options foo=VAL" and foo is a boolean valued parameter, but
// "VAL" is not true or false.
return _("boolean value must be specified as 'true' or 'false'.");
return 0;
}
}
for(int i(0); i < NUM_OF_LPS; ++i) {
if(strKey == s_oParamTables.LongParamTable[i].regName) {
SetLongParameter(s_oParamTables.LongParamTable[i].key, atoi(strValue.c_str()));
return;
return 0;
}
}
for(int i(0); i < NUM_OF_SPS; ++i) {
if(strKey == s_oParamTables.StringParamTable[i].regName) {
SetStringParameter(s_oParamTables.StringParamTable[i].key, strValue);
return;
return 0;
}
}
// Note to translators: This is output when command line "--options" doesn't
// specify a known option.
return _("unknown option, use \"--help-options\" for more information.");
}
......
......@@ -2,7 +2,7 @@
//
/////////////////////////////////////////////////////////////////////////////
//
// Copyright (c) 2002 Iain Murray
// Copyright (c) 2008 Iain Murray
//
/////////////////////////////////////////////////////////////////////////////
......@@ -63,7 +63,7 @@ public:
void LoadPersistent();
void ClSet(const std::string &strKey, const std::string &strValue);
const char *ClSet(const std::string &strKey, const std::string &strValue);
// --- Deprecated functions below
// although string functionality might be good for
......
......@@ -505,34 +505,75 @@ gboolean dasher_app_settings_get_module_settings(DasherAppSettings *pSelf, const
return gtk_dasher_control_get_module_settings(GTK_DASHER_CONTROL(pDasherWidget), szValue, pSettings, iCount);
}
void
// Set the option szKey to szValue. Return NULL if everything worked, a
// (literal) error string for unrecognized or illegal values.
const gchar *
dasher_app_settings_cl_set(DasherAppSettings *pSelf, const gchar *szKey, const gchar *szValue) {
for(int i(0); i < NUM_OF_APP_BPS; ++i ) {
if(!strcmp(app_boolparamtable[i].regName, szKey)) {
if(!strcmp(szValue, "1"))
dasher_app_settings_set_bool(pSelf, app_boolparamtable[i].key, true);
else if(!strcmp(szValue, "0"))
dasher_app_settings_set_bool(pSelf, app_boolparamtable[i].key, false);
if(!strcmp(szValue, "1") || !strcmp(szValue, _("true")))
dasher_app_settings_set_bool(pSelf, app_boolparamtable[i].key, true);
else if(!strcmp(szValue, "0") || !strcmp(szValue, _("false")))
dasher_app_settings_set_bool(pSelf, app_boolparamtable[i].key, false);