Improve documentation
This commit is contained in:
parent
55d0f53f7a
commit
973d1d27ea
GPG Key ID:
A0420B94F92B9493
92
README.adoc
92
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,
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
Loading…
Reference in New Issue