WYSIWYG полезная штука, но напрягает, с первого дня знакомства. Еще тогда на информатике меня учили, сперва набирай текст, потом форматируй, форматируй по правилам, отступами, никаких пробелов. И уже тогда было понятно, что форматирование можно как то и автоматизировать, что бы само. Причем уже тогда этот 2003 word висел на далеко не самых мощных школьных компах. И уже тогда ситуации с непонятно куда уехавшими картинками и таблицами были далеко не редкостью.
Но веселье продолжилось, я поступил в университет, понадобился текст с формулками. И если у фанатов сапера и пасьянсов вот такие штуки вызывают интерес, то у меня эти попытки попасть в эпсилон и омегу отнимали все мои вечера.
А ведь сколько сюжетных игр можно было пройти, знал бы я тогда хотя бы про tex подобный синтаксис в libreoffice. Но в то время сам факт использования компьютера был признаком высоких технологий и годной скорости выполнения работы, а уж то, насколько грамотно там подобран софт, никого особо не беспокоило.
Потом наступило время LibreOffice под линуксами. Дистрибутив с его 100-200МБ по меркам M$ был невесомым, появилась возможность открыть страницу и забыть. А еще можно было конвертировать из него pdf, что давало возможность открывать написанные в нем отчетики на любом компьютере. Опять же гораздо более приятная возможность набора сложных математических выражений кодом. Да и в целом мне эта штука казалась гораздо более стабильной в плане форматирования и сохранения адекватного вида документа после внесения изменений. Но все равно были проблемы, временами нужно было передавать документ тем, у кого только MS Office. И если конвертация и была теоретически возможной (имелся такой пункт в контекстном меню), то на практике с аккуратно отформатированным текстом происходило нечто ужасное. В общем если документ после конвертирования формально и существовал, то читать его было уже невозможно.
Шло время, и я насмотрелся на то как оформляются солидные opensource проекты, такие как speex. У них обязательно в комплекте есть подробная инструкция в формате pdf, и генерируют её обычно через издательскую систему LaTex. А это пост про то как настроить LaTex под простенькую инструкцию.
Сперва его нужно установить, можно конечно поставить с умом и выбрать только нужные пакеты. Но проще поставить сразу всё, займет это больше 100 МБ, немного не оптимально, зато быстро и без проблем. Поставщик теха сегодня это проект texlive:
sudo apt install texlive-full
Теперь о настройках, большую часть форматирования задает шаблон, я выбрал стандартный шаблон статьи. Весь остальной функционал, добавляемый к основному редактору хранится в пакетах. Мне понадобились:
- listingsutf8 для вставок с исходным кодом
- hyperref для вставок гиперсылок
- graphicx для добавления рисунков в формате png
- underscore для того, что бы на нижние подчеркивания в тексте не ругался (обычно оно используется для обозначения нижнего индекса)
\documentclass[12pt,a4paper]{article}
\usepackage[utf8]{inputenc} % кодировка утф8
\usepackage[T2A]{fontenc}
\usepackage[russian]{babel} % локализация
\usepackage{graphicx} % чтоб картинки вставлять
\graphicspath{ {pic} } % путь до картинок
\usepackage{listingsutf8}
\lstset{
extendedchars=\true, % для вставок кода
inputencoding=utf8,
keepspaces=true}
\usepackage{hyperref} % оформление ссылок
\usepackage{blindtext}
\usepackage{underscore} % отдельный пакет для нижнего подчеркивания
%\usepackage{amsmath} % для формул
%\usepackage{amsfonts}
%\usepackage{amssymb}
%\usepackage{color}
%\color[named]{BrickRed}
%\pagecolor[named]{Green}
\begin{document}
\begin{titlepage}
\title{Разработка USB устройства ввода в Linux}
\author{Михаил Белкин}
\maketitle
\end{titlepage}
\tableofcontents
\newpage
UTF8 нативная кодировка для Linux, потому и документ редактируется в этой же кодировке, что удобно.
1. listingsutf8
Имеется выбор языка программирования, поддерживаются как и отдельные от основного текста вставки, так и так называемые inline. Замороченные настройки пакета связаны с нежеланием адекватно выводить русскоязычные комментарии. Если в вашем коде все комментарии на английском, что правильно, лучше их убрать. Пример использования в случае с многострочной вставкой:
\lstset{language=c}
\begin{lstlisting}
portPoll();
reportUpdate();
++cnt;
sendReport(gamepadPar.report, &cnt);
\end{lstlisting}
Пример внутритекстовой вставки:
\lstinline{FLASH_ACR = PRFTBE | LATENCY_72M;}
2. hyperref
Можно выводить текст ссылок непосредственно, так и делать кликабельные ссылки, пример:
\href{https://github.com/dltech/usb_device3/tree/main/sch}{папке проекта}.
\url{https://github.com/dltech/usb_device3/blob/main/lib/usb_hid.c}
К этому пакету не относится, но полезно не забывать про ссылки внутри документа. Они обеспечиваются командами \ref{label} \label{label}.
3. graphicx
Со вставкой картинок все просто, можно даже настроить путь до папки с картинками. Можно настроить и размер и расположение и обтекаемость текстом, но я насчет этого не заморачивался, а только указывал размер.
\includegraphics[width=7cm]{pcb.jpg}
И jpg и png поддерживаются, проблемы возникнут если захотите добавлять еще и векторные svg. С растровыми же вопросов никаких.
А теперь о верстке целиком. Содержание генерируется автоматически, все что нужно это вывести команду \tableofcontents. Поддерживается аж три уровня иерархии заголовков: \section, \subsection, \subsubsection. А если мало заголовков, то можно вспомнить про параграфы - \paragraph. А ещё таблицы так же описываются кодом и не нужно сперва их создавать в excel, а потом копировать в word. А самое приятное во всем этом это то, что получающийся в итоге документ всегда ровный, то есть нормально отформатированный, ничего никуда никогда не уезжает.
Пожалуй рассказал все, теперь можно сохранить получившийся текстовик в файле формата tex и запустить команду "pdflatex описание.tex", документ сгенерируется довольно быстро. Можете скачать мой пример инструкции к геймпаду по ссылке и проверить.
Комментариев нет :
Отправить комментарий