Искусство программирования для Unix - Эрик Реймонд

Большинство систем разметки документов поддерживают макросредства. Макросы являются определяемыми пользователями командами, которые с помощью подстановки текста разворачиваются во встроенные запросы разметки. Обычно данные макросы добавляют в язык разметки структурные функции (такие как возможность объявлять заголовки разделов).

Наборы макросов troff (mm, me и мой пакет ms) были фактически предназначены для того, чтобы увести пользователей от редактирования, ориентированного на форматирование, в направлении редактирования, ориентированного на содержание документов. Идея заключалась в отметке семантических частей и в последующем использовании различных стилевых пакетов, которые "знали бы", следует ли выделять в данном стиле заголовок жирным шрифтом или нет, центрировать его или нет, и так далее. Таким образом, в одной точке был набор макросов, которые пытались имитировать ACM-стиль, и другой набор, имитировавший стиль Physical Review, но использующий базовую разметку -ms. Все эти макросы не имели успеха у людей, которые сосредотачивались на создании одного документа и управлении его внешним видом, так же как Web-страницы "тонут" в дискуссиях о том, кто должен управлять внешним видом, — автор или читатель. Я часто встречал секретарей, которые использовали команду .AU (author name — имя автора) только для того, чтобы выделить текст курсивом, заметив, что она выполняет это действие, а затем сталкивались с трудностями при использовании других эффектов команды.

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

18.2. Стиль Unix

Стиль документации в Unix (и инструментов для подготовки документов) имеет несколько технических и культурных особенностей, которые обособляют его от способа создания документации в других системах. Понимание данных характерных особенностей, во-первых, создаст основу для понимания того, почему программы и практические приемы выглядят именно так, и во-вторых, почему документация читается именно таким способом.

18.2.1. Склонность к большим документам

Средства подготовки документов в Unix всегда были предназначены, главным образом, для разрешения трудностей, связанных с компоновкой крупных и сложных документов. Первоначально такими документами были патентные заявки и техническая документация. Позднее — научные и технические статьи и техническая документация всех видов. В результате большинство Unix-разработчиков научились ценить средства разметки документов. В отличие от PC-пользователей того времени, Unix-культура не была под впечатлением WYSIWYG текстовых процессоров, когда они стали широко доступными в конце 80-х годов и в начале 90-х годов прошлого века. Даже среди молодых современных Unix-хакеров достаточно необычно встретить того, кто действительно отдает предпочтение WYSIWYG-системам.

Неприятие трудных для понимания двоичных форматов документов и особенно непонятных частных двоичных форматов также сыграло свою роль в отклонении WYSIWYG-инструментов. С другой стороны, Unix-программисты с энтузиазмом ухватились за PostScript (современный стандарт языка для управления графическими принтерами) как только документация на язык стала доступной. Данный стандарт точно вписывается в Unix-традиции узкоспециальных языков. Современные Unix-системы с открытым исходным кодом имеют превосходные инструменты для работы с форматами PostScript и PDF (Portable Document Format).

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

Привязанность Unix к системам разметки часто высмеивается как предубеждение или характерная черта замкнутых хакеров, но не является ни тем, ни другим. Так же как считающийся "примитивным" CLI-стиль, Unix во многих случаях лучше, чем GUI-интерфейсы, адаптируется к потребностям опытных пользователей, ориентированная на разметку конструкция таких инструментов, как troff(1), подходит для потребностей опытных компоновщиков документов лучше, чем WYSIWYG-программы.

Уклон традиции Unix в сторону больших документов не только привязывает разработчиков к форматерам на основе разметки, подобным troff, но также и заинтересовывает их в использовании структурной разметки. История развития документирующих средств Unix является историей прерывистого, запутанного и непостоянного движения в общем направлении от разметки уровня представления к структурной разметке. В середине 2003 года данная миграция все еще не была закончена, но ее конец близок

Развитие World Wide Web означало, что способность отображать документы в различных средах (или, по крайней мере, печатать и отображать HTML-документы) стало после 1993 года главной задачей для инструментов документирования. В то же время даже обычные пользователи под влиянием HTML более комфортно стали воспринимать системы, ориентированные на разметку. Это привело непосредственно к росту заинтересованности в структурной разметке и изобретению XML после 1996 года. Внезапно давняя склонность Unix к системам разметки стала восприниматься скорее как перспективная, нежели реакционная.

Сегодня для Unix характерна наиболее передовая разработка основанных на XML средствах документирования с использованием структурной разметки. Но в то же время Unix-культура еще должна освободиться от прежней традиции систем разметки уровня представления. "Скрипучий, лязгающий, бронированный динозавр", каковым является troff, только частично был вытеснен языками HTML и XML.

18.2.2. Культурный стиль

Большая часть документации по программному обеспечению написана "техническими писателями", стремящимися найти наименьший общий знаменатель незнания — "умное написание для неосведомленных". Документация, которая поставляется с Unix-системами, традиционно пишется программистами для коллег. Даже если документация не написана программистами для программистов, то она часто находится под влиянием стиля и формата огромной массы такой документации, поставляемой с Unix-системами.

Данные различия можно объединить одним замечанием: man-страницы в Unix обычно содержат раздел, который называется "BUGS" (ошибки). В других культурах "технические писатели" пытаются придать продукту лучший вид, минуя известные ошибки или касаясь их вскользь. В культуре операционной системы Unix разработчики беспощадно описывают известные недостатки своего программного обеспечения, а пользователи рассматривают краткий, но информативный раздел "BUGS" как обнадеживающий знак качественной работы. Коммерческие дистрибутивы Unix, нарушившие данное соглашение, либо исключив раздел "BUGS", либо заменив его название более мягкими формулировками "LIMITATIONS" (ограничения) или "ISSUES" (проблемы), или "APPLICATION USAGE" (использование приложения), неизменно приходят в упадок.

Тогда как большая часть остальной программной документации часто колеблется между "непонятностью" и чрезмерно упрощенным, снисходительным изложением, классическая Unix-документация пишется в сжатом стиле, но вместе с тем является полной. Она "не ведет читателя за руку", а обычно указывает верное направление. Данный стиль предполагает активное чтение, при котором читатель способен сделать очевидный, но не высказанный вывод, на основе написанного и обладает достаточной уверенностью, чтобы доверять своим заключениям.

Unix-программисты склонны хорошо писать справочники, и большинство документации в Unix имеют вид справочников или памяток для тех, кто думает подобно создателю документа, но еще не является экспертом в данном программном обеспечении. Результаты часто выглядят гораздо более загадочными и редкими, чем являются в действительности. Каждое слово документации необходимо читать очень внимательно, поскольку все, что необходимо знать, в ней, вероятно, имеется, а недостающие выводы можно сделать самостоятельно. Необходимо вдумчиво читать каждое слово, так как сведения редко повторяются дважды.

18.3. Многообразие форматов документации в Unix