Перевод и осмысление документации
29.11.2021
|
velkin
 |
Содержание
1. Должен ли программист знать английский.
2. Оффлайн против онлайн документации.
3. Расположение документации на диске.
4. Перевод оффлайн документации.
4.1 Перевод C++ Reference 19.06.07.
4.2 Перевод Boost 1.77.
4.3 Перевод Qt 5.9.9.
4.4 Перевод Sqlite 3.36.
4.5 Перевод Blender 2.93.
4.6 Настройка Kiwix.
5. Можно ли верить документации.
6. Использование оффлайн документации.
7. Заключение.
1. Должен ли программист знать английский.
Очень часто встречается утверждение, что программист должен знать английский. Сразу отмечу, что сущность алгоритмов не имеет никакого отношения ни к английскому, ни к какому либо другому разговорному языку. Вместо осмысленных имён можно писать бессмысленные и всё будет работать точно так же. Это один из принципов использующихся в системах обфускации кода, когда он по каким-то причинам открыт или может быть декомпилирован, но при этом нужно затруднить его последующее использование другими лицами.
Разделю английский на:
1) Технический.
Достаточен для дословного перевода технической документации, вроде "моя твоя понимать".
2) Разговорный.
Свободное общение с носителями другого языка, правильное построение фраз и тому подобное.
Но предположим человек плохо знает английский и ему лень его целенаправленно учить. Это называется не знать английский или как ещё говорят знать со словарём. Другая причина человек хочет читать документацию на своём языке, даже если она переведена коряво, а как известно другой документации и не будет.
Причины не учить английский:
1) Лень.
2) Предпочитать родной язык.
При всём при том, что технический английский позволит программировать без словаря, а разговорный устроиться работать в иностранную компанию для новичка сосредоточенного на обучении алгоритмам всё это может быть не слишком важно.
Преимущества знания английского:
1) Чтение чужой документации и кода без словаря.
2) Требование при устройстве на работу в иностранную компанию.
2. Оффлайн против онлайн документации.
Следующий вопрос должна ли документация быть:
1) Оффлайн.
Находится на диске пользователя.
2) Онлайн.
Находится на чужом удалённом сервере.
| Особенности | Оффлайн | Онлайн |
|---|---|---|
| канал доступа | прямое обращение к диску | задержка интернет канала |
| количество пользователей | один быстрая обработка | много долгая обработка |
| доступность ресурса | всегда доступен | интернет или сервер иногда недоступны |
| время перевода | сделан заранее | во время прокрутки страниц |
| качество перевода | немного корявый | лучше, но до идеала далеко |
| поиск по документации | хуже без локальных поисковых систем | можно использовать онлайн поисковые системы |
| просмотр директорий | да | нет |
Скорость доступа оффлайн документации, особенно расположенной на SSD многократно выше. Нет задержки канала, нет проблемы доступности, обслуживается лишь один клиент. А благодаря переводу сделанному заранее после открытия страницы можно сразу видеть перевод и использовать поиск на странице, тогда как онлайн переводчики вроде гугла медленно переводят текст по мере прокрутки страницы и только то, что попало в область видимости.
Если говорить о качестве перевода, то онлайн переводчик типа гугловского чуть лучше, но именно чуть. Он точно так же будет переводить как ему вздумается не обращая внимание на то, надо ли переводить идентификаторы в коде или нет. И без использования поисковых систем основанных на Xapian или других просто не будет полнотекстового поиска в оффлайне.
Зато в локальной документации благодаря мгновенному срабатыванию лучше запоминается путь перехода по ссылкам от главной страницы index.html. Так же начинает играть роль адресная строка, так как при стирании названия страницы попадаем в директорию со всеми html-страницами, что даёт удобный обзор на уровне файлов, а не просто ссылок на веб-страницах.
Итого, онлайн документация даёт преимущества в первые минуты использования. Оффлайн документация потребует время на подготовку, то есть скачивание, перевод, установку удобных ссылок, а всё это вместе может занять несколько часов лишь на создания одного пакета, но после этого имеет ощутимые преимущества перед онлайн документаций.
3. Расположение документации на диске.
У пользователя Windows жёсткие диски нумеруются с "C:", "D:", хотя можно было бы задать любые другие свободные буквы. На диск "C:" можно было бы установить операционную систему, а на диске "D:" хранить независимые данные, которые точно не будут повреждены в случае переустановки операционной системы.
Для GNU/Linux могут быть дополнительно примонтированные диски вроде "/mnt/data_01", "/mnt/data_02". Но даже в случае установки архива на диск операционной системы принцип не меняется.
С точки зрения виндузятника структура папок документации может выглядеть так.
D:
archive
anime # аниме
audiobooks # аудиокниги
books # книги
clips # клипы
develop # разработка
distros # дистрибутивы
doc # документация
blender293 # блендер 2.93
en # блендер 2.93 английская
ru # блендер 2.93 русская
boost177 # буст 1.77
en # буст 1.77 английская
ru # буст 1.77 русская
cppref190607 # c++ ссылки
common # c++ общее
en # c++ ссылки английская
ru # c++ ссылки русская
kiwix # вики
wikipedia_en_all_nopic_2018-09.zim
wikipedia_ru_all_novid_2018-07.zim
qt599 # кьют 5.9.9
en # кьют 5.9.9 английская
ru # кьют 5.9.9 русская
sqlite336 # склайт 3.66
en # склайт 3.66 английская
ru # склайт 3.66 русская
downloads # загрузки
files # файлы
games # игры
images # изображения
lessons # уроки
movies # фильмы
music # музыка
photos # фото
podcasts # подкасты
serials # сериалы
sources # исходники
torrent # торренты
video # видео
virtualbox # виртуалки
youtube # ютуб4. Перевод оффлайн документации.
Скачать примеры одним архивом: doc.7z
4.1 Перевод C++ Reference 19.06.07.
Исходная документация берётся со страницы:
https://en.cppreference.com/w/Cppreference:Archives
Был выбран документ:
html_book_20190607.zip
Возникают следующие вопросы:
1) CppReference уже имеет перевод на русский, почему бы не скачать его?
Скачал, он не полный. И вот вопрос, использовать ли корявый, но полный перевод с возможностью переключения на оригинал, или перевод постоянно обрывающийся при переходе на ссылку. В целях унификации выбрал корявый, но зато полный перевод, а так же полностью синхронизированный перевод.
2) А почему бы не использовать последнюю неофициальную версию для перевода?
На такой документации есть лишняя информация, так как её сгенерировали как попало. Потому я остановился на последнем официальном релизе.
Особенность перевода документации CppReference ещё и в том, что там уже предусмотрены папки для разных языков, а вот common общая для всех папка. Потому я просто перевёл папку en на ru и совместил её поверх папки en для получения полной версии папки ru. Этот алгоритм будет использоваться для всех документаций.
4.2 Перевод Boost 1.77.
Исходная документация берётся со страницы:
https://www.boost.org/users/download/
Была выбрана версия:
boost_1_77_0.7z
Особенность перевода boost в том, что нужно переводить всю папку целиком, так как документация раскидана на подпроекты. Не нужно вестись на папку doc, там отнюдь не вся документация.
А ещё:
1) Один doc файл не перевёлся, стёр его, так как он был нулевого размера и оставил английскую версию.
2) Случился вылет из-за файла:
\libs\geometry\doc\src\docutils\tools\doxygen_xml2qbk\contrib\rapidxml-1.13\manual.html
4.3 Перевод Qt 5.9.9.
Скачать дистрибутив можно отсюда:
https://download.qt.io/archive/qt/5.9/5.9.9/
Дальше всё просто
1) Взял папку "../Qt5.9.9/Docs/Qt-5.9.9/".
2) Стёр из неё *.qch и Makefile файлы.
3) Переименовал её в "en".
4) Перевёл в "ru".
5) Совместил с "en" для полноты.
Каких-либо проблем с переводом не было.
4.4 Перевод Sqlite 3.36.
Новые архивы можно скачать отсюда:
https://www.sqlite.org/download.html
Документация переводится один в один.
4.5 Перевод Blender 2.93.
Аналогично последняя документация по блендеру, качаем и переводим.
https://docs.blender.org/manual/en/latest/
4.6 Настройка Kiwix.
Лично я использую Kiwix-serve:
https://wiki.kiwix.org/wiki/Kiwix-serve/ru
kiwix-server-library.sh (в автозапуск)
#!/bin/bash
./kiwix/bin/kiwix-serve --port 8000 --daemon --library ~/.www.kiwix.org/kiwix/89d18krw.default/data/library/library.xmlДобавить в библиотеку:
/opt/kiwix/bin/kiwix-manage /home/user/.www.kiwix.org/kiwix/89d18krw.default/data/library/library.xml add /mnt/data_00/archive/doc/kiwix/wikipedia_en_all_nopic_2018-09.zim
/opt/kiwix/bin/kiwix-manage /home/user/.www.kiwix.org/kiwix/89d18krw.default/data/library/library.xml add /mnt/data_00/archive/doc/kiwix/wikipedia_ru_all_novid_2018-07.zim5. Можно ли верить документации.
Для начала ответим на вопрос для чего нужна документация. А нужна она для того, чтобы описывать не закодированные особенности. Фактически документация может врать и даже сгенерированная документация может вести себя странно.
Из документации Qt 5.9.9:
bool disconnect(const QObject *sender, const char *signal, const QObject *receiver, const char *method)Из исходников Qt 5.9.9:
static bool disconnect(const QObject *sender, const char *signal,
const QObject *receiver, const char *member);Различия:
1) В документации сгенерирована табуляция вместо пробелов в исходнике.
2) В документации вынесена опция static в группировку.
3) К сожалению модификаторы доступа не обязательно прописывать с каждым методом.
4) Не соблюдение прочих отступов таких как перенос строк.
5) Но самое удивительно method и member не совпадают.
Причём QtCreator показывает member как в исходнике. Но давайте ознакомимся с исходным кодом чтобы понять.
qobject.h
static bool disconnect(const QObject *sender, const char *signal,
const QObject *receiver, const char *member);
static bool disconnect(const QObject *sender, const QMetaMethod &signal,
const QObject *receiver, const QMetaMethod &member);
inline bool disconnect(const char *signal = Q_NULLPTR,
const QObject *receiver = Q_NULLPTR, const char *member = Q_NULLPTR) const
{ return disconnect(this, signal, receiver, member); }
inline bool disconnect(const QObject *receiver, const char *member = Q_NULLPTR) const
{ return disconnect(this, Q_NULLPTR, receiver, member); }
static bool disconnect(const QMetaObject::Connection &);
#ifdef Q_QDOC
template<typename PointerToMemberFunction>
static bool disconnect(const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method);Действительно есть такое макро определение, если документация Qt, тогда method.
Возможно PointerToMemberFunction заменяется на:
1) const char *
2) const QMetaMethod &
Я не знаю, не разбирался в этом, да и не важно. Суть в том, что генерация искажает исходный код, а в самой документации можно прописать другое поведение, то есть вовсе не то, что исполняет код. Конечно, документация помогает понять задумку не вникая в смысл кода, тем более, когда он состоит из одних генераторов в генераторе.
6. Использование оффлайн документации.
1) Создать в браузере на "Панели закладок" подпапку "Документация".
2) Последовательно создать ссылки:
Википедия
http://127.0.0.1:8000/wikipedia_ru_all_novid_2018-07/?
Wikipedia
http://127.0.0.1:8000/wikipedia_en_all_nopic_2018-09/?
C++ Ссылка
file:///mnt/data_00/archive/doc/cppref190607/ru/index.html
C++ Reference
file:///mnt/data_00/archive/doc/cppref190607/en/index.html
Буст 1.77
file:///mnt/data_00/archive/doc/boost177/ru/index.html
Boost 1.77
file:///mnt/data_00/archive/doc/boost177/en/index.html
Кьют 5.9.9
file:///mnt/data_00/archive/doc/qt599/ru/qtdoc/index.html
Qt 5.9.9
file:///mnt/data_00/archive/doc/qt599/en/qtdoc/index.html
Склайт 3.36
file:///mnt/data_00/archive/doc/sqlite336/ru/index.html
Sqlite 3.36
file:///mnt/data_00/archive/doc/sqlite336/en/index.html
Блендер 2.93
file:///mnt/data_00/archive/doc/blender293/ru/index.html
Blender 2.93
file:///mnt/data_00/archive/doc/blender293/en/index.html3) Переключаться между русской и английской документацией можно меняя в строке адреса "ru" на "en" и наоборот.
7. Заключение.
Проблема оффлайн документации не нова. Помимо kiwix у которого множество выкачанных ресурсов, а не только википедия, есть и другие проекты, такие как zeal и прочие. Меня же в первую очередь интересовал перевод. Поскольку помимо всего я использую высокоскоростной SSD для меня гораздо приятнее просматривать оффлайн документацию. Так же корявый перевод гораздо лучше его отсутствия так как позволяет меньше напрягать мозги. В целом думаю опыт по созданию документации и её перевода проходит более ли менее успешно. Но не стоит забывать, что документация это не код, и полное представление о работе программы можно получить только из кода, тогда как документация служит для упрощения первичного ознакомления.
| 29.11.2021 0 комментариев |