rt-orgdocs/rules_and_reasons-russian.md

Правила и рекомендации

Содержание

================================================================================
1. Общие положения и соображения
2. Создание репозитория и оригинал издания
  2.1. Именование репозитория
  2.2. Описание репозитория
  2.3. Файловая структура репозитория
    2.3.1. Файл README.md
    2.3.2. Основной файл проекта
    2.3.3. Файл definitions.tex
    2.3.4. Сценарий сборки
3. Перенабор издания
  3.1. Набор текста
  3.2. Структура
  3.3. Набор таблиц
  3.4. Набор формул
  3.5. Включение иллюстраций
  3.6. Ссылки
  3.7. Предметный указатель
  3.8. Технические страницы
4. Рекомендации
  4.1. Принцип DRY и метод переиспользования кода
  4.2. Предметный указатель
  4.3. Программа для редактирования исходного кода TeX
  4.4. Программа для отрисовки векторных изображений
  4.5. Программа для измерения иллюстраций и элементов оформления   4.6. Графический интерфейс Git

================================================================================

1. Общие положения и соображения

Перенабор книг производится исходя из принципа разделения представления и содержания, но при этом необходимо сохранить фрагменты оформления оригинального издания, влияющие на смысл.

Предполагается, что перенаборщик как минимум прочитал книгу, которую перенабирает, а лучше не только прочитал, но и понял её содержание. Это позволяет, во-первых, находить опечатки и ошибки в тексте оригинального издания; во-вторых, сохранять форматирование и оформление несущее смысловую нагрузку в оригинальном издании, так как не все издания изначально придерживались принципа разделения представления и содержания.

Предполагается, что перенаборщик знаком с системы типографской верстки TeX/LaTeX как минимум настолько, чтобы набрать документ, содержащий текст, таблицы, иллюстрации.

Толкование правил в спорных ситуациях исключительная прерогатива администрации ресурса.

2. Создание репозитория и оригинал издания

Только привилегированные пользователи могут создавать репозитории, поэтому для создания репозитория отправьте письмо по адресу электронной почты create@retype.r4in.tk с темой письма [create repository], в теле письма в первой строке укажите ed2k- или torrent-ссылку на оригинальное издание, во второй строке укажите ваше имя пользователя. Будет создан соответствующий репозиторий, к которому вам будет предоставлен доступ. В перенаборе отдельных публикаций в рамках данного проекта может быть отказано.

Оригинальное издание должно находиться в открытом доступе в пиринговых сетях, если его там нет, опубликуйте его в torrent или ed2k сети. Если оригинальное издание в нескольких файлах, то файлы объединяются в один ZIP-архив. Если оригинального издания нет в открытом доступе, но печатное издание находится в вашем владении, то отсканируйте его, включая обложку, форзацы, и все страницы, в том числе страницы с технической информацией об издании.

Если вы не можете обеспечить доступность оригинального издания в пиринговых сетях, отправьте файл с оригинальным изданием или ссылку на него по адресу электронной почты orig@retype.r4in.tk с темой письма [original publishing], если оригинальное издание ещё не использовалось для перенабора, то вам будут высланы ссылки ed2k и magnet на оригинальное издание, а также издание будет добавлено в список изданий запланированных к перенабору.

2.1. Именование репозитория

Репозитории именуются как

rt-g0_hhhhhhhh-краткое_наименование_книги-язык

где

• hhhhhhhh - последние 4 байта хэша SHA3-256 от файла оригинального издания в шестнадцатеричном представлении. Буквы набраны строчными. Если оригинальное издание в нескольких файлах, то все файлы объединяются в один ZIP-архив. Получить хэш SHA3-256 от файла оригинального издания можно командой

  rhash --sha3-256 имя_файла_оригинального_издания

• краткое_наименование_книги - набирается строго латинницей и представляет короткую последовательность, позволяющую идентифицировать книгу. Все пробелы заменяются знаками подчёркивания "_". Набор русских слов осуществляется в соответствии с правилами транслитерации любым, но только одним вариантом.

Правила транслитерации (прочерк - буква опускается):
|русская буква:     |а|б|в|г|д|е |ё |ж  |з|и|й|к|л|м|н|о|п|р|с|т|у|ф|х |ц |ч   |ш  |щ      |ъ|ы|ь|э|ю |я |
|английский вариант:|a|b|v|g|d|e |yo|zh |z|i|y|k|l|m|n|o|p|r|s|t|u|f|h |ts|ch  |sh |shch   |-|y|-|e|yu|ya|
|немецкий вариант:  |a|b|w|g|d|je|jo|sch|s|i|j|k|l|m|n|o|p|r|s|t|u|f|ch|z |tsch|sch|schtsch|-|y|-|e|ju|ja|

• язык - основной язык книги на английском (russian - русский).

2.2. Описание репозитория

Описание репозиториев набирается по шаблону:

Фамилия И. О., Фамилия И. О. [автор(ы)]
--
"Название книги" [в двойных кавычках]
Дополнительные сведения об издании, номер редакции [если есть]
--
[если книга переведена, то указываются переводчики в следующем виде]
перевод с языка [наименование языка] Фамилия И. О., Фамилия И. О.
[если важна редактура, то указываются научные редакторы в следующем виде]
под редакцией Фамилия И. О., Фамилия И. О.
--
nnnn год [nnnn - год издания]

Пояснения в квадратных скобках не набираются.

2.3. Файловая структура репозитория

2.3.1. Файл README.md

Файл README.md набирается по шаблону:

*Фамилия И. О.* [первый автор]

*Фамилия И. О.* [второй автор, и далее указываются все авторы]

**Название книги**

Дополнительные сведения об издании, номер редакции [если есть]

[если книга является переводом,
 указать с какого языка и Фамилии И. О. переводчиков,
 в ином случае следующая строка не набирается]
*перевод с наименование языка Фамилия И. О., Фамилия И. О.*

[если важна редактура,
 то указываются Фамилии И. О. научных редакторов,
 в ином случае следующая строка не набирается]
*под редакцией Фамилия И. О., Фамилия И. О.*

nnnn год [nnnn - год оригинального издания, указать все 4 цифры]

#### Оригинал

<a href="magnet:?dn=имя_файла_с_оригиналом_издания&xt=urn:ed2k:хэш_ed2k_данного_файла&xt=urn:ed2khash:хэш_ed2k_данного_файла&xl=размер_данного_файла_в_байтах">ed2k</a>
&nbsp; &nbsp; &nbsp; 
<a href="magnet:?xt=urn:btih:torrent_хэш_файла_с_оригиналом_издания">torrent</a>

#### Замечания по сборке

1. Сборка осуществляется скриптом `build_script`, который использует
`xelatex`. Результат сохраняется в подкаталоге `build`.

2. Перед сборкой убедитесь в наличии всех пакетов, включаемых в файле
`definitions.tex` инструкциями `\usepackage` и `\RequirePackage`.

3. Перед сборкой убедитесь в наличии всех используемых шрифтов, перечисленных
в файле `definitions.tex` в параметрах инструкций `\set*font` и
`\newfontfamily`.

4. ... [иные замечания по сборке]

#### Замечания по соответствию оригиналу

1. Исправлены замеченные опечатки и ошибки. Эти изменения относительно
оригинала отмечены в исходном коде комментариями под абзацами, в которых
произведены изменения.

2. ... [иные отличия от оригинала]

Пояснения в квадратных скобках не набираются. Вставка HTML со ссылками обусловлена тем, что некоторые markdown-парсеры ломают magnet-ссылки.

Не обязательно вручную добавлять имя_файла_с_оригиналом_издания, размер_данного_файла_в_байтах, хэш_ed2k_данного_файла, torrent_хэш_файла_с_оригиналом_издания. magnet-ссылки можно целиком получить из ed2k-клиента и torrent-клиента. Если что-то из этого вы сделать не сможете, воспользуйтесь предложением из раздела "2. Создание репозитория и оригинал издания".

2.3.2. Основной файл проекта

Основной файл проекта это tex-файл, названный по следующему шаблону:

Familiya_I.O.,Familiya_I.O.-Nazvaniye_knigi[Eth_ed][NNNNy]-language.tex

где

• Familiya_I.O. - фамилия и инициалы автора(ов) набранные латинницей в соответствии с правилами транслитерации из раздела "2.1. Именование репозитория", все пробелы заменены на знак подчеркивания "_";
• Nazvaniye_knigi - название книги набранное латинницей в соответствии с правилами транслитерации из раздела "2.1. Именование репозитория", все пробелы заменены на знак подчеркивания "_";
• E - номер редакции при налиции такового, в ином случае этот блок, включая квадратне скобки пропускается;
• NNNN - год издания оригинального издания с указание всех четырёх цифр;
• language - английское именование основного языка оригинального издания (русский - russian).

2.3.3. Файл definitions.tex

Файл definitions.tex содержит все включения (\usepackage,\RequirePackage), настройки (геометрические, языковые, форматирования) и определения, используемые в документе. Исключение составляют только пакеты, включение которых необходимо строго до определения класса документа.

Файл definitions.tex включается директивой \input{definitions.tex} в основной файл проекта сразу после определения класса документа следующим образом:

\documentclass{класс_документа}
\input{definitions.tex}

Таким образом обеспечивается единое местоположение всех настроек документа и определений окружений оформления.

2.3.4. Сценарий сборки

Сценарий сборки представляет собой sh/bash-сценарий, с именем build_script, который, будучи запущенным, осуществляет окончательную сборку проекта в подкаталоге build. При написании сценария сборки полезно помнить, что для обновления ссылок и оглавления (toc) необходимо дважды запустить сборку, а для формирования предметного указателя и сопутствующих файлов - трижды.

3. Перенабор издания

3.1. Набор текста

Текст набирается исходя из того, что сборка будет осуществляться программами XeTeX/XeLaTeX с использованием пакетов polyglossia и xltxtra. Программа XeTeX и сопутствующие пакеты поставляются в составе дистрибутива TeX Live. При необходимости допускается включение Lua-скриптов для сборки проекта системой LuaTeX, однако необходимость этого должна быть убедительно обоснована в первом комментарии в основном файле проекта.

Текст набирается в исходном файле с расчётом на ширину терминала 80 символов за исключением случаев, когда синтаксис не допускает переноса. Перенос по границе 80 символов осуществляется строго вместо пробела простого текста или в окружениях допускающих такой перенос.

Форматирование оригинального текста, а именно отступы, относительные размеры шрифтов, семейства шрифтов по возможности сохраняются, так как могут нести смысловую нагрузку. Отступы yказываются в долях от значений \paperwidth и \paperheight

3.2. Структура

Структура документа полностью восстанавливается в строгом соответствии с оригинальным изданием. Если структура оригинального издания не соответствует типовой структуре книги, то соответствующие изменения должны быть внесены в cls-файл, описывающий класс документа. Базовым классом, на основании которого строится новый cls-файл, является extbook. Любой структурный элемент книги должен иметь метку \label для возможности сослаться на него.

3.3. Набор таблиц

Короткие по высоте таблицы выполняются в окружении tabular. Длинные по высоте таблицы выполняются в окружении longtable пакета longtable. Набор таблиц осуществляется с указанием строго относительных размеров столбцов к переменной \linewidth или, при необходимости, \textwidth. Для расчёта размеров столбцов использовать пакет calc и значение \tabcolsep. Использование иных пакетов и окружений для оформления таблиц должно быть строго необходимым и необходимость объяснена в комментарии перед такой таблицей, так как другие пакеты иногда приводят к нежелательным артефактам в сборке.

3.4. Набор формул

Формулы в строке набираются в окружении $формула$. Многострочные и отдельные формулы набраются в окружениях equation. Использование иных окружений для набора формул должно быть строго необходимым и необходимость объяснена в комментарии перед такой формулой, для избежания артефактов в сборке. Обращайте внимание на наличие в математических шрифтах используемых символов, так как часть символов может быть не описана в шрифте.

Сложные формулы-диаграммы набираются в синтаксисе пакета Xy-pic.

3.5. Включение иллюстраций

Иллюстрации оригинального издания включаются в перепечатку издания по следующим правилам:

1. Иллюстрация должна пропорционально соответствовать оригинальному в разумных пределах. Разумные пределы - один пиксел.

2. Если иллюстрацию можно без значительных затрат времени описать в виде таблицы, тогда иллюстрация оформляется в окружении tabular.

3. Если иллюстрацию можно без значительных затрат времени описать в синтаксисе пакета Xy-pic, тогда иллюстрация оформляется в синтаксисе пакета Xy-pic.

4. Если иллюстрация по смыслу использования в оригинале не представляет собой растровое изображение, а является схемой или диаграммой или графиком, в таком случае иллюстрация включается в формате eps. При этом в репозиторий также добавляется черновик иллюстрации, который может представлять собой:

   (а) векторное изображение в формате svg, при переносе оригинальной иллюстрации в формат svg желательно использовать масштабирование 1 пиксел = 1 миллиметр, при измерении оригинального изображения в масштабе 1, в ином случае в первом комментарии svg-файла укажите масштаб и условия измерений оригинальной иллюстрации;

   (б) исходный код программы для математического пакета, который строит требуемый график, в таком случае первым комментарием исходного кода должен быть указан математический пакет и его точная версия вплоть до минорной.

5. Если иллюстрация в контексте оригинала является растровым изображением, то использовать его оригинал со сжатием без потерь в формате png. При недоступности оригинала - использовать лучшую доступную копию.

Такие требования к иллюстрациям обусловлены тем, что даже в оригинальных электронных книгах издательств можно обнаружить растровые изображения, которые в контексте избыточны, не масштабируются свободно и при определенных условиях приводят к некорректному отображению страницы. Исходя из принципа разделения представления и содержания, иллюстрация должна корректно масштабироваться в широком (условно бесконечном) интервале множителей и корректно отображаться при любых настройках представления, например:

3.6. Ссылки

Все внутренние ссылки должны быть соответственно оформлены и работать, включая ссылки на библиографию внутри издания. Все внешние сылки должны быть соответственно оформлены и ссылаться на URL из оригинала издания, даже если он на момент набора не ведет на существующий или релевантный ресурс.

3.7. Предметный указатель

Предметный указатель формируется пакетом xindy. Ключевые слова инструкцией \indexотмечаются либо прямо перед ключевым словом внутри абзаца, либо перед абзацем без разделения инструкцией \par или двумя символами новой строки, так как в ином случае при сборке координата ключевого слова и сам абзац могут оказаться на разных страницах. Оформление и порядок сортировки описываются в отдельном xdy-файле, в соответствии с таковыми в оригинале.

3.8. Технические страницы

Технические страницы оригинального издания перенабираются строго в соответствии с оригиналом, даже если перенабор не соответствует заявленной информации. Технические страницы могут отсутствовать, только если оригинал доступен только в копии без технических страниц. Кроме того, при перенаборе добавляется последняя страница набранная моноширинным шрифтом в соответствии с шаблоном:

%%=============================================================================
\newpage\pagestyle{empty}
\begingroup\newpage
\setlength{\parindent}{0cm}
\footnotesize\ttfamily
\textit{Фамилия И. О.}\par% первый автор
\textit{Фамилия И. О.}    % второй автор, и далее указываются все авторы
\smallskip\par
{\normalsize Название книги}\smallskip\par
Дополнительные сведения об издании, номер редакции % при наличии таких сведений
\smallskip\par
% если книга является переводом,
% указать с какого языка и Фамилии И. О. переводчиков,
% в ином случае следующая строка не набирается
\textit{перевод с наименование языка Фамилия И. О., Фамилия И. О.}\par
% если важна редактура, то указываются Фамилии И. О. научных редакторов,
% в ином случае следующая строка не набирается
\textit{под редакцией Фамилия И. О., Фамилия И. О.}\par
nnnn год% nnnn - год оригинального издания, указать все 4 цифры
\bigskip\par
Перенабор книги выполнен в рамках проекта ReType
(\href{https://retype.r4in.tk}{https://retype.r4in.tk})\par
Исходный код для индивидуальной сборки или типографской вёрстки может быть
получен по адресу:\par
\href{адрес_репозитория_с_исходным_кодом}{адрес_репозитория_с_исходным_кодом}
\bigskip\par
{\normalsize Оригинал}\smallskip\par
ed2k -- \href{ed2k://|file|имя_файла_с_оригиналом_издания|размер_данного_файла_в_байтах|хэш_ed2k_данного_файла|}
{ed2k://|file|имя_файла_с_оригиналом_издания|размер_данного_файла_в_байтах|хэш_ed2k_данного_файла|}\smallskip\par
torrent -- \href{magnet:?xt=urn:btih:хэш_torrent_файла_с_оригиналом_издания}
{magnet:?xt=urn:btih:хэш_torrent_файла_с_оригиналом_издания}\bigskip\par
{\normalsize Замечания по соответствию оригиналу}\smallskip\par
\begin{enumerate}
  \item Исправлены замеченные опечатки и ошибки. Эти изменения относительно
  оригинала отмечены в исходном коде комментариями под абзацами, в которых
  произведены изменения.
  \item ... % иные отличия от оригинала
\end{enumerate}
\newpage
\endgroup

При этом учитывайте, что

• второй аргумент инструкции \href это текст, где при наборе надо использовать экранирование ряда символов, используемых в TeX'е;
• после завершения перенабора репозиторий будет перенесен в группу rt-releases, и адрес_репозитория_с_исходным_кодом будет содержать другой каталог.

Не обязательно вручную добавлять имя_файла_с_оригиналом_издания, размер_данного_файла_в_байтах, хэш_ed2k_данного_файла, хэш_torrent_файла_с_оригиналом_издания. ed2k-ссылку можно целиком получить из ed2k-клиента, а magnet-ссылку на торрент можно получить в torrent-клиенте. Если что-то из этого вы сделать не сможете, воспользуйтесь предложением из раздела "2. Создание репозитория и оригинал издания".

4. Рекомендации

4.1. Принцип DRY и метод переиспользования кода

Следование принципу DRY (Don’t repeat yourself) приводит к тому, что имеет смысл перед перенабором пролистать издание и выделить повторяющееся одинаковое форматирование и оформление, после чего создать для такого оформления отдельное окружение, которое потом и использовать. Это снизит вероятность возникновения ошибки.

Использование метода переиспользования кода приводит к тому, что имеет смысл не только выделить повторяющееся одинаковое оформление, но и однотипные оформления, отличающиеся лишь некоторыми параметрами (обычно одним). Так, например, если в тексте оригинального издания часто встречаются таблицы из двух столбцов, прижатые вправо и отличающиеся только шириной столбцов, то есть смысл создать единое окружение для таких таблиц, в аргументах которого указывать ширину столбцов. Следует, однако, избегать переусложнённых окружений с множеством параметров на все случаи жизни, такое окружение уже есть и называется TeX.

4.2. Предметный указатель

Если оригинальное издание содержит предметный указатель, то лучше сначала отсортировать ключевые слова указателя по номерам страниц и добавлять их в ходе перенабора, так как восстановление предметного указателя по ключевым словам в перенабранном тексте довольно трудоёмко.

Несколько снизить трудность перенабора предметного указателя позволяют комментарии в исходном коде, разбивающие исходный код на блоки в соответствии с нумерацией страниц оригинала, например такие:

%% ======================= Страница 235 =======================

4.3. Программа для редактирования исходного кода TeX

Для редактирования исходного кода TeX довольно удобно использовать Kile

4.4. Программа для отрисовки векторных изображений

Для отрисовки векторных изображений рекомендуется использовать Inkscape.

4.5. Программа для измерения иллюстраций и элементов оформления

Для измерения иллюстраций и элементов оформления рекомендуется использовать KRuler

4.6. Графический интерфейс Git

Если отдаётся предпочтение графическим интерфейсам, а не командной строке, то для работы с Git использовать SmartGit