Инструменты, которые я использую для написания книг

Ссылка на оригинал - https://thorstenball.com/blog/2018/09/04/the-tools-i-use-to-write-books/, автор публикации - Thorsten Ball

В начале всегда есть один текстовый файл, не более того. Это называется ideas.md или book.md. Содержит список мыслей и идей, схему. Все остальное растет оттуда. Имеет смысл начать с разговора о файлах.

Файлы

Обе мои книги, «Написание интерпретатора на Go» (Writing An Interpreter In Go) и «Написание компилятора на Go» (Writing A Compiler In Go), написаны на GitHub Flavored Markdown (GFM) . Один файл на главу и все файлы под контролем версий через git.

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

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

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

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

// compiler/compiler.go

func (c *Compiler) emit(op code.Opcode, operands ...int) int {
  // [...]

  pos := c.addInstruction(ins)
  return pos
}

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

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

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

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

Трубопровод

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

Во-первых, файлы Markdown передаются по каналу pp, универсальному препроцессору для текстовых файлов, который может делать много вещей, но который я использую только для замены двух переменных в тексте: URL-адресов читателей папки с zip-кодом, которые можно загрузить, и текущей версия книги.

После этого полученная уценка передается в pandoc - самую важную часть этого конвейера.

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

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

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

Генерация PDF, тем не менее, выполняется с использованием LaTeX и требует шаблона, написанного на LaTeX. Я соединил свои воедино из стандартного шаблона Pandoc и того, что дали мне Stack Overflow, часы проб и ошибок, а также просветление и ужас, которые были «черт побери, вы знали, что у LaTeX есть собственный менеджер пакетов?». Я люблю трогать его только тогда, когда это абсолютно необходимо. В конце концов, это не имеет большого значения.

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

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

Когда окончательные файлы выпадают из конвейера, я объединяю их в ZIP-файл вместе с папкой, которая содержит весь код, представленный в книгах. Готово к публикации.

Публикация

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

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

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

Издания в мягкой обложке продаются, печатаются по требованию и отправляются Amazon Kindle Direct Publishing (KDP). Я загружаю готовую к печати обложку и PDF-версию книги, и Amazon превращает ее в книгу в мягкой обложке, которую можно купить в семи разных магазинах Amazon. Createspace - это то, что я ранее использовал для этого, но после того, как Amazon купил Createspace, они начали перемещать функциональность Createspace в KDP. К настоящему времени я полностью переключился и использую только KDP. Еще один инструмент для беспокойства, так как я все равно использовал KDP для публикации Kindle-версии книг в магазинах Kindle.

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

Затем читатели могут приобрести мои книги, как и любой другой продукт на Amazon, включая Prime shipping, возвраты и все способы оплаты, принятые Amazon. Недостатком всего этого является потеря контроля для меня. Я не могу, например, предложить персональные коды купонов, а также не могу связать книгу в мягкой обложке с изданием электронной книги.

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

Самый важный бит

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

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

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

Не нашли ответ на свой вопрос? Возможно, вы найдете решение проблемы на нашем канале в Youtube! Здесь мы собрали небольшие, но эффективные инструкции. Смотрите и подписывайтесь на наш youtube-канал!

Смотреть на Youtube