aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--README.adoc92
-rw-r--r--docs/sdtui.1.adoc71
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)