После заметки о DSL-е для подсистемы логирования меня попросили рассказать о том, как LaTeX был выбран в качестве инструмента для написания документации. Попытаюсь нижеследующим текстом удовлетворить эту просьбу. Хотя дело это уже очень давнее, наверняка в датах буду путаться.
Вопрос о том, как и чем делать документацию для наших разработок встал перед нами в полный рост где-то лет 7-8 назад, в районе 2005-2006 годов. Поначалу, как, полагаю, и в любом другом стартапе, до своей внутренней документации руки не доходили. То, что нужно было заказчику, без каких-либо альтернатив набиралось в Word-е. И здесь ничего с тех пор не изменилось, уж очень активно бизнес-аналитики/ПМы пользуются режимом Review при совместной работе над документом. Тем не менее, со временем, особенно с ростом удаленной от центра разработки (Гомель) службы эксплуатации (Москва), необходимость написания эксплуатационной документации "для себя" созрела окончательно. Нужно было налаживать этот процесс. Чем тогда попытались заниматься, если мне не изменяет склероз, я и Слава Костин.
Задействовать для написания документации Word лично мне не очень хотелось. У меня было много своих причин не любить Word. Но это были мои личные тараканы, с которыми можно было соглашаться, а можно было и не воспринимать всерьез. Но вот в чем мы сходились, так это в неудобстве совместной работы с .doc-файлами, если они хранятся в Subversion репозитории. Если хранить в Svn текстовый файл, то во многих случаях при одновременном его редактировании несколькими людьми можно было автоматически объединять все изменения не имея конфликтов. doc-файлы же у Word-а тогда были бинарными, об слиянии изменений, сделанных в doc-файле одновременно разными людьми, не могло быть и речи. Вроде бы, существовали какие-то инструменты-плагины для Word-а, которые могли это делать, но было очевидно, что это есть облегчение проблемы, но не ее решение. Поэтому мы стали всерьез рассматривать системы документирования на основе простых текстовых файлов.
Выбор был невелик и пристально рассматривалось всего два варианта: DocBook и LaTeX. Помнится, я еще смотрел в сторону Doxygen-а: там можно было посредством т.н. \page-секций делать весьма большие описания, но все-таки это инструмент для построения справочников по API, а не для полноценных руководств по эксплуатации программных комплексов.
Если я помню правильно, то нам со Славой толком договорится по единому инструменту так и не удалось. Он больше склонялся к DocBook-у, как к стандарту, который поддерживается разными инструментами. Я же был сторонником LaTeX-а. После ряда экспериментов и с тем, и с другим, я тихо начал использовать LaTeX для документирования разработок, за которые я отвечал. А потом заставлял осваивать LaTeX своих подчиненных. В итоге мое небольшое подразделение, получившее впоследствии название транспортного цеха отдела разработки в области транспортных систем, всю документацию по своим продуктам писала сама в LaTeX-е. Эксперименты с DocBook-ом в других командах, насколько я помню, заглохли. Да и вообще дела с документацией после отъезда занимавшейся этим направлением Ирины Агеенко шли ни шатко, ни валко. Специализированный же отдел эксплуатационной документации, организованный осенью 2012-го, стал одним из моих немногих реальных достижений на должности начальника управления. Впрочем это уже другая совсем другая история.
Возможно, я был необъективен по отношению к DocBook-у. Но меня сильно смущали несколько вещей. Во-первых, формат XML. Как-то не сложилось у меня с XML-ем. Когда он используется для автоматического парсинга или генерации, это еще куда ни шло. Но вот создавать его ручками -- это то еще удовольствие. Отсюда вытекало и во-вторых: необходимость использования специализированных редакторов. Кои были, но лучшие из них, помнится, были платными. Да и насколько просто было мержить сгенерированные этими редакторами XML-файлы при одновременных правках -- это был вопрос без внятного ответа. В-третьих, на тот момент не было каких-то удобных инструментов для генерации из DocBook-овских файлов чего-то читабельного. И если преобразовалки из DocBook XML в HTML еще находились и худо-бедно работали, то сгенерировать PDF-ку оказывалось не просто. Нужно было качать что-то написанное на Java, как-то с этим шаманить, и только после этого получать как-то слепленную PDF-ку. Лично у меня это не получалось, хотя Диме Косточко это удалось. С LaTeX-ом мне было намного проще.
Здесь нужно сказать, что к тому моменту с LaTeX-ом я сталкивался уже не в первый раз. Более того, для своих личных нужд я его уже применял. Но обо всем по порядку :)
Сначала я о нем услышал учась в аспирантуре на математическом факультете. Поскольку кандидатские диссертации там люди готовили с большим количеством формул, то в качестве инструментов для верстки текста диссертаций использовался либо такой интересный DOS-овский редактор, как ChiWriter (кстати говоря, один из первых редакторов написанный с использованием принципов ООП), либо же кое-как портированный под DOS вариант LaTeX-а. Мощные компьютеры, на которых можно было пускать 6-й Word были тогда доступны далеко не всем, вот люди и пользовались инструментами, которые нормально работали на старых 286/386-х (а некоторые и на совсем-совсем старых 86-х). Я тогда подрабатывал в университете в лаборатории, где был в наличии принтер, и некоторые диссертанты пользовались им для печати своих материалов. От них я и слышал отзывы и о ChiWriter-е, и о LaTeX-е. LaTeX при этом хвалили больше, объясняя мне на пальцах принципы работы с ним. Хотя я тогда не понимал, как может быть удобен инструмент для верстки, не работающий в режиме WYSIWYG.
Первое же знакомство с LaTeX-ом у меня состоялось где-то в 1999-м, когда пришло время набирать текст своей диссертации, хотя формул там вообще не было :) Для этих целей я приобрел старенький, но очень удобный лаптоп Toshiba 5100/100, на котором стоял MS-DOS и был 7-й MultiEdit. И хотя я изучил взятую в университете методичку по использованию LaTeX-а, прихваченный оттуда же на дискетах дистрибутив LaTeX-а на этом лаптопе не пошел. Но какие-то представления о том, что можно делать в LaTeX-е у меня сформировались.
Затем было активное использование Doxygen-а, который во многом напоминал не только Javadoc, но и LaTeX. Так что, психологически, к работе с LaTeX-ом я был готов. И когда в конце 2003-го мне потребовалось написать что-то вроде учебника по SObjectizer-4, я начал с Doxygen-а, но довольно быстро перебрался под LaTeX.
В качестве дистрибутива я сначала использовал пакет TeX Live, который брал с CTAN (тогда дистрибутив сразу для Windows и Linux помещался на один CD, потом они перешли на DVD). Впоследствии, с чьей-то подсказки (не помню, был ли это Михаил Лёсин, Игорь Мирончик или Дима Косточко) я перешел на MikTeX, о чем совершенно не жалею и рекомендую для Windows-пользователей.
Для изучения LaTeX-а мне потребовалась всего одна дока: где-то в дебрях каталога doc в TeX Live был файлик под именем, похожим на lshort-russian.pdf. Это оказался очень толковый документ, страниц на 60, в котором расписывались все основные моменты использования LaTeX для простых и не очень простых целей. Найти этот документ в Интернете можно и сейчас по названию "Не очень краткое введение в LaTeX" (только с того времени он стал объемнее). Повторюсь, для начала полноценного использования LaTeX-а его оказалось вполне достаточно.
Спустя несколько лет мне попалась замечательная книга Котельникова и Чеботарева "LaTeX по-русски". Именно ей я и пользовался, если мне нужно было разобраться в каком-либо вопросе. В частности то, как вставлять картинки в текст документа я осваивал с помощью этой книги. Очень ее рекомендую.
В общем, к 2005-му у меня уже был собственный опыт создания больших документов в LaTeX. Результаты меня вполне устраивали, пользоваться LaTeX-ом было удобно. И этот опыт хотелось использовать при создании документации для интервэйловских продуктов.
Но прежде, чем предлагать LaTeX в качестве инструмента для документирования я посмотрел и на других похожих зверей вокруг. Для непосвященных нужно сказать, что ядром всех что-то-над-TeX-ов является система TeX, разработанная тем самым Дональдом Кнутом. Автором знаменитого многотомника "Искусство программирования", для верстки которого он и написал METAFONT и TeX (попутно еще познакомив мир с "литературным программированием").
Так вот, ядром системы компьютерной верстки является TeX. Но непосредственно TeX-ом мало кто пользуется, уж больно низкоуровневый это инструмент. Поэтому на его основе разработаны макропакеты для разных целей. LaTeX один из них, очень раскрученный и популярный. Тем не менее, в качестве инструмента для написания документации LaTeX представлялся слишком мощным, хотелось найти что-нибудь попроще. Вроде бы более простым показался ConTeXt, но на тот момент в нем были проблемы с поддержкой русского языка. Смотрел я так же и на LyX, который вполне мог бы использоваться в качестве альтернативы Word-у для технических писателей, но в те времена под Windows в готовом виде он был доступен только в составе cygwin и работал там не очень устойчиво. В конце-концов поиски альтернативного макропакета для TeX-а я забросил и остановился на LaTeX-е.
Вначале мы генерировали два типа результирующего представления из tex-файлов. В первую очередь это были PDF-документы. Которые аттачились в соответствующие разделы нашей корпоративной wiki-системы. По просьбе службы эксплуатации делали и HTML-представления. Этот вариант был удобен для использования на КПК (Palm-ы и PocketPC). Но затем мы перешли исключительно на PDF-ки. Благо теперь смартфоны и планшеты совершенно спокойно переваривают PDF-ы. В любом случае получить то или иное представление документа можно было всего одной командой, без шаманства, как с DocBook-ом ;)
В качестве редактора LaTeX-овских документов я использовал ViM. Хотя есть и специально заточенные под LaTeX редакторы, которыми некоторые мои подчиненные пользовались. Но я предпочитал все делать в ViM-е, и специальных плагинов для LaTeX-а не ставил, хватало того, что ViM умеет "из коробки".
Из-за того, что я пользовался ViM-ом, вопрос автоматической проверки орфографии в документации я не решил. Впрочем, и не решал :) Обычно я сам вычитываю то, что пишу в документации, по нескольку раз. И часть опечаток нахожу сам. Если же была возможность, то отдавал документацию коллегам на корректуру. И таким образом выявлялось много больше ошибок, в том числе и те, которые автоматической проверкой не обнаруживались (например, я часто пишу правильные слова но не в согласованных падежах, что пропускается автоматическими проверяльщиками, но замечается людьми).
Еще одна штука, до которой не дошли руки -- это предметный указатель. Но это, думаю, всего лишь дело техники. Просто насущной необходимости в этом не было, вот и не тратили время на разбирательство.
В целом, я уверен, выбор LaTeX-а себя оправдал.
Разработчики осваивают его легко, особенно если сначала они правят чужие документы, видя как все это организовано. Потом и сами начинают без проблем писать свои документы "с нуля". Вообще, написание документации в LaTeX чем-то напоминает написание программы. Возможно, поэтому программистам с LaTeX-ом подружится несложно.
Нет совершенно никаких проблем с совместным редактированием находящихся под контролем Svn tex-файлов. Это же обычный текст, который мержится не хуже каких-либо других исходников. В самом начале серьезного внедрения LaTeX-а мы совместно с Димой Косточкой работали над одним объемным документом, состоящим из нескольких больших tex-файлов. Тогда часто бывало, что Дима дописывает что-то в конец очередного tex-файла, а я при этом делаю правки в начале этого же файла. По сравнении с Word-ом это были совсем другие ощущения.
Есть, конечно, и свои сложности. Например, если нужно оформить LaTeX-овский документ так же, как какой-нибудь Word-овский. Тут потребуются более серьезные знания тонкостей LaTeX-а, его настроек и дополнительных пакетов. Не так просто вставляются в текст растровые картинки. Большие таблички требуют большего геморроя, чем в Word-е. С другой стороны, есть и свои плюшки. В первую очередь это возможность задавать свои макрокоманды. Например, захотел я, чтобы теги конфигурационных файлов (которые у нас задаются в фигурных скобках), выделялись в тексте курсивом, определил макрокоманду \CfgTagInBrackets. После чего в тексте имена всех тегов указывал посредством этой команды. Если со временем вместо курсива нужно было бы сделать полужирный шрифт, то текст перелопачивать бы не пришлось, нужно было бы всего лишь изменить определение макрокоманды \CfgTagInBrackets в прологе документа. В этот же список плюшек идет и поддержка списка литературы. А так же наличие дополнительных пакетов, например, таких, как listings, который позволяет красиво форматировать фрагменты исходного кода.
В LaTeX-е я набрал много документации. Думаю, что не ошибусь, если скажу, что счет давно перевалил за тысячу страниц, а может и не одну. Из публично доступных образцов моего "литературного творчества" могу упомянуть учебник по SObjectizer-4 (плюс не законченное описание построенных над ним фреймворков) и первый, еще русскоязычный вариант описания Mxx_ru (который затем был любезно переведен на английский язык Михаилом Лёсиным). Да и самую лучшую свою статью, Ruby-новые грани, для RSDN-а я так же писал изначально в LaTeX-е. Но намного больше моего текста осталось в документации внутри Интервэйла.
Подводя итог могу сказать, что если нет жесткой любви к WYSIWYG и автоматической проверки орфографии, то LaTeX может стать отличным инструментом для написания документации. Связываться же с DocBook-ом сейчас вообще вряд ли есть смысл, имхо, интерес к нему уже совсем не такой, как лет 10 назад. Так что стой я сейчас перед выбором системы для написания документации, то с большой вероятностью вновь выбрал бы LaTeX (или ConTeXt).
PS. Кстати, для написания совсем маленьких статеек с последующей конвертацией в HTML можно воспользоваться такой штукой, как reStructuredText (который относится к категории легковесных языков разметки текста). Я им пользовался, действительно удобно. Для маленьких текстов :)
