Совместная работа над документацией по LibreOffice

Статья о том, как организовать работу по написанию и переводу официальной документации LibreOffice.

Когда я работал над руководством по LibreOffice Math, то я работал в одного. Ни на кого не оглядывался и ни от кого не зависел.

Сейчас над переводом официальной документации LibreOffice трудится как минимум 3 человека, что создает определенные трудности. Самая большая – контроль изменений. Нужно избегать повторной работы, но в то же время, очень тяжело и муторно согласовывать каждую правку. Конечно, в LibreOffice есть функция контроля версий и отслеживания изменения, но она не очень удобна в нашем случае.

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

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

Я много думал о том, как нам устроить процесс. Прежде всего, я думал о процессе вёрстки. Мало написать или перевести руководство, его же еще надо привести к удобному виду и желательно распространить в нескольких форматах. И это очень утомительное занятие.

Мне кажется, что я нашел лучший выход из ситуации. Заключается он в использовании связки Markdown, ReText (Geany тоже очень удобен), Pandoc, Git и GitHub. А как же LibreOffice спросите вы. Не волнуйтесь, ему тоже отведено место в этой связке, но не главное.

Markdown — облегчённый язык разметки. Подробнее о нем можно прочитать здесь: http://mydebianblog.blogspot.ru/2012/09/markdown.html.

ReText — редактор для Markdown и reStructuredText. Подробнее о нём: http://habrahabr.ru/post/161669.

Какие преимущества и возможности открываются перед нами?

1. Простота и элегантность. Настоящий unix-way! Обычные текстовые файлы, которые можно редактировать с предельной легкостью в любом текстовом редакторе, хоть в блокноте. А изменения отслеживать с помощью Git и ему подобных систем, без дополнительных настроек.

2. Единообразие. Независимо от программ и методов работы, все документы будут оформляться на лету в едином стиле.

3. Переносимость и кроссплатформенность. Работать над документацией можно будет в любом месте и в любое время. Мы не будем зависеть ни от операционных систем, ни от злых сисадминов на работе, ни от специфичного программного обеспечения. Писать документацию можно в Блокноте, на смартфоне в дороге, в любой операционной системе. А самое главное, писать ее может любой человек, не обладающий специфическими навыками.

4. Контроль версий и синхронизация. Использование всей мощи Git и GitHub. Все о чем мы мечтали! Контроль версий лучше всего работает с простыми текстовыми файлами. И данное обстоятельство как нельзя лучше подходит нам.

5. Удобное конвентирование в разные форматы. Это самое приятное для меня обстоятельство. Одной командой можно получить документ в любом формате: odt, pdf, html, LaTeX, Epub и др. Я уже провел эксперимент по конвертации в Epub. Так легко создавать электронные книги у меня не получалось никогда!

6. Дополнительные плюшки. Markdown используется в движке MediaWiki. Он также используется в Python Sphinx. Он легко конвертируется в html.

Документация по LibreOffice без использования LibreOffice?

ДА! На самом деле, LibreOffice будет использоваться в самом конце, исключительно для создания качественной и красивой odt и pdf версии руководства. Конечно, можно было бы с помощью LaTeX создать pdf-версию, но я предпочитаю делать гибридные PDF, доступные простым пользователям LibreOffice.

Шик ситуации в том, что Markdown может быть конвертирован в odt. А дальше требуется только заменить стандартные стили, на наши фирменные. Естественно, используя поиск и замену по стилям.

А что с формулами, таблицами, сносками и т.д.?

Markdown все это отлично поддерживает. Даже формулы! Между прочим, с помощью модуля MathJax.js можно вводить формулы используя синтаксис LaTeX.

В заключении

Связка Git и Markdown представляется мне идеальной. Использование только LibreOffice, не даст нам такой эффективности и легкости. А LibreOffice в связке с Git наоборот создаст дополнительные трудности.

Пример работы с Markdown описан в статье Упрощаем публикацию статей в Blogger (Blogspot).

Сегодня постараюсь написать еще одну статью на тему использования Markdown и LibreOffice.