Welcome to ODict! This should tutorial will get you up and running with your first dictionary. By the end of this quickstart, you’ll know how to run ODict, write your own dictionaries, compile them, and look up words!
Let’s get started.
Until we can better cross-compile the ODict binary, the best way to install ODict is directly from Go. Make sure you have installed the latest version of Go, then just run the following in your terminal:
go install github.com/TheOpenDictionary/odict@latest
There is a small chance you may have to add the following to your shell configuration if your
GOPATH is not currently part of your
export PATH="$(go env GOPATH)/bin:$PATH"
You can ensure ODict is installed by running the following command:
Open up your favorite text editor and paste the following XML into a file called
<dictionary name="My First Dictionary"> <entry term="hello"> <ety> <usage pos="intj"> <definition value="Hello world!"> <example>All programmers greet each other by announcing "Hello world!"</example> </definition> </usage> </ety> </entry> </dictionary>
So, what’s happening here?
- We are defining our top-level dictionary with a
<dictionary>tag. There should only ever be one of these per file.
- We are defining an entry for the term “hello”. The
termattribute is case-sensitive and used to look up words once the dictionary is compiled.
- Our entry contains an etymology (abbreviated
ety). Etymologies refer to the origin of a word (such as example stemming from the Latin word eximere, meaning “to take out”). Every
entryneeds at least one etymology.
- Inside the etymology are usages. Usages, often referred to a word senses, refer to the usage of a word. For example, “run” can be used as both a noun and a verb (“I just came back from a run” vs. “walk, don’t run”). Usages can specify a part-of-speech (POS) tag. In this case, we are specifying that “hello” is an interjection (
- Usages contain definitions. Definitions are the meanings of words, as associated with their part-of-speech. In this case, we’re defining “hello” to be short for “Hello world!“.
- Lastly, definitions can contain examples to illustrate how you might use a word in a sentence.
Now that we have our dictionary file written, let’s compile it!
Compiling your new dictionary is super straightforward – it’s just one command.
Open your terminal in your current directory, and run the following:
odict compile mydictionary.xml
You’ll notice you now have a new file in your directory:
mydictionary.odict. Congrats, you just compiled your first dictionary!
Now comes the fun part – looking up words. To look up words in your compiled dictionary, just run the following command:
odict lookup mydictionary.odict "hello"
You should now see something that looks like the following in your terminal:
For a more machine readable format, you can even output JSON by adding
-f json right after
odict lookup -f json mydictionary.odict "hello"
Woo-hoo! You did it. Give yourself a good pat on the back!