Update doco

ENDrain · May 13, 2021 · d142cf5 · d142cf5
1 parent 33e4f96
commit d142cf5
Show file tree

Hide file tree

Showing 8 changed files with 225 additions and 9 deletions.
diff --git a/CHANGELOG.md → docs/CHANGELOG.md b/CHANGELOG.md → docs/CHANGELOG.md
@@ -1,5 +1,7 @@
 # Changelog
 
+🌏 English [Русский](./CHANGELOG.ru.md)
+
 ## 1.3.2
 
 - Added: Exceptions on unexpected input
@@ -27,7 +29,7 @@
 
 - Added: Now supports Python >= 3.5
 - Fixed: Wrong "titlo" positioning
-- Fixed: Wrong 800 digit
+- Fixed: Wrong "800" digit
 
 
 ## 1.0.0

diff --git a/docs/CHANGELOG.ru.md b/docs/CHANGELOG.ru.md
@@ -0,0 +1,37 @@
+# История версий
+
+🌏 [English](./CHANGELOG.md) Русский
+
+## 1.3.2
+
+- Добавлено: Исключения при некорректных входных данных
+
+## 1.3.1
+
+- Оптимизация
+
+## 1.3.0
+
+- Добавлено: Флаги декорирования точками: конечная, с обеих сторон, точки-разделители разрядов, или любая их комбинация
+- Добавлено: Обязательное проставление точек-разделителей в неоднозначных случаях
+
+## 1.2.0
+
+- Добавлено: Поддержка чтения/записи в "сплошном" записи
+- Добавлено: Флаг выбора варианта записи при преобразовании в ЦСЯ ("по группам" по умолчанию)
+- Добавлено: Флаг для опускания вывода "титла"
+
+## 1.1.1
+
+- Полировка
+
+## 1.1.0
+
+- Добавлено: Поддержка Python >= 3.5
+- Исправлено: Неверная позиция "титла"
+- Исправлено: Неверная цифра "800"
+
+
+## 1.0.0
+
+- Исходный выпуск
diff --git a/INTRODUCTION.md → docs/INTRODUCTION.md b/INTRODUCTION.md → docs/INTRODUCTION.md
@@ -1,5 +1,7 @@
 # CYRILLIC NUMERAL SYSTEM
 
+🌏 English [Русский](./INTRODUCTION.ru.md)
+
 ## 1. Numerals
 Cyrillic numeral system has individual letters assigned to represent numbers from 1 to 9 in registries from digits to hundreds, for a total of 27 numerals. There's no zero numeral.
 
@@ -27,7 +29,7 @@ Cyrillic|Arabic|Cyrillic|Arabic|Cyrillic|Arabic
 |||а҃і|11|ра҃і|111
 |||к҃а|21|рк҃а|121
 
-## 3. Thousands and above
+## 3. Numbers from thousand and above
 In a number `x > 999`, the `҂` "thousand" sign is used before numerals that represent higher order of magnitude. For each thousand sign before a numeral its value is multiplied by 1000.
 
 **Examples:**
@@ -46,7 +48,7 @@ In "plain" style, "thousand" signs are prepended to each numeral in higher regis
 
 In this style, numerals representing numbers 11-19 are only swapped unless "thousand"-marked.
 
-***Examples:**
+**Examples:**
 Cyrillic|Arabic
 ---|---
 ҂р҂і҂ара҃і|111 111
@@ -72,7 +74,7 @@ Cyrillic|Arabic
 ## 5. Decoration
 
 ## 5.1 "Titlo"
-The `҃`&nbsp; "titlo" superscript sign is obligatory to Cyrillic numbers. "Titlo" is placed above the 2nd-from-last digit if it exists and is not thousand-marked, otherwise above the last digit.
+The `҃ `&nbsp; "titlo" superscript sign is obligatory to Cyrillic numbers. "Titlo" is placed above the 2nd-from-last digit if it exists and is not thousand-marked, otherwise above the last digit.
 
 Historically, "titlo" could've been placed above the 2nd digit, or above the whole number. It is possible to reproduce this with Unicode symbols "Titlo start", "titlo section", "titlo end".
 

diff --git a/docs/INTRODUCTION.ru.md b/docs/INTRODUCTION.ru.md
@@ -0,0 +1,89 @@
+# ЦЕРКОВНОСЛАВЯНСКАЯ СИСТЕМА ЗАПИСИ ЧИСЕЛ
+
+🌏 [English](./INTRODUCTION.md) Русский
+
+## 1. Цифры
+В церковнославянской системе записи чисел отдельные буквы используются для записи цифр от 1 до 9 в регистрах от единиц до сотен - т.е. всего 27 цифр. Нуль отсутствует.
+
+ЦСЯ|Арабские|ЦСЯ|Арабские|ЦСЯ|Арабские
+---|---|---|---|---|---
+а҃|1|і҃|10|р҃|100
+в҃|2|к҃|20|с҃|200
+г҃|3|л҃|30|т҃|300
+д҃|4|м҃|40|у҃|400
+є҃|5|н҃|50|ф҃|500
+ѕ҃|6|ѯ҃|60|х҃|600
+з҃|7|ѻ҃|70|ѱ҃|700
+и҃|8|п҃|80|ѿ҃|800
+ѳ҃|9|ч҃|90|ц҃|900
+
+## 2. Базовые числа
+Число величиной `x < 1000` (базовое) записывается соответствующими цифрами соответствующих разрядов, от старшего разряда к младшему. Исключение составляют числа от 11 до 19, в которых цифры меняются местами.
+
+**Примеры:**
+ЦСЯ|Арабские|ЦСЯ|Арабские|ЦСЯ|Арабские
+---|---|---|---|---|---
+а҃|1|і҃|10|р҃|100
+|||||р҃а|101
+|||||р҃і|110
+|||а҃і|11|ра҃і|111
+|||к҃а|21|рк҃а|121
+
+## 3. Числа от тысячи и больше
+В числе величиной `x > 999` для обозначения разряда старшего порядка перед цифрой приписывается отметка - знак тысячи `҂`. За каждый знак тысячи перед цифрой ее величина умножается на 1000.
+
+**Примеры:**
+ЦСЯ|Арабские
+---|---
+҂а҃|1 000
+҂і҃|10 000
+҂р҃|100 000
+҂҂а҃|1 000 000
+
+## 4. Варианты записи чисел
+В ЦСЯ существует несколько вариантов записи чисел величиной `x > 999`.
+
+## 4.1. "Сплошная" запись
+В "сплошной" записи знаками тысяч отмечается каждая цифра в разрядах старшего порядка. Таким образом, умножается только цифра, непосредственно следующая за знаками.
+
+В этом варианте цифры в числах от 11 до 19 меняются местами только "в натуральном" виде, если не отмечены знаками тысяч.
+
+**Примеры:**
+ЦСЯ|Арабские
+---|---
+҂р҂і҂ара҃і|111 111
+
+## 4.2 Запись "по группам"
+В записи с разбиением по группам знаками тысяч отмечается каждая группа цифр, составляющая отдельное базовое число в разряде старшего порядка. Таким образом, умножается все базовое число, непосредственно следующее за знаками.
+
+В этом варианте цифры в числах от 11 до 19 меняются местами всегда, в отличие от "сплошного".
+
+**Примеры:**
+ЦСЯ|Арабские
+---|---
+҂раіра҃і|111 111
+
+## 4.3 Запись "с обводом"
+В записи с обводом для обозначения разрядов старшего порядка используется специальный набор отметок, которыми обводятся цифры, находящиеся в разрядах от десяти тысяч до миллиардов.
+
+**Примеры:**
+ЦСЯ|Арабские
+---|---
+а&#1160;а&#8413;҂ара҃і|111 111
+
+## 5. Декорирование
+
+## 5.1 Титло
+В записи ЦСЯ чисел обязательно используется надстрочный знак "титло" `҃ `&nbsp;. Титло пишется над второй цифрой с конца, если она существует и не отмечена знаками тысяч. В противном случае титло пишется над последней цифрой числа.
+
+В более древних источниках можно обнаружить другие правила записи титла: например, над второй цифрой сначала, или длинное над всем числом. Последний вариант можно воспроизвести с помощью символов Unicode "титло начало", "титло отрезок", "титло конец".
+
+## 5.2 Точки
+
+Иногда в записи ЦСЯ чисел использовались точки. Точка может стоять после числа, а может быть и по точке с обеих сторон. Точка также может использоваться как дополнительный разделитель разрядов при записи "по группам". В некоторых случаях это даже необходимо, чтобы избежать двусмысленности:
+
+||ЦСЯ|Арабские
+|---|---|---
+|Запись "сплошная":|҂і҂а҃|11000
+|Запись "по группам":|҂а҃і|11000
+||҂а.і҃|1010
diff --git a/LICENSE → docs/LICENSE b/LICENSE → docs/LICENSE
diff --git a/docs/LICENSE.ru b/docs/LICENSE.ru
@@ -0,0 +1,21 @@
+Лицензия MIT
+
+Copyright (c) 2021 Андрей Шур
+
+Данная лицензия разрешает лицам, получившим копию данного программного обеспечения
+и сопутствующей документации (в дальнейшем именуемыми «Программное Обеспечение»),
+безвозмездно использовать Программное Обеспечение без ограничений,
+включая неограниченное право на использование, копирование, изменение, слияние,
+публикацию, распространение, сублицензирование и/или продажу копий
+Программного Обеспечения, а также лицам, которым предоставляется
+данное Программное Обеспечение, при соблюдении следующих условий:
+
+Указанное выше уведомление об авторском праве и данные условия
+должны быть включены во все копии или значимые части данного Программного Обеспечения.
+
+ДАННОЕ ПРОГРАММНОЕ ОБЕСПЕЧЕНИЕ ПРЕДОСТАВЛЯЕТСЯ «КАК ЕСТЬ», БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ,
+ЯВНО ВЫРАЖЕННЫХ ИЛИ ПОДРАЗУМЕВАЕМЫХ, ВКЛЮЧАЯ ГАРАНТИИ ТОВАРНОЙ ПРИГОДНОСТИ,
+СООТВЕТСТВИЯ ПО ЕГО КОНКРЕТНОМУ НАЗНАЧЕНИЮ И ОТСУТСТВИЯ НАРУШЕНИЙ, НО НЕ ОГРАНИЧИВАЯСЬ ИМИ.
+НИ В КАКОМ СЛУЧАЕ АВТОРЫ ИЛИ ПРАВООБЛАДАТЕЛИ НЕ НЕСУТ ОТВЕТСТВЕННОСТИ ПО КАКИМ-ЛИБО ИСКАМ,
+ЗА УЩЕРБ ИЛИ ПО ИНЫМ ТРЕБОВАНИЯМ, В ТОМ ЧИСЛЕ, ПРИ ДЕЙСТВИИ КОНТРАКТА, ДЕЛИКТЕ ИЛИ ИНОЙ СИТУАЦИИ,
+ВОЗНИКШИМ ИЗ-ЗА ИСПОЛЬЗОВАНИЯ ПРОГРАММНОГО ОБЕСПЕЧЕНИЯ ИЛИ ИНЫХ ДЕЙСТВИЙ С ПРОГРАММНЫМ ОБЕСПЕЧЕНИЕМ.
diff --git a/README.md → docs/README.md b/README.md → docs/README.md
@@ -4,6 +4,8 @@
 
 [![PyPI - License](https://img.shields.io/pypi/l/cu-numbers)](./LICENSE) [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 
+🌏 English [Русский](./README.ru.md)
+
 A program for numbers conversion between Arabic and Cyrillic (*further CU*) numeral systems.
 
 ## Background
@@ -16,29 +18,29 @@ See [Introduction](./INTRODUCTION.md) to learn about CU numeral system.
 
 ## Usage
 
-	import cunumbers
+	import cunumbers.cunumbers as cu
 
 	#   Convert an Arabic number to CU
 	#   Requires non-zero int, returns str
 
-	a = cunumbers.to_cu(1)
+	a = cu.to_cu(1)
 
 	#   Convert a CU number to Arabic
 	#   Requires non-empty str, returns int
 
-	b = cunumbers.to_arab("а҃")
+	b = cu.to_arab("а҃")
 
 "Delimiter" and "plain" style numbers are supported in both directions. "Delimeter" style is default for CU-wise conversion.
 
 Several falgs can be used with `to_cu()` method:
 
 	#   CU_PLAIN flag sets conversion to "plain" style
 
-	c = cunumbers.to_cu(111111, CU_PLAIN)
+	c = cu.to_cu(111111, CU_PLAIN)
 
 	#   CU_NOTITLO flag omits "titlo" output
 
-	d = cunumbers.to_cu(11000, CU_PLAIN | CU_NOTITLO)
+	d = cu.to_cu(11000, CU_PLAIN | CU_NOTITLO)
 
 	#   Following flags control dot styling:
 	#

diff --git a/docs/README.ru.md b/docs/README.ru.md
@@ -0,0 +1,63 @@
+# cu-numbers
+
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/cu-numbers) ![PyPI - Wheel](https://img.shields.io/pypi/wheel/cu-numbers) [![Codecov](https://img.shields.io/codecov/c/github/endrain/cu-numbers)](https://app.codecov.io/gh/endrain/cu-numbers)
+
+[![PyPI - License](https://img.shields.io/pypi/l/cu-numbers)](./LICENSE.ru) [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+🌏 [English](./README.md) Русский
+
+Программа для преобразования чисел между арабской и церковнославянской системами записи.
+
+## Историческая справка
+
+[В этой статье](./INTRODUCTION.ru.md) вы можете ознакомиться с церковнославянской системой записи чисел.
+
+## Установка
+
+	pip install cu-numbers
+
+## Использование
+
+	import cunumbers.cunumbers as cu
+
+	#   Преобразовать арабское число в церковнославянское
+	#   Принимает ненулевой int, возвращает str
+
+	a = cu.to_cu(1)
+
+	#   Преобразовать церковнославянское число в арабское
+	#   Принимает непустой str, возвращает int
+
+	b = cu.to_arab("а҃")
+
+В обоих направлениях поддерживаются варианты записи "сплошной" и "по группам". Запись "по группам" используется по умолчанию для преобразования в ЦСЯ.
+
+Метод `to_cu()` принимает несколько флагов:
+
+	#   CU_PLAIN устанавливает "сплошной" вариант записи для преобразования в ЦСЯ
+
+	c = cu.to_cu(111111, CU_PLAIN)
+
+	#   CU_NOTITLO опускает вывод знака "титло"
+
+	d = cu.to_cu(11000, CU_PLAIN | CU_NOTITLO)
+
+	#   Следующие флаги управляют декорированием точками:
+	#
+	#   CU_ENDDOT - выводит точку в конце
+	#   CU_WRAPDOT - выводит точки с обеих сторон
+	#   CU_DELIMDOT - выводит точки-разделители разрядов. Устанавливает вариант записи "по группам"
+	#   CU_ALLDOT - комбинация флагов CU_WRAPDOT и CU_DELIMDOT
+
+
+## Принять участие
+
+Откройте новую проблему, опишите в ней исправляемый баг или предлагаемый функционал. Затем откройте запрос на слияние, в описании дайте ссылку на проблему.
+
+## Отзывы
+
+Пишите по адресу: [email protected]
+
+## История версий
+
+Смотрите [здесь](./CHANGELOG.ru.md).