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 +++++++++++++++++++------------------------------------------ 1 file changed, 29 insertions(+), 63 deletions(-) (limited to 'README.adoc') 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, -- cgit v1.2.3-70-g09d2