GNOME Bugzilla – Bug 496872
dasher man page very out of date
Last modified: 2021-05-26 09:58:10 UTC
The manpage Doc/user/dasher.1.in seems very out of date Dasher seems to only take two options (-a and -o), however the manpage seems to say it supports -o, -p, -s, -w. The -o option in the manpage seems different than the actual -o option. Also, this manpage seems to try and describe the menus and preferences. I'm not sure this is really useful since dasher is well described in Help->Contents, which is probably where people would look for this sort of information. I'd recommend that these sections be removed from the manpage. Even if you decide to keep them, they are out of date and describe options that don't exist and the tabs of the preferences dialog are all different than described in the manpage. In the FILES section, it seems a bit unclear to me. It says: FILES /usr/share/dasher/ System-wide configuration files ~/.dasher User configuration files These should read "directory containing configuration files.". The way it reads makes it sound like these are files. I assume that the alphabet*.xml, colour*xml, and train*txt files go in the system-wide configuration or user configuration directory, but this isn't really clear. Perhaps something could be mentioned about this? And it isn't clear how the * expands. In other words, does the * expand to a locale? Also, the manpage describes a lot of information about training files, but doesn't really explain what a training file is or what it is used for. It might be good if a brief description of what training files are were put before information about training files need to be in UTF-8 format, etc.
Created attachment 106161 [details] [review] Bring man page more up to date. Description of menu's still present. This patch properly describes the program options, and partly clarifies the configuration directory and filename issues raised in the summary. I'm not sure the best way to describe the configuration files themselves (I replaced the "*" with a NAME). My installation of dasher doesn't properly install the help pages, so I can't (yet) comment on whether the menu descriptions should be left in place. This patch makes some minor changes to them, but with the expectation that they will be deleted I didn't work them over very much.
Looks much better. It isn't clear to me if the manpage is suggesting that users might want to edit the configuration files (alphabet, colour, training) by hand. If so, then it might be nice to explain the format of the files in a bit more detail. Or is the intent that these files are not edited by hand, and only are edited by changing preferences in dasher itself? If the intent that they are not edited by hand, then this should be explained in the manpage. The -a option takes many different arguments (compose, traditional, etc.). Would be nice if these were explained in more detail. What is the difference between compose, direct, fullscreen and traditional, for example? How do I know which one I want to use? You say -o option "Overrides stored options", but it isn't really clear to me what this does. Overrides them with what? The patch says: +After startup, Dasher will present the user with a window containing +two major! sections. Why the "!" after major? It then says: +The top portion is the \fIedit box\fR - 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. This isn't always true, is it? I think if you start with various -a options, the format of the window is different. I don't think the "top portion" is shown at all in direct mode, for example. Might be good to explain this. Since dasher is a bit complicated to learn to use (in my opinion), might be handy to refer the reader to the user documentation, and perhaps any docs at the dasher website for more information to learn how to use it.
*** Bug 415711 has been marked as a duplicate of this bug. ***
(In reply to comment #2) > Looks much better. Sorry for the long delay getting back to you. I neglected to CC myself on this bug and just noticed that you had made comments. And, just for the record, I'm probably the last person who should be updating the man page, I'm highly ignorant of dasher operation. > It isn't clear to me if the manpage is suggesting that users might > want to edit the configuration files (alphabet, colour, training) by > hand. If so, then it might be nice to explain the format of the > files in a bit more detail. > Or is the intent that these files are not edited by hand, and only > are edited by changing preferences in dasher itself? If the intent > that they are not edited by hand, then this should be explained in > the manpage. It appears to me that the alphabet and colour files are not expected to be edited by anyone. I don't know for sure, but I think the colour files in the user's directories will be updated by dasher. The training text is something the users do something with, but I don't understand what or how. > The -a option takes many different arguments (compose, traditional, > etc.). Would be nice if these were explained in more detail. What > is the difference between compose, direct, fullscreen and > traditional, for example? How do I know which one I want to use? I've used traditional and I can get direct to start, but I can't figure out how to get it to send text to anywhere. compose and fullscreen coredump on my system. > You say -o option "Overrides stored options", but it isn't really > clear to me what this does. Overrides them with what? The valid options appear to be specified in the structure definitions in the AppSettingsData.h file. My suggestion here is to not replicate this information in the man page, but rather add a "--help options", or something similar and have the options dumped. In either case the existing option settings will need a bit more documentation to make them understandable. Also, there is currently no error checking on the option names, and when you set a boolean option to something other than 0 or 1 dasher core dumps. Ouch! It also appears, from the code, that a filename is a legal argument, but it doesn't appear to work. > The patch says: > > +After startup, Dasher will present the user with a window containing > +two major! sections. > > Why the "!" after major? My bad. > It then says: > > +The top portion is the \fIedit box\fR - text > +entered via Dasher will appear here, and the text may also be edited > +directly. > > This isn't always true, is it? I think if you start with various -a options, > the format of the window is different. I don't think the "top portion" is > shown at all in direct mode, for example. Might be good to explain this. It sounds like you are considerably more knowledgeable about dasher operation than I, and my installation (ubuntu) and my local mods always core dump on the other -a options. If you propose some text, I'll work it into man page format. > Since dasher is a bit complicated to learn to use (in my opinion), > might be handy to refer the reader to the user documentation, and > perhaps any docs at the dasher website for more information to learn > how to use it. Perhaps add the Inference web to the "SEE ALSO" section?
Created attachment 106569 [details] Proposed help text for option strings. I hacked together a function that will output the current options. Let me know if this is worth adding to the source, and if so, then I'll submit a patch with proper option processing and such. Many of the options don't really have good descriptions, but at least it is a start.
I'm afraid that I don't really understand dasher well enough to further improve the manpage. I just had questions about how it works. It would be good if someone who understands it better could answer.
Ok Brian. I didn't mean to dump on you, just trying to make progress. Please keep reviewing my changes. Your feedback is very helpful. Perhaps together we can get something reasonable. My proposal is to 1. Delete the user interface documentation and expect that online help will be enough for that. 2. Add a "--help-options" option that generates the text similar to attachment 106569 [details]. 3. Add back the description of a "filename" argument. Its in the code, it just doesn't work currently. 4. Add some additional references of some sort for where to find additional information. If this seems generally the right direction, I'll submit a patch, for review.
I notice section 5 of the yelp document (when I go to dasher and run Help->Contents) seems to claim that users are intended to customize the language/alphabet/colour files. Might be useful to take some of this information and put it in the man page. I don't see any information in the help docs regarding how to use the various -a options, though.
Created attachment 106782 [details] [review] Update manpage, add "--options-help" command line option. Brian, please look this over. I realize its not the best it could be, but unless you find a defect with it, I'm going to ask Phil to review and commit the changes. I'm just having no luck getting to the online documentation. I even tried installing dasher on windows, and after download I get "not a windows executable". I think my time would be better spent fixing some of the crashes, so I'm going to suspend work on this for a while.
Yes, I think fixing the various crasher bugs so that the various --appstyle arguments don't crash is probably more important. :) That said, I would remove the text about the top part being where the text goes. I don't think this area of the screen is supposed to show up in all --appstyle options. For example, I think the idea behind running with the -direct option is that 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. Otherwise you'ld have to copy-paste the text from dasher into the program you actually want to type into. In other words, the default way of running dasher isn't the most useful for people with disabilities. At least that is my understanding. This bug report seems to confirm this: https://lists.ubuntu.com/archives/ubuntu-accessibility-devel/2007-April/000595.html The "fullscreen" mode is obviously to try and run dasher in fullscreen mode. I'm not sure what compose is for You say you have trouble reading the docs. It works on Solaris for some reason. This is what it says about the files in the FILES section of the manpage. Perhaps some of this text explaining the format of the files would be useful to mention in the manpage: 5.1. Personalizing the language model Dasher's predictions (in version 3 of Dasher) are based not on a dictionary but on a training text of ordinary text. For example, when you download Dasher version 3, it comes with a file called training_english_GB.txt. This is 300 kbytes of ordinary english harvested from various documents on the internet. When you use Dasher, it stores everything you write in another personal file with the same name as the training file. Next time you use Dasher, it reads in the original training file and everything you wrote last time, to help it predict better. Dasher learns all the time. To get the best results from Dasher: * If possible, provide Dasher with a training text in your own style -- a plain text file made from documents you have written before, and containing your own pet phrases, friends' names, and so forth. Either append this file to the training file, or replace the original training file. * If you think your personal training file may have become corrupted with rubbish text, edit it using any plain text editor. (Or ask a friend to do this for you.) * If you use Dasher for many months, the personal training file may become so large that Dasher becomes slow to start up; if so, edit the training file using a plain text editor. 5.2. Personalizing the alphabet Which characters are available to you, and their order, is determined by the alphabet file. For example, you might use alphabet.english.xml. Dasher comes with many alternative alphabets. You can edit alphabet files to change which characters are in the alphabet, or their order. When you edit this xml file, it might be a good idea to save the new file with a new name and change the name of the alphabets in the new file, to avoid confusion. Each field in the xml file specifies a symbol by three items: the character that should be displayed (d=...); the character that goes into the text when this symbol is selected (t=...); and the background colour number of the box for this symbol (b=...), of which more below. 5.3. Personalizing the colour scheme You can change the colours of the Dasher world in two ways. The colour file (for example colour.xml or colour.euroasian.xml) specifies the 200 colours in the palette that Dasher uses. Each line specifies red, green, blue values. These colours are used to colour multiple objects in dasher. If for example you want to change the colour of the “red line”;, change the second colour line of the colour file, which reads <colour r="255" g="0" b="0"/>. You can change which of these colours is used for each symbol's box by changing the “b”; field for that symbol in the alphabet file.
Created attachment 106843 [details] updated dasher.1.in (superceeds just that file from the previous patch). Brian, here is an updated man page. I did not replicate the text describing the file options (I'm not a big fan of duplication), but I'm willing to go with whatever you think is appropriate on this topic. For now I just added "see online help".
Looks reasonable. One comment. You say "on-line" help. However, it is also available by just running Help->Contents from the menu (at least it does on Solaris). Perhaps you could say more simply, "Refer to the Dasher manual for more information". Otherwise, it is definately a big improvement over what was before. I would recommend updating the existing manpage with this one. Probably should leave the bug report open, though, in case others have more ideas of how to further improve it.
Applied attachment 106843 [details] plus some additional cleanup as r3471.
GNOME is going to shut down bugzilla.gnome.org in favor of gitlab.gnome.org. As part of that, we are mass-closing older open tickets in bugzilla.gnome.org which have not seen updates for a longer time (resources are unfortunately quite limited so not every ticket can get handled). If you can still reproduce the situation described in this ticket in a recent and supported software version, then please follow https://wiki.gnome.org/GettingInTouch/BugReportingGuidelines and create a new enhancement request ticket at https://gitlab.gnome.org/GNOME/dasher/-/issues/ Thank you for your understanding and your help.