Markdown docs

README.md

@@ -46,7 +46,7 @@ export TEXINPUTS=/home/user/latex-template/tex//::.
 ### Опции и примеры
 
 Титульный лист зависит от опции пакета (класса документа):
- 
+
 * `diploma` - ВКР
 * `research` - НИРС
 * `ordinary` - иные документы, например, отчёты по лабораторным, домашним и т.п.
@@ -56,6 +56,8 @@ export TEXINPUTS=/home/user/latex-template/tex//::.
 Его не нужно скачивать. И этот пример проходит `TestVKR`, исключая замечание 
 по количеству страниц.
 
+**Подробнее в [документации](./docs/README.md)**
+
 ### Чего тут нет
 
 Чего тут нет (и не будет, потому что это отдельные сущности):

docs/README.md

@@ -0,0 +1,253 @@
+# BMSTU IU8
+
+Британские учёные выяснили, что НИРС и ВКР -- слова женского рода. :)
+
+## Поля, шрифты...  короче база
+В пакете установлены поля (в мм): 30, 20, 20, 10. Строго говоря размер правого поля не соответствует ГОСТ 7.32-2017, поэтому для выставления переопределения полей в ГОСТовый вариант "30,20,20,15" или в какой-либо другой можно использовать команду:
+```latex
+\newgeometry{a4paper, left=30mm, right=20mm, top=20mm, bottom=15mm}
+```
+
+По умолчанию кегль шрифта установлен в 12 пунктов, но иногда требуют 14. Для выставления этого параметра можно воспользоваться командой:
+```latex
+\KOMAoptions{fontsize=14pt}
+```
+
+## Документация к полям на титульных листах
+
+В пакете существует 3 класса документов: `diploma` (ВКР), `research` (НИРС) и `ordinary` (простой отчёт a la ГОСТ). Каждый из них помимо общих имеет специфичные поля титульного листа.
+Ниже приводятся все доступные поля с описанием (поля обязательно должны быть заполнены, если не указано иное).
+
+##### Общие поля
+
+* Обязательные:
+	* `\student{...}` -- И.О. Фамилия студента;
+	* `\theme{...}` -- тема ВКР/НИРС, у класса `ordinary` -- тип/наименование работы;
+	* `\group{...}` -- группа студента.
+* Опциональные:
+	* `\faculty{Название факультета}{Код}` -- задаёт название факультета на титульном листе, по умолчанию `\faculty{Информатика и системы управления}{ИУ}`;
+	* `\department{Название кафедры}{Код}` -- аналогично для кафедры, по умолчанию `\department{Информационная безопасность}{ИУ8}`.
+
+##### Поля ВКР
+
+* Особенность `\theme{...}`: для ВКРов текст, куда вставляется тема работы выглядит так `РАСЧЁТНО-ПОЯСНИТЕЛЬНАЯ ЗАПИСКА К ВЫПУСКНОЙ КВАЛИФИКАЦИОННОЙ РАБОТЕ НА ТЕМУ: <тема работы>`
+* `\supervisor{...}` -- И.О. Фамилия руководителя ВКР;
+* `\researchConsultant{...}` -- И.О. Фамилия консультанта по исследовательской части;
+* `\designConsultant{...}` -- И.О. Фамилия консультанта по конструкторской части;
+* `\technologicalConsultant{...}` -- И.О. Фамилия консультанта по технологической части;
+* `\economicsConsultant{...}` -- И.О. Фамилия консультанта по организационно-экономической части;
+* `\lawsConsultant{...}` -- И.О. Фамилия консультанта по организационно-правовому обеспечению ИБ;
+* `\normController{...}` -- И.О. Фамилия нормоконтролера.
+
+##### Поля НИР
+
+* Особенность `\theme{...}`: для НИРов текст, куда вставляется тема работы выглядит так `Отчёт по научно-исследовательской работе студента  на тему <тема работы>`
+* `\studentFullName{...}` -- полные фамилия имя и отчество студента;
+* `\profile{...}` -- номер зачётки;
+* `\speciality{...}` -- код специальности (например, 10.05.01) и его расшифровка "в ёлочках";
+* `\specialization{...}` -- код и расшифровка профиля/специализации (пример: `10.05.01\_01 <<Математические методы защиты информации>>`);
+* `\supervisorWithDegree{...}` -- должность, ~~регалии~~ и Фамилия И.О. научного руководителя НИРС (пример: `доцент, к.т.н. Иванов И. И.`);
+* `\supervisor{...}` -- И.О. Фамилия руководителя, который допускает к защите.
+
+##### Поля титульника класса ordinary
+
+* Особенность `\theme{...}`: это тип (заглавие) работы, например "Отчёт о выполнении лабораторной работы", "Домашняя работа" и т.п., после заглавия следует фраза "по дисциплине";
+* Обязательные:
+	* `\discipline{...}` -- дисциплина в именительном падеже;
+	* `\student{...}` -- И.О. Фамилия студента;
+	* `\group{...}` -- группа;
+	* `\supervisor{...}` -- И.О. Фамилия преподавателя;
+* Опциональные:
+	* `\version{...}` -- вариант работы, по умолчанию является пустым и не вставляется в документ;
+	* `\noscorefield` -- отключение поля для оценки, которое выглядит, как в классе `research` (по умолчанию включено).
+
+## Команды структурных элементов
+
+Из ГОСТа 7.32-2017:
+```
+6.2.1 Наименования структурных элементов отчета: 
+"СПИСОК ИСПОЛНИТЕЛЕЙ", % У нас (на ИУ8) не используется, один студент -- одна НИРС/ВКР
+"РЕФЕРАТ", % У нас не используется
+"СОДЕРЖАНИЕ",
+"ТЕРМИНЫ И ОПРЕДЕЛЕНИЯ", 
+"ПЕРЕЧЕНЬ СОКРАЩЕНИЙ И ОБОЗНАЧЕНИЙ", 
+"ВВЕДЕНИЕ", 
+"ЗАКЛЮЧЕНИЕ", 
+"СПИСОК ИСПОЛЬЗОВАННЫХ ИСТОЧНИКОВ", 
+"ПРИЛОЖЕНИЕ" 
+служат заголовками структурных элементов отчета.
+```
+
+Внутренней командой для таких заголовков является `\structure{ЗАГОЛОВОК}`. Она просто вставляет заголовок структурного элемента. Если очень-очень надо, то можно использовать для определения загловков в "ручном режиме". Например, иногда требуют заголовок "ОСНОВНАЯ ЧАСТЬ", хотя в ГОСТ 7.32-2017 это никак не определено, но как говорится кодекс -- это просто свод указаний, а не жёстких законов (с).
+
+#### "Неинтерактивные" команды
+
+`\introduction` -- вставляет заголовок "ВВЕДЕНИЕ".
+
+`\conclusion` -- вставляет заголовок "ЗАКЛЮЧЕНИЕ".
+
+`\tableofcontents` -- вставляет структурный элемент "СОДЕРЖАНИЕ" целиком.
+
+`\abstract` -- вставляет заголовок элемента "РЕФЕРАТ" и абзац содержащий количество рисунков, таблиц, источников и приложений.
+
+#### Перечни сокращений и терминов
+
+`\listofabbreviations` -- вставляет перечень сокращений и обозначений (структурный элемент целиком).
+Чтобы добавить аббревиатуру/акроним в этот перечень, необходимо до `\begin{document}` вставить команды
+```latex
+\newacronym{идентификатор}{АББРЕВИАТУРА}{расшифровка аббревиатуры}
+```
+Идентификатор должен быть уникальным, и в теории отражать смысл сокращения. Например:
+```latex
+\newacronym{cd}{CD}{compact disk} % пример
+```
+
+`\termsanddefenitions` -- вставляет термины и определения.
+В целом всё аналогично сокращениям, следующую команду надо использовать перед `\begin{document}`:
+```latex
+\newglossaryentry{идентификатор}{
+	name={термин},
+	description={определение термина} 
+}
+```
+Пример:
+```latex
+\newglossaryentry{latex}{
+	name={\LaTeX},
+	description={система компьютерной вёрстки} 
+}
+```
+
+В тексте можно ссылаться на сокращение или термин командой, которая вставит само сокращение/термин и гиперссылку на него в перечне:
+```latex
+\gls{идентификатор}  % текст с кликабельной гиперссылкой
+\gls*{идентификатор} % только текст, без ссылки
+\Gls{идентификатор}  % то же самое, но с заглавной буквы
+```
+
+#### Приложения
+
+Начало секции приложений к отчёту ознаменовывается командой `\appendix`. Она выставляет счётчики в 0 и переопределяет команды `\thefigure`, `\thetable`, `\theequation` и `\thelstlisting` так, чтобы оформление нумерации соответствовало ГОСТу.
+
+Каждое приложение должно начинаться с команды `\appendixsection{...}`, которая принимает один аргумент -- название приложения. Например, если в первое приложение помещена большая принципиальная схема:
+```latex
+\appendixsection{Схема принципиальная}
+```
+
+Латех породит заголовок **ПРИЛОЖЕНИЕ А Схема принципиальная** (и ещё вставит его в содержание). Для второго приложения согласно ГОСТу индекс будет Б, третьему --- В и так далее.
+
+Использовать `\section{...}` здесь НЕ СЛЕДУЕТ.
+
+## Список источников
+
+Для формирования списка источников используется пакет `biblatex-gost`. Поэтому смотрим документацию на него и на `biblatex`. Здесь же приводится краткое изложение работы с библиографией.
+
+[Документация](https://mirrors.ctan.org/macros/latex/contrib/biblatex-contrib/biblatex-gost/doc/biblatex-gost.pdf) и [примеры](https://mirrors.ctan.org/macros/latex/contrib/biblatex-contrib/biblatex-gost/doc/biblatex-gost-examples.pdf)  к `biblatex-gost` (дата обращения 28.10.2024)
+
+[Документация к `biblatex`](https://mirrors.ctan.org/macros/latex/contrib/biblatex/doc/biblatex.pdf) (дата обращения 28.10.2024)
+
+#### Общие моменты
+
+*One does not simply get a reference list. (c) Боромир*
+
+Будучи новоиспечённым пользователем латеха, автор сего манускрипта столкнулся со следующими нюансами в работе с библиографией, о которых прежде и не помышлял:
+
+* Сборка с библиографией состоит из трёх этапов:
+	1. компиляция `.tex` ("сборка ссылок");
+	2. запуск утилиты для формирования библиографии из файла `.bib` и `.aux` латеха;
+	3. повторная компиляция `.tex` в окончательный документ.
+* Если ставили неполный дистрибутив латеха, то лучше проверить установлен ли `biber`, так как этот бэкенд используется нашим пакетом (команда `biber --version` в терминале должна выдвать версию утилиты).
+* Поля содержащие дату заполняются в формате `yyyy-mm-dd`, например, дата обращения к электронному ресурсу `urldate = {2024-11-15}`.
+* Если у статьи/книги несколько авторов, то поле `author = {П. П. Первый and В. В. Второй and Т. Т. Тритий and Д. Д. Дейтерий ...}`.
+* ФИО автора записываются в формате "Имя Отчество Фамилия", причём пробелы между именем и отчеством (или их инициалами) обязательны.
+
+Также в `biblatex-gost` желательно использовать поле `media`, которое отвечает за плашки [Электронный ресурс], [Видеозапись] и другие. Его возможные значения:
+
+* videorecording --- видеозапись,
+* soundrecording --- звукозапись,
+* graphic --- изоматериал,
+* cartographic --- карты,
+* kit --- комплект,
+* motionpicture --- кинофильм,
+* microform --- микроформа,
+* multimedia --- мультимедиа,
+* music --- ноты,
+* object --- предмет,
+* manuscript --- рукопись,
+* text --- текст,
+* braille --- шрифт Брайля,
+* eresource --- электронный ресурс.
+
+#### Книги
+
+`book`/`mvbook` --- книги однотомные/многотомные. Обязательными полями с точки зрения пакета являются `author`, `title` и `year/date`.
+
+`collection`/`mvcollection` --- сборники однотомные/многотомные. Обязательные поля: editor, title, year/date.
+
+#### Статьи
+`article` --- ссылка на статью из журнала и др. сборников статей. Обязательные поля: author, title, journaltitle, year/date.
+
+`periodical` --- ссылка на журнал целиком (правда, зачем оно надо, не очень ясно). Обязательные поля: editor, title, year/date.
+
+#### Стандарты (нормативные документы по стандартизации)
+
+Руководство `biblatex-gost` рекомендует использовать тип записи `@reference` для ГОСТов и других нормативных документов по стандартизации. Пример из документации:
+```latex
+@reference{standard3,
+	heading = {ГОСТ 19790-74},
+	title = {Селитра калиевая техническая. Технические условия},
+	media = {eresource},
+	specdata = {Взамен ГОСТ 1949-65 и ГОСТ 5.1138-71 ; введ. 01.07.05},
+	location = {М.},
+	publisher = {Стандартинформ},
+	year = {2006},
+	pagetotal = {18},
+	series = {Межгосударственный стандарт},
+	langid = {russian},
+}
+```
+
+## Математика
+
+В пакете определены следующие окружения:
+
+* `definition` -- определение
+* `theorem` -- теорема
+* `corollary` -- следствие
+* `lemma` -- лемма
+* `example` -- пример
+
+Соответственно, использование таково:
+```latex
+\begin{example}
+М-м-м... пример примера, фантазия закончилась XD
+$$
+3 + 4 = 2
+$$
+\end{example}
+```
+
+## Листинги
+Для оформления листингов используется пакет `listings`. При этом нашим пакетом добавлено окружение `codelisting`, которое в теории не должно провоцировать машинный нормоконтроль. Пример использования с кодом для SageMath:
+```latex
+\begin{codelisting}[language=Python]
+	upper_limit = 30 # генерируем~элементы~до~30
+	d = 1
+	n = 5
+	dist_arr = []
+	for i in range (0, upper_limit):
+		x = i
+		dist_arr.append(x^(n-1)*exp(-x/d)/(gamma(n)*d^n))
+	gammaD = GeneralDiscreteDistribution(dist_arr)
+	dataset_gamma = [gammaD.get_random_element() for _ in range(1000)]
+	dist_fun_points_gamma = [0] * (max(dataset_gamma) + 1)
+	for i in dataset_gamma:
+		dist_fun_points_gamma[i] += 1
+\end{codelisting}
+```
+
+****
+```
+Файлик написал Fe-Ti (aka Tim Kravchenko) в 2024 году.
+По всем вопросам обращаться в исходный код.
+```