From 973d1d27ea776a902eb1bf85e645181eb389d7a9 Mon Sep 17 00:00:00 2001 From: Přemysl Eric Janouch Date: Thu, 7 Oct 2021 20:08:56 +0200 Subject: Improve documentation --- README.adoc | 92 ++++++++++++++++++------------------------------------- docs/sdtui.1.adoc | 71 +++++++++++++++++++++++++++++++++++------- 2 files changed, 89 insertions(+), 74 deletions(-) diff --git a/README.adoc b/README.adoc index 724c7e8..1c94dd9 100644 --- a/README.adoc +++ b/README.adoc @@ -8,26 +8,20 @@ of this kind, GUI or not, and thus decided to write my own. The project is covered by a permissive license, unlike vast majority of other similar projects, and can serve as a base for implementing other dictionary -software. I wasn't able to reuse _anything_ for StarDict. +software. image::sdtui.png[align="center"] -Further Development -------------------- -While I've been successfully using sdtui for a long time now, some work has to -be done yet before the software can be considered fit for inclusion in regular -Linux and/or BSD distributions. Help is much appreciated. - -An approximate list of things that need to be resolved: - - - the tab bar and the text input field don't handle overflows well - - figure out a way to become capable of displaying most StarDict dictionaries - Packages -------- Regular releases are sporadic. git master should be stable enough. You can get a package with the latest development version from Archlinux's AUR. +Documentation +------------- +See the link:docs/sdtui.1.adoc[man page] for information about usage. +The rest of this README will concern itself with externalities. + Building and Running -------------------- Build dependencies: CMake, pkg-config, asciidoctor + @@ -49,67 +43,39 @@ Or you can try telling CMake to make a package for you. For Debian it is: $ cpack -G DEB # dpkg -i sdtui-*.deb -Having the program installed, simply run it with a StarDict '.ifo' file as an -argument. It is however highly recommended to configure it, see below. - -Extensions ----------- -As the original StarDict is a bit of a clusterfuck with regard to collation of -dictionary entries, I had to introduce an additional `collation` field into the -'.ifo' file. When sdtui discovers this field while reading the dictionary, it -automatically reorders the index according to that locale (e.g. "cs_CZ"). -This operation may take a little while, in the order of seconds. - -Configuration -------------- -To get a nicer look in 256color terminals, create _~/.config/sdtui/sdtui.conf_ -with the following. Note that it is intended for black-on-white terminals. - -.... -[Settings] -center-search = true -underline-last = false -hl-common-prefix = true -watch-selection = true - -[Colors] -header = reverse -header-active = ul -search = ul -even = 16 231 -odd = 16 255 -.... - -The `watch-selection` option makes the application watch the X11 primary -selection for changes and automatically search for selected text. This feature -requires XCB. Wayland is currently unsupported, but would require a compositor -supporting the wlr-data-control protocol. Luckily, some compositors, such as -Sway, synchronize selections with Xwayland. - -You can also set up some dictionaries to be loaded at startup automatically: - -.... -[Dictionaries] -name1 = ~/path/to/dict.ifo -name2 = ~/another/dict.ifo -.... - -The names define how they will appear in the tab bar. +Having the program installed, simply run it with a StarDict '.ifo' file as +an argument. It is, however, preferable to +link:docs/sdtui.1.adoc#_configuration[configure it] to load your dictionaries +automatically. Dictionaries ------------ -Unfortunately this application only really works with specific dictionaries. +Unfortunately, this application only really works with specific dictionaries. Word definitions have to be in plain text, separated by newlines. The `make dicts` command will build some examples from freely available sources. -You may use the included transform tool to transform existing dictionaries that -are almost useful as they are, e.g. after stripping XML tags. You might want to -fix up the `sametypesequence` of the resulting '.ifo' file afterwards, and run -dictzip on the resulting '.dict' file. +You may use the included 'transform' tool to convert already existing +dictionaries that are almost good as they are, e.g., after stripping XML tags. +You might want to fix up the `sametypesequence` of the resulting '.ifo' file +afterwards, and run 'dictzip' on the resulting '.dict' file to make it compact. https://mega.co.nz/#!axtD0QRK!sbtBgizksyfkPqKvKEgr8GQ11rsWhtqyRgUUV0B7pwg[CZ <--> EN/DE/PL/RU dictionaries] +Further Development +------------------- +While I've been successfully using 'sdtui' for many years now, some work has to +be done yet before the software can be considered fit for inclusion in regular +Linux and/or BSD distributions. + +An approximate list of things that need to be resolved is as follows: + + - the tab bar and the text input field don't handle overflows well, + - figure out a way to become capable of displaying most StarDict dictionaries. + +Given the entangledness of this codebase, issues with the file format, +and general undesirability of terminal UIs, it might be better to start anew. + Contributing and Support ------------------------ Use https://git.janouch.name/p/sdtui to report any bugs, request features, diff --git a/docs/sdtui.1.adoc b/docs/sdtui.1.adoc index af5e62d..0292271 100644 --- a/docs/sdtui.1.adoc +++ b/docs/sdtui.1.adoc @@ -14,16 +14,13 @@ Synopsis Description ----------- -*sdtui* is a StarDict dictionary viewer custom tailored for viewing translation -dictionaries, using a simple curses-based terminal UI. +*sdtui* is a StarDict dictionary viewer, custom-tailored for translation +dictionaries, with a simple curses-based terminal UI. -The program expects to find on its command line the path to a dictionary's -_.ifo_ file, which contains further information required to load the dictionary. - -Some options as well as dictionaries to load on start-up by default can be -specified in a configuration file. See the README for an example. - -// FIXME: the README isn't even installed, so this manual isn't very useful +Without any command line arguments, the program expects to find a list of +dictionaries to load on start-up in its configuration file. The _.ifo_ files +contain information required to load dictionaries from their accompanying +database files. Options ------- @@ -33,13 +30,65 @@ Options *-V*, *--version*:: Output version information and exit. +Configuration +------------- +You can start your _sdtui.conf_ file with the following snippet: + + [Settings] + center-search = true # Ensure visibility of preceding entries? + underline-last = false # Underline the last line of entries? + hl-common-prefix = true # Highlight the longest common prefix? + watch-selection = true # Watch X11 selection for changes? + +The _watch-selection_ option makes the application watch the X11 PRIMARY +selection for changes and automatically search for any selected text. +This feature requires XCB. Wayland is currently unsupported, +but would require a compositor supporting the wlr-data-control protocol. +Luckily, some compositors, such as Sway, synchronize selections with Xwayland. + +To set up automatically loaded dictionaries, use the following scheme: + +[subs="normal"] + [Dictionaries] + _name 1_ = __~/path/to/dict.ifo__ + _name 2_ = __~/another/dict.ifo__ + +The left-hand side keys define their appearance in the tab bar. + +Finally, to make the program look nicer in 256color black-on-white terminals, +rather than rely on the universal default, try: + + [Colors] + header = reverse + header-active = ul + search = ul + even = 16 231 + odd = 16 255 + +Terminal attributes are accepted in a format similar to that of *git-config*(1), +only named colours aren't supported. + +Extensions +---------- +Because the StarDict file format is a bit of a clusterfuck with regard to +collation of dictionary entries, this software introduces an additional, +optional "collation" field into the '.ifo' file. When *sdtui* discovers this +field while reading a dictionary, it automatically reorders the index according +to that locale (e.g., "cs_CZ"). This operation may take a little while, +in the order of seconds. + Files ----- +*sdtui* follows the XDG Base Directory Specification. + _~/.config/sdtui/sdtui.conf_:: - The configuration file, in which you can configure some settings, terminal - colours and the set of dictionaries to be loaded automatically on start-up. + The configuration file. Reporting bugs -------------- Use https://git.janouch.name/p/sdtui to report bugs, request features, or submit pull requests. + +See also +-------- +*dictzip*(1) -- cgit v1.2.3-70-g09d2