# Правила и рекомендации ### Содержание ================================================================================ [1. Общие положения и соображения](#1-общие-положения-и-соображения) [2. Создание репозитория и оригинал издания] (#2-создание-репозитория-и-оригинал-издания)   [2.1. Именование репозитория](#21-именование-репозитория)   [2.2. Описание репозитория](#22-описание-репозитория)   [2.3. Файловая структура репозитория] (#23-файловая-структура-репозитория)     [2.3.1. Файл README.md](#231-файл-readmemd)     [2.3.2. Основной файл проекта](#232-основной-файл-проекта)     [2.3.3. Файл definitions.tex](#233-файл-definitionstex)     [2.3.4. Сценарий сборки](#234-сценарий-сборки) [3. Перенабор издания](#3-перенабор-издания)   [3.1. Набор текста](#31-набор-текста)   [3.2. Структура](#32-структура)   [3.3. Набор таблиц](#33-набор-таблиц)   [3.4. Набор формул](#34-набор-формул)   [3.5. Включение иллюстраций](#35-включение-иллюстраций)   [3.6. Ссылки](#36-ссылки)   [3.7. Предметный указатель](#37-предметный-указатель)   [3.8. Технические страницы](#38-технические-страницы) [4. Рекомендации](#4-рекомендации)   [4.1. Принцип DRY и метод переиспользования кода] (#41-принцип-dry-и-метод-переиспользования-кода)   [4.2. Предметный указатель](#42-предметный-указатель)   [4.3. Программа для редактирования исходного кода TeX] (#43-программа-для-редактирования-исходного-кода-tex)   [4.4. Программа для отрисовки векторных изображений] (#44-программа-для-отрисовки-векторных-изображений)   [4.5. Программа для измерения иллюстраций и элементов оформления] (#45-программа-для-измерения-иллюстраций-и-элементов-оформления) ================================================================================ ### 1. Общие положения и соображения Перенабор книг производится исходя из принципа *разделения представления и содержания*, но при этом необходимо сохранить фрагменты оформления оригинального издания, влияющие на смысл. Предполагается, что перенаборщик как минимум прочитал книгу, которую перенабирает, а лучше не только прочитал, но и понял её содержание. Это позволяет, во-первых, находить опечатки и ошибки в тексте оригинального издания; во-вторых, сохранять форматирование и оформление несущее смысловую нагрузку в оригинальном издании, так как не все издания изначально придерживались принципа *разделения представления и содержания*. Предполагается, что перенаборщик знаком с системы типографской верстки [TeX/LaTeX](https://tug.org/) как минимум настолько, чтобы набрать документ, содержащий текст, таблицы, иллюстрации. Толкование правил в спорных ситуациях исключительная прерогатива администрации ресурса. ### 2. Создание репозитория и оригинал издания Только привилегированные пользователи могут создавать репозитории, поэтому для создания репозитория отправьте письмо по адресу электронной почты [create@retype.r4in.tk](mailto:create@retype.r4in.tk) с темой письма `[create repository]`, в теле письма в первой строке укажите ed2k- или torrent-ссылку на оригинальное издание, во второй строке укажите ваше имя пользователя. Будет создан соответствующий репозиторий, к которому вам будет предоставлен доступ. **В перенаборе отдельных публикаций в рамках данного проекта может быть отказано.** Оригинальное издание должно находиться в открытом доступе в пиринговых сетях, если его там нет, опубликуйте его в torrent или ed2k сети. Если оригинальное издание в нескольких файлах, то файлы объединяются в один ZIP-архив. Если оригинального издания нет в открытом доступе, но печатное издание находится в вашем владении, то отсканируйте его, включая обложку, форзацы, и все страницы, в том числе страницы с технической информацией об издании. Если вы не можете обеспечить доступность оригинального издания в пиринговых сетях, отправьте файл с оригинальным изданием или ссылку на него по адресу электронной почты [orig@retype.r4in.tk](mailto:orig@retype.r4in.tk) с темой письма `[original publishing]`, если оригинальное издание ещё не использовалось для перенабора, то вам будут высланы ссылки ed2k и magnet на оригинальное издание, а также издание будет добавлено в список изданий запланированных к перенабору. #### 2.1. Именование репозитория Репозитории именуются как rt-g0_hhhhhhhh-краткое_наименование_книги-язык где * *hhhhhhhh* - последние 4 байта хэша SHA3-256 от файла оригинального издания в шестнадцатеричном представлении. Буквы набраны строчными. Если оригинальное издание в нескольких файлах, то все файлы объединяются в один ZIP-архив. Получить хэш SHA3-256 от файла оригинального издания можно командой `rhash --sha3-256 имя_файла_оригинального_издания` * *краткое_наименование_книги* - набирается строго латинницей и представляет короткую последовательность, позволяющую идентифицировать книгу. Все пробелы заменяются знаками подчёркивания "`_`". Набор русских слов осуществляется в соответствии с правилами транслитерации любым, но только одним вариантом. ```plaintext Правила транслитерации (прочерк - буква опускается): |русская буква: |а|б|в|г|д|е |ё |ж |з|и|й|к|л|м|н|о|п|р|с|т|у|ф|х |ц |ч |ш |щ |ъ|ы|ь|э|ю |я | |английский вариант:|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. Описание репозитория Описание репозиториев набирается по шаблону: ```plaintext Фамилия И. О., Фамилия И. О. [автор(ы)] -- "Название книги" [в двойных кавычках] Дополнительные сведения об издании, номер редакции [если есть] -- [если книга переведена, то указываются переводчики в следующем виде] перевод с языка [наименование языка] Фамилия И. О., Фамилия И. О. [если важна редактура, то указываются научные редакторы в следующем виде] под редакцией Фамилия И. О., Фамилия И. О. -- nnnn год [nnnn - год издания] ``` Пояснения в квадратных скобках не набираются. #### 2.3. Файловая структура репозитория ##### 2.3.1. Файл README.md Файл `README.md` набирается по шаблону: ```Markdown *Фамилия И. О.* [первый автор] *Фамилия И. О.* [второй автор, и далее указываются все авторы] **Название книги** Дополнительные сведения об издании, номер редакции [если есть] [если книга является переводом, указать с какого языка и Фамилии И. О. переводчиков, в ином случае следующая строка не набирается] *перевод с наименование языка Фамилия И. О., Фамилия И. О.* [если важна редактура, то указываются Фамилии И. О. научных редакторов, в ином случае следующая строка не набирается] *под редакцией Фамилия И. О., Фамилия И. О.* nnnn год [nnnn - год оригинального издания, указать все 4 цифры] #### Оригинал ed2k       torrent #### Замечания по сборке 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-создание-репозитория-и-оригинал-издания)". ##### 2.3.2. Основной файл проекта Основной файл проекта это tex-файл, названный по следующему шаблону: Familiya_I.O.,Familiya_I.O.-Nazvaniye_knigi[Eth_ed][NNNNy]-language.tex где * *Familiya_I.O.* - фамилия и инициалы автора(ов) набранные латинницей в соответствии с правилами транслитерации из раздела "[2.1. Именование репозитория](#21-именование-репозитория)", все пробелы заменены на знак подчеркивания "`_`"; * *Nazvaniye_knigi* - название книги набранное латинницей в соответствии с правилами транслитерации из раздела "[2.1. Именование репозитория](#21-именование-репозитория)", все пробелы заменены на знак подчеркивания "`_`"; * *E* - номер редакции при налиции такового, в ином случае этот блок, включая квадратне скобки пропускается; * *NNNN* - год издания оригинального издания с указание всех четырёх цифр; * *language* - английское именование основного языка оригинального издания (русский - russian). ##### 2.3.3. Файл definitions.tex Файл `definitions.tex` содержит все включения (`\usepackage`,`\RequirePackage`), настройки (геометрические, языковые, форматирования) и определения, используемые в документе. Исключение составляют только пакеты, включение которых необходимо строго до определения класса документа. Файл `definitions.tex` включается директивой `\input{definitions.tex}` в основной файл проекта сразу после определения класса документа следующим образом: ```TeX \documentclass{класс_документа} \input{definitions.tex} ``` Таким образом обеспечивается единое местоположение всех настроек документа и определений окружений оформления. ##### 2.3.4. Сценарий сборки Сценарий сборки представляет собой sh/bash-сценарий, с именем `build_script`, который, будучи запущенным, осуществляет окончательную сборку проекта в подкаталоге `build`. При написании сценария сборки полезно помнить, что для обновления ссылок и оглавления (toc) необходимо дважды запустить сборку, а для формирования предметного указателя и сопутствующих файлов - трижды. ### 3. Перенабор издания #### 3.1. Набор текста Текст набирается исходя из того, что сборка будет осуществляться программами [XeTeX/XeLaTeX](http://xetex.sourceforge.net/) с использованием пакетов [polyglossia](https://ctan.org/pkg/polyglossia) и [xltxtra](https://ctan.org/pkg/xltxtra). Программа XeTeX и сопутствующие пакеты поставляются в составе дистрибутива [TeX Live](https://www.tug.org/texlive/). При необходимости допускается включение [Lua](http://www.lua.org/)-скриптов для сборки проекта системой [LuaTeX](http://www.luatex.org/), однако необходимость этого должна быть убедительно обоснована в первом комментарии в основном файле проекта. Текст набирается в исходном файле с расчётом на ширину терминала 80 символов за исключением случаев, когда синтаксис не допускает переноса. Перенос по границе 80 символов осуществляется строго вместо пробела простого текста или в окружениях допускающих такой перенос. Форматирование оригинального текста, а именно отступы, относительные размеры шрифтов, семейства шрифтов по возможности сохраняются, так как могут нести смысловую нагрузку. Отступы yказываются в долях от значений `\paperwidth` и `\paperheight` #### 3.2. Структура Структура документа полностью восстанавливается в строгом соответствии с оригинальным изданием. Если структура оригинального издания не соответствует типовой структуре книги, то соответствующие изменения должны быть внесены в cls-файл, описывающий класс документа. Базовым классом, на основании которого строится новый cls-файл, является `extbook`. Любой структурный элемент книги должен иметь метку `\label` для возможности сослаться на него. #### 3.3. Набор таблиц Короткие по высоте таблицы выполняются в окружении `tabular`. Длинные по высоте таблицы выполняются в окружении `longtable` пакета [longtable](https://www.ctan.org/pkg/longtable). Набор таблиц осуществляется с указанием строго относительных размеров столбцов к переменной `\linewidth` или, при необходимости, `\textwidth`. Для расчёта размеров столбцов использовать пакет [calc](https://www.ctan.org/pkg/calc) и значение `\tabcolsep`. Использование иных пакетов и окружений для оформления таблиц должно быть строго необходимым и необходимость объяснена в комментарии перед такой таблицей, так как другие пакеты иногда приводят к нежелательным артефактам в сборке. #### 3.4. Набор формул Формулы в строке набираются в окружении `$формула$`. Многострочные и отдельные формулы набраются в окружениях `equation`. Использование иных окружений для набора формул должно быть строго необходимым и необходимость объяснена в комментарии перед такой формулой, для избежания артефактов в сборке. Обращайте внимание на наличие в математических шрифтах используемых символов, так как часть символов может быть не описана в шрифте. Сложные формулы-диаграммы набираются в синтаксисе пакета [Xy-pic](http://tug.org/applications/Xy-pic/Xy-pic.html). #### 3.5. Включение иллюстраций Иллюстрации оригинального издания включаются в перепечатку издания по следующим правилам: 1. Иллюстрация должна пропорционально соответствовать оригинальному в разумных пределах. Разумные пределы - один пиксел. 2. Если иллюстрацию можно без значительных затрат времени описать в виде таблицы, тогда иллюстрация оформляется в окружении `tabular`. 3. Если иллюстрацию можно без значительных затрат времени описать в синтаксисе пакета [Xy-pic](http://tug.org/applications/Xy-pic/Xy-pic.html), тогда иллюстрация оформляется в синтаксисе пакета Xy-pic. 4. Если иллюстрация по смыслу использования в оригинале не представляет собой растровое изображение, а является схемой или диаграммой или графиком, в таком случае иллюстрация включается в формате `eps`. При этом в репозиторий также добавляется черновик иллюстрации, который может представлять собой: (а) векторное изображение в формате `svg`, при переносе оригинальной иллюстрации в формат `svg` желательно использовать масштабирование `1 пиксел = 1 миллиметр`, при измерении оригинального изображения в масштабе 1, в ином случае в первом комментарии svg-файла укажите масштаб и условия измерений оригинальной иллюстрации; (б) исходный код программы для математического пакета, который строит требуемый график, в таком случае первым комментарием исходного кода должен быть указан математический пакет и его точная версия вплоть до минорной. 5. Если иллюстрация в контексте оригинала является растровым изображением, то использовать его оригинал со сжатием без потерь в формате [png](http://www.libpng.org/pub/png/). При недоступности оригинала - использовать лучшую доступную копию. Такие требования к иллюстрациям обусловлены тем, что даже в оригинальных электронных книгах издательств можно обнаружить растровые изображения, которые в контексте избыточны, не масштабируются свободно и при определенных условиях приводят к некорректному отображению страницы. Исходя из *принципа разделения представления и содержания*, иллюстрация должна корректно масштабироваться в широком (условно бесконечном) интервале множителей и корректно отображаться при любых настройках представления, например: ![](imgs/vec_example.png) #### 3.6. Ссылки Все внутренние ссылки должны быть соответственно оформлены и работать, включая ссылки на библиографию внутри издания. Все внешние сылки должны быть соответственно оформлены и ссылаться на URL из оригинала издания, даже если он на момент набора не ведет на существующий или релевантный ресурс. #### 3.7. Предметный указатель Предметный указатель формируется пакетом [xindy](http://www.xindy.org/). Ключевые слова инструкцией `\index`отмечаются либо прямо перед ключевым словом внутри абзаца, либо перед абзацем без разделения инструкцией `\par` или двумя символами новой строки, так как в ином случае при сборке координата ключевого слова и сам абзац могут оказаться на разных страницах. Оформление и порядок сортировки описываются в отдельном xdy-файле, в соответствии с таковыми в оригинале. #### 3.8. Технические страницы Технические страницы оригинального издания перенабираются строго в соответствии с оригиналом, даже если перенабор не соответствует заявленной информации. Технические страницы могут отсутствовать, только если оригинал доступен только в копии без технических страниц. Кроме того, при перенаборе добавляется последняя страница набранная моноширинным шрифтом в соответствии с шаблоном: ```TeX %%============================================================================= \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'е; * после завершения перенабора репозиторий будет перенесен в группу, и *адрес_репозитория_с_исходным_кодом* будет содержать другой каталог. Не обязательно вручную добавлять *имя_файла_с_оригиналом_издания*, *размер_данного_файла_в_байтах*, *хэш_ed2k_данного_файла*, *хэш_torrent_файла_с_оригиналом_издания*. edk2k-ссылку можно целиком получить из ed2k-клиента, а magnet-ссылку на торрент можно получить в torrent-клиенте. Если что-то из этого вы сделать не сможете, воспользуйтесь предложением из раздела "[2. Создание репозитория и оригинал издания] (#2-создание-репозитория-и-оригинал-издания)". ### 4. Рекомендации #### 4.1. Принцип DRY и метод переиспользования кода Следование принципу DRY (Don’t repeat yourself) приводит к тому, что имеет смысл перед перенабором пролистать издание и выделить повторяющееся одинаковое форматирование и оформление, после чего создать для такого оформления отдельное окружение, которое потом и использовать. Это снизит вероятность возникновения ошибки. Использование метода переиспользования кода приводит к тому, что имеет смысл не только выделить повторяющееся одинаковое оформление, но и однотипные оформления, отличающиеся лишь некоторыми параметрами (обычно одним). Так, например, если в тексте оригинального издания часто встречаются таблицы из двух столбцов, прижатые вправо и отличающиеся только шириной столбцов, то есть смысл создать единое окружение для таких таблиц, в аргументах которого указывать ширину столбцов. Следует, однако, избегать переусложнённых окружений с множеством параметров на все случаи жизни, такое окружение уже есть и называется TeX. #### 4.2. Предметный указатель Если оригинальное издание содержит предметный указатель, то лучше сначала отсортировать ключевые слова указателя по номерам страниц и добавлять их в ходе перенабора, так как восстановление предметного указателя по ключевым словам в перенабранном тексте довольно трудоёмко. Несколько снизить трудность перенабора предметного указателя позволяют комментарии в исходном коде, разбивающие исходный код на блоки в соответствии с нумерацией страниц оригинала, например такие: ```TeX %% ======================= Страница 235 ======================= ``` #### 4.3. Программа для редактирования исходного кода TeX Для редактирования исходного кода TeX довольно удобно использовать [Kile](https://kile.sourceforge.io) #### 4.4. Программа для отрисовки векторных изображений Для отрисовки векторных изображений рекомендуется использовать [Inkscape](https://inkscape.org). #### 4.5. Программа для измерения иллюстраций и элементов оформления Для измерения иллюстраций и элементов оформления рекомендуется использовать [KRuler](https://kde.org/applications/graphics/org.kde.kruler)