ASCIIDoc для самых маленьких...

...документов.

Данная заметка рассчитана всё-таки на программистов, преимущественно сидящих под Linux. Но даже, если Вы не принадлежите множеству таких сектантов, не проходите мимо! Возможно, Вы откроете для себя что-то новое.

P.S.: Господа программисты, никто здесь не покушается на Вашу пальму интеллектуального первенства. Если Вам кажется, что я буду втирать дичь, exit(127)

Не прошло и суток с момента прошлой публикации, как я снова забыл закусить, и вновь решил написать про замечательный формат ASCIIDoc. В прошлый, если можно так выразиться, раз, я сумбурно и вкратце рассказал про ASCII, текстовые процессоры, воздал анафему Microsoft'у и агитировал, так сказать, за ASCIIDoc. Сегодня же, с новыми силами, я попробую структурированно описать основные прелести, поджидающие нас за углами символьных последовательностей текста.

Итак, сегодняшний план будет таков:

• Что из себя представляет ASCIIDoc?
• Инструменты для работы с текстом.
• Первые шаги
• Cheatsheet

Милости прошу заинтересовавшихся.

Что из себя представляет ASCIIDoc?

ASCIIDoc представляет из себя формат описания текстового документа с возможностью вставки изображений и медиа контента. По сути, документ, написанный в формате ASCIIDoc, можно конвертировать в абсолютно любой из известных нам форматов, хоть как-то связанных с текстом, или медиа: от html до pptx. Оно и не удивительно -- документ ASCIIDoc есть ни что иное, как обычный текст. Интерпретируй, как хошь! Главное, чтобы кто-то написал правила этого преобразования.

Чем же все-таки отличается этот ваш ASCIIDoc от любимого .docx?

Простотой описания (только подумайте, что скрывается в XML вашей курсовой), скоростью создания и правки документов, переносимостью на любые платформы (благо символы ASCII читаются, дерзновенно сказать, любыми системами).

Как я успел похвастаться в предыдущей статейке про, собственно, объект восхваления, на создание приятного документа, который будет одинаково выглядеть и в html, и в pdf, и, в (прости, Господи) .docx, у меня ушло не более минуты, из которой около половины я копировал текст в мой любимый редактор.

И вот тут назревает еще одно преимущество использования ASCIIDoc -- текстовый редактор. Вы можете использовать абсолютно всё, что пожелаете, исходя из собственный эстетических потребностей и/или возможностей рабочей станции (компьютера). По собственному опыту скажу, что для меня до сих пор работа в MS Word на офисном компьютере каждый раз превращается в пятый круг ада. При этом на своём домашнем ноутбуке, работая в любимом NeoVim, я не ощущаю никакого дискомфорта.

Что же умеет ASCIIDoc? -- Всё. Everything.

• Тексты, да жирные с курсивом, да с подчёркиваниями-перечёркиваниями, да цветные-разноцветные
• Списки с таблицами, всяко разно нумерованные, маркированные, нумеровано-маркированные
• Заголовки, подзаголовки, сносочки, дисклеймеры, ссылочки
• Цитаточки-эпиграфы, да с подвыподвехтом
• Картиночки-иконочки, да видосики с музычкой
• Латекс (LaTeX) всяческий, в самых разнообразных извращённых формах

Стоит оговориться, что не все "конечные форматы" поддерживают, например, музычку. Так же будьте аккуратны в том, какой инструмент для работы с ASCIIDoc Вы используете: не каждый из них поддерживает все возможности формата.

И всё это добро еще и настраиваться может под нужды конкретного документа.

Инструменты для работы с текстом

На сегодняшний момент существует некоторое множество инструментов для преобразования текстов ASCIIDoc в любые (почти любые!) виды документов. Одним из любимых, по крайней мере у линуксоидов, является ASCIIDoctor, написанный на языке Perl. Если такой расклад Вам не по душе -- существует вариант на python, который незатейливо называется ASCIIDoc, и разработан, судя по всему, собственно задумщиками формата.

Итак, что нам понадобится?

• Любимый текстовый редактор
• Консоль (опционально. Может, вы используете Atom...)
• ASCIIDoc(-tor).

В сущности, это всё!

Первые шаги

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

Как Вы видите, ASCIIDoc позволяет нам забыть про такие вещи, как слияние по шаблону и т.д. Оно само берет наще имя из аннотации к документу, которая следует сразу после главного заголовка (Обратите внимание, что главный заголовок отделяется знаками "=". Их должно быть столько же, сколько символов в заголовке.)
Также Вы наверняка успели заметить, что имеют место быть аттрибуты начертания текста, такие, как, например, жирный шрифт...

... и курсивый шрифт... А это что такое..? Что же, давайте посмотрим на результат:

Как видите, мы можем задать собственный стиль для каждого участка текста. Здесь важно обратить внимание на три момента:

1. Пробелы очень важны! ASCIIDoc воспринимает пробелы, как окончание/начало слова, и не будет заменять, например "--" на длинное тире, если "--" не окружен разными словами.
2. Пустые строки -- разделители блоков текста. Если не оставить пустую строку перед, скажем, новым подзаголовком, он не станет подзаголовком.
3. Если Вы хотите, чтобы стиль применялся к символу, Вам нужно удвоить выделяющий знак (в данном примере это "#")

Вы ведь читаете содержимое примеров, не так ли?

Ну, здесь всё довольно таки тривиально, несёмся дальше!

Не пугайтесь жирных знаков равенства. Это просто "===", но с лигатурами ^.^

Немного о списках:

Обратите внимание на пустую строку перед подзаголовком! (Там "==". Лигатуры :))

А вот еще несколько интересных особенностей, на которые стоит обратить драгоценное внимание:

А вот комплексный пример)

Стоит отметить, что здесь встречается "[]#...#" и "[]##...##".
Разница в том, что второй вариант работает с символами, и позволяет определять стиль для набора символов (подстроки, части строки...). То же самое, кстати, касается и средств "ужирнения" и "окурсивливания" текста. Например: "*..*" и "**...**" работают немного по разному. Предлагаю Вам поиграться на досуге ;)