Language/Multiple-languages/Culture/Numeration-Tutorial

Finally, the first version of the Numeration tool is released! This version will allow you to practise Chinese, English, Esperanto, German and Japanese numerals! More languages to come...

An overhaul is underway. It will take some time. I know that the current public version has some mistakes like plural of “percent”. I just need some spare time.

If you are interested in providing hard-to-find information, please leave a comment.

What is the Numeration tool?

This tool will help you practise reading, writing (hopefully also listening and speaking) numbers, written in Python and YAML.

The Numeration project is for practising conversion of numbers between symbols and writing systems.

Address: https://gitlab.com/GrimPixel/Numeration

NB: It would be ridiculous to post this tutorial on GitLab, because this tutorial's target readers are non-programmers, so it is too detailed for programmers.

What are Python and YAML and why choose them?

Python

Python is one of the most favoured languages.

Why not Rust or TypeScript, but Python? Well, because Python codes are very easy to maintain, Python also has some unique useful features including f-string and negative indexing. In addition, Python has a lot of scientific libraries, so it is more relevant to my main area of study.

YAML

YAML is one of the most useful data serialization formats.

And why not JSON or TOML, but YAML? Because YAML has a high readability and is very easy to maintain, at least no need to type soo many quotation marks.

By the way, XML is not that horrible as described in that linked page. That is a joke with escape characters.

How to get started with Numeration?

1. Download the latest Python (or theoretically any Python 3 version) and install it, so you can run Python programs. For Linux users, the latest version can be installed following this article.

2. Download Python's YAML parser, so that Python interpreter of the default version can understand YAML. If you are using Windows, tap WinKey, input "cmd", tap Enter, so the command line is opened. Copy the line starting with "pip" in that webpage, paste into the command line window, tap Enter. For users of other operating systems, you should already have known how to open the command line of your system, I suppose.

(Optional) 3. Download PyCharm, an integrated development environment (IDE), and install it, so you have a graphical user interface (GUI) to edit the code or run it with the font configuration. Alternative: Pyzo.

They are all open-source.

If a newer version of Python is available and you want to use that version, you need to install packages like ruamel.yaml for the new versions again. This is how Python works: users can have different versions with different packages and settings.

After doing this, go to that Address above. Download the source code and extract the compressed file.

With step 3: Open PyCharm, open the project directory, open 'numerate.py'. You can go to “File -> Settings -> Editor -> Font” to change the font and its size. Tap "Ctrl + Shift + F10" to run the code in current tab. Tap "Shift + F10" to run the code in the file specified on the upper-right corner.

Without step 3: Use command line to open 'numerate.py': For Windows, there is an article about this; for users of other operating systems, you should have known how to do this. Type 'python numerate.py', it will run in the command line.

You can go to 'rule/library/setting.yaml' and change the settings following the comment.

If you are using Linux and the latest Python is not available in the repository

Though theoretically any version of Python 3 is good to use, you may want to manually download and install the latest Python as described in this article. The version needs to be specified like “pip3.9”, so the operating system won't call the default old one and install packages for the old version. When the project is opened in PyCharm, go to "File -> Settings -> Project: Numeration -> Python Interpreter -> Python Interpreter -> Show All -> + (Add)", select "Existing Environment", make sure it is the latest version.

If the interpreter in your PyCharm doesn't recognise “ruamel.yaml”

Go to “File -> Settings -> Project: Numeration -> Python Interpreter”, click on that “+”, find “ruamel.yaml”, select it and click on “Install Package”.

Why choose Apache 2.0?

I want to let people use this even commercially, e.g. in language-learning games like Influent. Thus I need a permissive license. You may ask why not public domain. There are some countries where people cannot put their work in public domain, None of the current 3 public domain licenses is not friendly to commercial use.

MIT is good, but there is a problem: it doesn't explain how to deal with patents and trade marks. This allows patent trolls to sue those who use the code commercially without knowing that it contains patent. When the MIT license came into being, there were no many software patent issues, so the license can be called outdated.

A guy named Lawrence E. Rosen created the Academic Free License to deal with this issue and this idea was incorporated into Apache 2.0, a better alternative.

Explain the code?

The main program is “numerate.py”. It reads your selected language codes, read the language settings (rule/library/setting.yaml), then read your subject (mathematical numeral, ordinal number, nominal number, date and time) selection number, then read the notation, convert it to Western Arabic, then call the language's “.py” file and show the result, finally ask you what to do next (do again from a step or end).

In the language “.py” files, everything is in a function “do”, so it can be called from another file (numerate.py) easily. They read the notation and the language setting as part of the input of the function “do”, then read the corresponding lexicon YAML file. Then the notation will be processed according to different notation types.

There are something to be noticed like the magnitude and archmagnitude.

Take the cardinal number 987654321 as an example:

• digit grouping: 3 (European)

	9	8	7	6	5	4	3	2	1
magnitude	2	1	0	2	1	0	2	1	0
archmagnitude	2	2	2	1	1	1	0	0	0

• digit grouping: 4 (East Asian)

	9	8	7	6	5	4	3	2	1
magnitude	0	3	2	1	0	3	2	1	0
archmagnitude	2	1	1	1	1	0	0	0	0

• digit grouping: [3, 2] (South Asian)

	9	8	7	6	5	4	3	2	1
magnitude	1	0	1	0	1	0	2	1	0
archmagnitude	3	3	2	2	1	1	0	0	0

What means that mosaic?

It's the ideograph 𠬞, graphically meaning “two hands”. Details at CUHK.

What's the future plan?

I need to

• add support to other languages mentioned in 'about/language.yaml'
• add notations mentioned in 'about/notation.yaml'
• start supporting other languages covering as many language families as possible, languages being mostly learned are given the priority
• add a guidance on adding a new language
• add the TTS support and maybe the SR support
• create a GUI with BeeWare, but not for iOS because of its totalitarian regulations. If there were iOS versions later, they wouldn't be my work.

I need to accumulate experience through this project, then I can create other ones.

Planned next 3 langauges to be supported: Lojban, French, Spanish.