Образование и саморазвитиеРабота и карьераСтатьи

От Markdown до бумаги — как написать книгу с контролем версий

uniti 2

Это перевод статьи Торстона Бола, разработчика и автора двух книг про программирование на GO.

Всё начинается с одного текстового файла — ничего лишнего. Он называется идеи.md или книга.md. Он содержит список идей и мыслей, общий план. Всё остальное начинается с этих файлов. Логично, что мы начнем разговор именно с них.

Файлы
Обе мои книги «Пишем интерпретатор в GO» и «Пишем компайлер в GO» написаны на разметке GitHub Flavored markdown (GFM). Один файл на главу и все файлы под системой контроля версий git.

Я использую минимальный набор функций markdown в своих текстах: заголовки, выделения, списки, ссылки, картинки, цитаты, и огороженные блоки кода. Последний пункт заслуживает особого внимания, потому что каждый кусочек кода в исходниках представлен в виде «` огороженного блока«` (ориг. fenced code blocks)

Да, вы правильно подумали, что такое решение имеет кучу недостатков. Хоть у меня и установлено выделение синтаксиса для таких блоков, редактировать их не так просто, как, например, если бы они хранились в виде отдельных файлов. Что хуже, код тоже дублируется: одна версия живет в виде файла markdown, а другая (или их несколько) хранится в папке с кодом, которая поставляется с книгой. Если мне нужно обновить строку кода в книге, приходится вручную обновлять каждую копию.

Да, трудоемко, но в этом подходе есть одно неотвратимое приемущество: это работает, и работает именно так, как я хочу. Существует довольно много инструментов, чтобы вставлять код в файлы markdown, но ни один из них не позволяет мне отображать изменение части кода.

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

code_block

Я не знаю ни одного инструмента, который позволяет такое делать. Они либо встраивают куски кода, или целого файла. И да, этот файл может быть *.diff, но даже его придется генерировать отдельно и заранее. Поэтому я решил использовать огороженные куски кода.

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

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

Я написал две книги и ни одного инструмента. Я считаю это успехом.

Техпроцесс
Конечно читателям я отправляю не сырой текст, а красиво оформленные файлы PDF, ePub, Mobi и HTML. Создаю я их с помощью минимального набора инструментов: pp, pandoc и KindleGen. Все вместе они составляют техпроцесс:

book_tool_pipeline

Файлы markdown пропускаются через pp — стандартный препроцессор для текстовых файлов. Им я пользуюсь только чтобы заменять две переменных в тексте: ссылку на архив с кодом, который читатели могут скачать с текущей версией книги.

После этого, получившийся markdown передается в pandoc, самый важный элемент процесса.

Кратко о том, что делает Pandoc.  Он берет текст в одном формате и выводит в другом: markdown на входе, HTML на выходе. И наоборот: если на входе HTML, на выходе будет markdown. Или если скормить ему markdown можно получить DOCX, ODT, PDF, AsciiDoc, или любой другой из множества поддерживаемых форматов.

В моем техпроцессе, Pandoc забирает файлы markdown и с небольшим количеством метаданных в формате YAML превращает его в PDF, HTML и ePub. Результат выглядит хорошо и со стандартными настройками, но у меня есть свой шаблон для каждого из этих форматов.

Полученный HTML это один файл со встроенным в <head> CSS, его очень легко стилизовать. Тоже самое касается ePub, который по сути представляет собой ZIP архив с файлами HTML, и я его почти не трогаю, потому что он хорошо выглядит из коробки.

Но PDF генерируется с помощью LaTeX и требует шаблона, написанного на LaTeX. Я собрал свой из стандартного pandoc и часов проб и ошибок, поиска на Stack Overwlow, а так же ужаса и прозрения, которое я испытал узнав что у LaTeX есть своя система управления пакетами. Теперь я залезаю туда как можно меньше и только по необходимости. В конце концов, это не очень влияет на конечный результат.

То, что я получаю на выходе выглядит прекрасно, и Pandoc без сомнений и преувеличений, один из лучших инструментов, которые я когда-либо использовал. Он делает то что обещает, документация блестящая, он активно и тщательно поддерживается и ещё ни разу меня не подводил. Если бы надо было сократить этот пост до одного слова, я бы оставил «Pandoc».

Единственное чего он не может — это выдавать файлы Mobi, которые Amazon использует в своих электронных книгах Kindle и в магазине. Для этого я использую инстурмент для командной строки KindleGen, который переваривает ePub, созданный Pandoc в Mobi. Не нужно никаких стилей или шаблонов.

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

Теоретически я конечно могу открыть свой магазин, и через него продавать, но я хочу писать книги, а не веб-приложение для продажи книг. Особенно если придётся связывается с налогами и международной аудиторией. Поэтому я использую два сервиса, которые об этом заботятся вместо меня.

Первый называется Gumroad. Я использую его чтобы продавать и распространять электронную версию. Я загружаю ZIP архив, Gumroad принимает платеж по PayPal или по карте и отправляет файл читателю в обмен на довольно маленьккую комиссию. Сервис так же занимается налогами за меня и я могу устанавливать цену без каких либо ограничений, управляю возвратами, отправляю обновленные версии и создаю промо-коды. После двух лет использования, я по прежнему очень доволен сервисом. Единственное, чего мне не хватает: больше вариантов оплаты и региональные цены, чтобы можно было снизить цену для читателей из индии.

Бумажные версии продаются, печатаются по запросу и доставляются через Amazon Kindle Direct Publishing (KDP). Я загружаю готовую к печати обложку и PDF версию книги, а Amazon превращает ещё в физическую книгу, которую можно купить в его семи магазинов Раньше я пользовался Createspace но после того, как их купил Amazon, они начали переносить его фукнционал в KDP. Теперь я полностью перешел на KDP.

Для меня, как человека, который начинает потеть когда слышит в одном предложении «CMYK», «RGB» и «тебе надо кое-что поменять в жизни», создание готовых к печати экземпляров может быть тяжеловато. Но для этого пригождается LaTeX. В отдельном шаблоне, который я использую с Pandoc, я устанавливаю размеры формата и поля документа, а LaTeX разбирается со всем остальным.

Читатели, которые покупают мои книги как любой другой товар в Amazon: включая доставку Prime, возвраты и все способы оплаты им поддерживаемые. Минус такого подхода — это потеря контроля. Например, я не могу создать персонализированные промо-коды или продавать бумажную версию вместе с цифровой.

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

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

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

Важно в инстурментах то, что они не должны вам мешать. Вы должны беспокоится не о том как вносить текст в файл, а что вносить. Как только вы сможете уверенно это делать — с автосохранением и возможностью редактировать без усилий — продолжайте. И продолжайте ещё. Когда у вас будет что-то, что будет достойно печати, начинайте волноваться по поводу инструментов.

Торстену можно написать в твиттер: @thorstenball или письмом на [email protected]