Оригінал : MultiMarkdown User's Guide
Version 2.0.b6

Автор : Fletcher T. Penney
http://fletcherpenney.net/

Ліцензія : 2005-2009 Fletcher T. Penney.
This work is licensed under a Creative Commons License.
http://creativecommons.org/licenses/by-nc-sa/3.0/

Переклад : Михайло Даниленко isbear@ukrpost.net

Дата оригіналу перекладу : 2012-11-24

Вступ до multimarkdown

Цей документ познайомить вас з multimarkdown — що воно таке, як ним користуватися, як його можна покращити. Документ існує у декількох виглядах: як простий текст, як pdf, як документ Scrivener тощо. Виберіть який вам більше підходить, або зробіть свій власний. Multimarkdown для цього й створювався!

Що таке markdown?

Щоб зрозуміти, що таке MultiMarkdown, треба спочатку розібратися з Markdown. Найкраще визначення markdown знаходиться на сайті Джона Грубера про markdown:

Markdown — це утиліта для перетворення тексту на HTML для мережевих письменників. Markdown дозволяє вам писати тексти у простому на читанні та письмі форматі, а тоді отримувати з нього структурно правильний XHTML (чи HTML).

Отож, «Markdown» представляє собою два поняття: (1) синтаксис для форматування простого тексту; та (2) написаний на Perl інструмент, що перетворює відформатований текст на HTML. Детальніше про правила форматування markdown можна дізнатися на сторінці "Синтаксис". Ви також можете спробувати його прямо зараз за допомогою утиліти «Dingus».

Найголовнішою метою розробки правил markdown є простота читання. Ідея полягає в тому, що відформатований з використанням markdown документ може бути опублікованим як він є (без перетворення у HTML), і при цьому він не буде виглядати, як ніби він розмічений тегами чи іншими інструкціями форматування. Правила markdown увібрали у себе риси декількох існуючих інструментів перетворення тексту на HTML, але найбільший вплив мали правила оформлення електронних листів.

Що таке multimarkdown?

Markdown — це добре, але у ньому не вистачає декількох можливостей, які б доволили його використання для оформлення документів, а не просто шматків веб-сторінок.

Я написав multimarkdown, щоб підважити правила markdown та поширити його на цілі документи, які можна перетворювати з тексту у інші формати, в тому числі у повні документи XHTML, LaTeX, PDF, RTF, чи, навіть (який жах), Microsoft Word.

Правилам markdown, окрім роботи з документом вцілому та перетворення на інші формати, також не вистачало деяких елементів. Мішель Фортін дадав декілька додаткових правил, коли писав PHP Markdown Extra. Деякі з його ідей знайшли місце у multimarkdown.

Джон Грубер може зі мною не погодитися, але я дійсно намагався дотримуватися його поглядів додаючи нові правила у multimarkdown. Риса markdown, що мене найбільше привабила — це його чисте форматування. Читати текстові документи, написані з використанням markdown просто. Форматування логічне, і виглядає як написане для людини, а не для комп’ютера. Наскільки можливо, при роботі над markdown, я намагався тримати це в голові.

Можливо це мені вдалося, можливо ні...

Подібно до подвійного визначення markdown, ви можете розуміти multimarkdown як:

1. Скрипт на Perl для перетвотення тексту на XHTML;
2. Набір правил, що описує перетворення тексту на XHTML;
3. Набір програм (скрипти на perl, команди оболонки, трансформації XSLT, скрипти на php тощо), що використовуються для перетворення тексту на XHTML, і тоді подальшого його перетворення у LaTeX, PDF, RTF тощо.

Як його використовувати?

Ви можете застосовувати multimarkdown декількома різними методами:

• Як консольну програму на perl (типове застосування);
• Як додаток Mac OS X з підтримкою перетягування;
• Як пакунок для TextMate;
• У програмі Scrivener
• На сайтах blosxom чи Oddmuse

Де його взяти?

Пакунок multimarkdown можна звантажити з http://files.fletcherpenney.net/MultiMarkdown.zip.

Інформаця щодо multimarkdown є на моєму сайті http://fletcherpenney.net/MultiMarkdown.

Markdown Джона Грубера (з якого все почалося) знаходиться на його сайті http://daringfireball.net/projects/markdown/.

Версія markdown на PHP Мішеля Фортіна знаходиться на його сайті: http://www.michelf.com/projects/php-markdown/.

Де можна дізнатися більше про multimarkdown?

Як вказано вище, зазирніть на мій сайт.

Також варто переглянути список обговорення multimarkdown:

• http://groups.google.com/group/multimarkdown/
• multimarkdown@googlegroups.com

Якщо ваше питання стосується конкретно Scrivener, може стати у нагоді форум "Literaturee and Latte":

• http://www.literatureandlatte.com/forum/

Швидке уведення до markdown

Короткі базові інструкції для тих, хто поспішає...

Загальні вказівки

1. Звантажте пакунок:

   http://fletcher.github.com/MultiMarkdown/

2. Розпакуйте його.

3. Multimarkdown може працювати звідки завгодно, але найпростіше його встановити у «звичайне» місце:

   • Windows:

     • C:\Documents and Settings\All Users\MultiMarkdown
     • C:\Documents and Settings<користувач>\MultiMarkdown

   • Mac OS X чи *nix

     • ~/Library/Application Support/MultiMarkdown (рекомендовано для Mac OS X)
     • ~/.multimarkdown
     • /Library/Application Support/MultiMarkdown (рекомендовано для Mac OS X)
     • /usr/share/multimarkdown

4. У теці "bin" знаходяться декілька скриптів на perl, призначених для перетворення текстового файлу multimarkdown на XHTML, LaTeX чи PDF. Ці скрипти можуть запускатися звідки завгодно. Можете залишити їх де вони є або встановити у теку, що знаходиться у вашому PATH. Скрипти:

   • mmd2XHTML.pl
   • mmd2LaTeX.pl
   • mmd2PDF.pl
   • mmd2PDFXeLaTeX.pl
   • mmd2letter.pl

5. Щоб запустити один з них, зробіть щось на кшталт цього:

    cd MultiMarkdown
    bin/mmd2XHTML.pl file.txt
   

   де "file.txt" — це файл, що містить multimarkdown, який ви хочете перетворити. Кінцевий файл "file.html" буде створено автоматично.

6. Тепер можете відкривати file.html у веб-переглядачі чи робити з ним що захочете.

Правила оформлення multimarkdown

Уведення до правил розмітки, що використовує система multimarkdown.

Мета-дані

Multimarkdown підтримує мета-дані — це означає, що ви можете додавати інформацію про документ, що може не входити у сам документ.

Мета-дані просто додаються на початку файлу:

Title:  Новий документ  
Author: Флетчер Т. Пенні  
        Джон Доу  
Date:   25 липня 2005 року  

Ключ — це текст перед двокрапкою, дані — текст після неї. Зауважте, що у цьому прикладі для ключа «Author» є два рядки даних. Якщо ви закінчите рядок двома пробілами, при перетворенні на інші формати цей розрив рядка буде збережено.

Секція мета-даних закінчується на першому порожньому рядку, отож вона повинна починатися з самого початку файлу. Метадані прибираються з документа перш ніж передавати його на обробку парсеру.

Хоча це не обов’язково, я рекомендую закінчувати усі рядки мета-даних двама пробілами. Таким чином, якщо ви подасте ваш документ на вхід звичайному markdown, мета-дані будуть правильно відформатовані як звичайний текст з розривами рядків, а не з’єднані у один некрасивий параграф.

Я додав опис деяких «стандартних» ключів мета-даних — вітаються відгуки та побажання щодо розширення цього списку. Якщо ви додаєте не вказані тут ключі, вони додаються до XHTML та LaTeX як користувацькі змінні, які ви можете використовувати як вам заманеться.

Пам’ятайте, що шматки XHTML не використовують мета-дані. Для їх використання ви маєте застосувати Format: complete для створення повних документів XHTML, що після цього можуть передаватися XSLT для створення інших типів документів. Наприклад, я використовую мета-дані для додавання інформації про заголовок, автора, ключові слова та ліцензію у PDF, створенні за допомогою multimarkdown.

Зауваження: Я багато згадую використання цих ключів у документах LaTeX. Це обумовлено тією простою причиною, що вивід у LaTeX наразі найбільше виграє від використання мета-даних. Будь-який формат виводу можна змінити так, щоб він їх використовував.

Address (адреса)

Використовуйте це для вказання списку листування автора. Можна вказувати декілька рядків — додавайте два пробіли в кінці рядків, і у LaTeX буде додано символ нового рядка. Також використовується як зворотня адреса у заготовках листів та конвертів.

Author (автор)

Пояснення не потребує. Я через цей ключ передаю LaTeX інформацію про автора документа. Також використовується як адресант у шаблонах листіва та конвертів.

Affiliation (об’єднання)

Вказуйте тут організацію, з якою автор пов’язаний — наприклад, університет, компанію або організацію. Можете вказати адресу тут, а можете використати поля Address, email, web та phone. Тут можна використати декілька рядків — додавайте два пробіли в кінці рядка, щоб у LaTeX з’явився символ нового рядка.

Base Header Level (початковий рівень заголовків)

Використовується моїм скриптом XSLT для зміни стандартного рівня заголовків. Наприклад, у мемуарних документах заголовки першого рівня можуть позначати розділ, а не частину. Для цього просто встановіть Base Header Level у 2.

Base URL (основне посилання, вийшов з ужитку)

Не вживайте — WikiWords та WikiLinks більше не підтримуються.

Bibliography Title (заголовок літератури)

Змінює назву роздіду літератури (наприклад, "Література", чи "Посилання"). Зазвичай це "Bibliography".

Bibliography Style (стиль літератури)

Назва стилю BibTeX, що ви хочете використати.

BibTeX

Тут має вказуватися ім’я файлу .bib (файл BibTeX для збереження посилань). При використанні мого файлу xhtml2latex.xslt це перетворить зовнішні цитати на розмітку BibTeX (детальніше — див. [Література][])

Вам знадобиться встановлений і працюючий bibtex; файл .bib повинен знаходитися у поточній теці.

Chapterstyle (стиль розділів)

Значення для chapterstyle у мемуарних документах LaTeX.

Copyright (копірайт)

Тут можна вказати рядок копірайту.

CSS

При створенні цілих документів XHTML — CSS.

Date (дата)

Дата документу.

Email (електронна пошта)

Для електронної адреси автора.

Format (формат)

Щоб вказти, що потрібен повністю відформатований документ XHTML, вкажіть тут complete. З такими документами можуть працювати утиліти XSLT, наприклад, файли, що перетворюють XHTML на LaTeX.

Значення snippet означає, що тег <head> та іншу інформацію буде випущено. Це може використовуватися, наприклад, для отримання результату у XHTML для того, щоб вставити його у веб-журнал.

Зауваження: Деякі інструменти multimarkdown авроматично додають це поле (наприклад, TextMate з моїм пакунком, Scrivener). Подвійне використання поля Format у цих програмах не має створювати проблем — якщо це не так, дайте мені знати.

Keywords (ключові слова)

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

Language (мова)

Наразі поле Language визначає яку версію SmartyPants використовувати. Можливо потім воно буде використовуватися й у інших цілях.

Мова вказується англійським словом (наприклад, "german" а не "deutsch").

LaTeX XSLT

Визначає файл XSLT для перетворення документу XHTML на документ LaTeX. Після цього документ LaTeX можна перетворити на PDF за допомогою pdflatex. Раніше це поле називалося XSLT File.

Pagestyle (стиль сторінки)

Вказує pagestyle для мемуарних документів LaTeX.

Phone (телефон)

Можете тут вказати телефон(и) автора. Дозволяється використання декількох рядків — додавайте два пробіли в кінці, щоб отримати розрив у LaTeX.

Recipient (отримувач, адресат)

Використовується у шаблонах листів та конвертів.

Recipient Address (адреса отримувача)

Використовується у шаблонах листів та конвертів.

Revision (версія)

Можете вказати рядок, що представляє поточну версію документу. При використанні моєї мемуарної трансформації XSLT, буде показуватися на сторінці копірайту.

RTF XSLT

Використовувався для визначення файлу XSLT, що змінював вивід XHTML перед перетворенням його на RTF. Може стати в нагоді для подальшого підлаштування виводу multimarkdon конкретно для формату RTF. Я не збираюся робити таких файлів, але комусь іншому це може згодитися.

Я рекомендую вам використовувати інший метод перетворення XHTML на RTF. Для мене найкраще працюють Google Docs. Для користувачів систем, відмінних від Mac, це найвірніший шлях.

Subtitle (підзаголовок)

Вказується підзаголовок. Він опиняється у мета-тегах, але XSLT може його виокремити для інших цілей.

Title (заголовок)

Офіційний заголовок документу. Використовується у тезі <title> заголовку <head> документа HTML. Також використовується у інших форматах виводу.

Use WikiLinks (не використовується)

Значення true чи 1 дозволяє використання ВікіСлів та <span class="createlink"><a href="/cgi-bin/ikiwiki.cgi?page=%D0%92%D1%96%D0%BB%D1%8C%D0%BD%D0%B8%D1%85_%D0%BF%D0%BE%D1%81%D0%B8%D0%BB%D0%B0%D0%BD%D1%8C&amp;from=Dlou%2FMultimarkdown_Users_Guide&amp;do=create" rel="nofollow">?</a>Вільних посилань</span>. Також має бути визначеним поле Base URL. Див. [ВікіПосилання][ВікіПосилання (не використовуються)].

Web (мережа)

Посилання на сайт автора.

XHTML Header (заголовок XHTML)

Використовується для додавання довільного тексту до заголовку документу XHTML. Це може бути форматування CSS, код javascript або будь-що інше. Я не відповідаю за працездатність доданого тексту, multimarkdown просто додає його як він є.

Вміст цього поля вставляється без змін усередину розділу <head> документу XHTML. Якщо ви щось додаєте таким чином, можуть знадобитися зміни до стилів XSLT, щоб примусити їх при перетворенні у LaTeX ігнорувати додане. Повідомте мені, що ви додаєте, і я подумаю над оновленням стилів XSLT. Наразі стилі ігнорують секції <elyts>.

XHTML XSLT

Назва файлу XSLT для післяобробки XHTML. Може використовуватися для підлаштування отриманого XHTML до ваших потреб. Наприклад, xhtml-toc.xslt додає зміст на початку сторінки XHTML.

XMP

Це поле використовувалося для того, щоб вказати файл, який треба додати за допомогою xmpincl. Фактично, це надає можливість вказувати ліцензійну інформацію Creative Commons у мета-даних PDF. Також може використовуватися для інших цілей, але це виходить за рамки цього документу.

XSLT File (файл XSLT, не використовується)

Замість цього поля варто використовувати XHTML XSLT, RTF XSLT, та LaTeX XSLT.

Внутрішні посилання

Одним з покращень, які користуються попитом, є створення внутрішніх посилань з тією ж легкістю, що й зіовнішніх. Отож я додав можливість інтерпретувати [Якийсь текст][] як внутрішнє посилання, якщо існує заголовок з назвою "Якийсь текст".

Наприклад, [Мета-дані][] перенесе вас до [розділу, що описує мета-дані][].

Або ж ви можете вказувати власні мітки до заголовків, що допомагає у випадках, коли декілька заголовків мають однакову назву. Наприклад, оце:

### Огляд [ОглядMultiMarkdown] ##

дозволить вам звертатися до цього розділу за допомогою [ОглядMultiMarkdown] (а не до іншого розділу з назвою "Огляд"). Працює для заголовків atx та settext.

Якщо назви мітки й якогось заголовку збігатимуться, мітка матиме більшу вагу.

Таблицям і малюнкам також можна додавати мітки для внутрішніх посилань.

Малюнки

Звісно, малюнки прекрасно працюють у markdown (за виключенням атрибутів, як згадувалося раніше). Однак, для інших форматів документів (PDF, як приклад) малюнки можуть потребувати додаткової інформації.

З цієї причини мої файли XSLT використовують вказаний розмір з тегу <img> (наприклад, height та width). Якщо розмір присутіній — малюнок буде підігнано під нього. Якщо вказано лише один вимір, малюнок буде масштабуватися пропорційно. Якщо ж не вказано ані height ані width, малюнок буде підігнано під ширину тексту. Це робиться щоб малюнки з високою роздільною здатністю не вилізли за межі сторінки. Але з-за цього маленькі малюнки можуть збільшитися. Якщо ви не бажаєте, щоб ваші малюнки так збільшувалися, вкажіть розмір у принаймні одному вимірі.

Зауваження: у XHTML розмір у тезі <img> може мати лише одиниці px або %. LaTeX підтримує декілька інших одиниць. Отож, мій файл XSLT дозволяє використання інших одиниць, навіть якщо вони не працюють у XHTML. Вам доведеться вибрати одиниці, що відповідають вашій меті. На жаль, єдиний метод обійти це — впевнитися, що усі малюнки мають вказані розміри, а тоді прибрати з XSLT.* частину \resizebox.

Атрибути для міток та малюнків

У списку листування markdown вже давно просили зробити додавання атрибутів до посилань та малюнків. Я не підтримував цю ідею, оскільки більшість пропозицій порушувала легкість читання. Я вважаю себе "пурістом markdown" — визначення Джона припало мені до душі:

Markdown має бути настільки простим у читанні та на письмі, наскільки дозволяє доцільність.

При цьому простота читання має найбільшу вагу. Якщо опублікувати документ, написаний з використанням Markdown як є (простим текстом), він не повинен виглядати так, ніби він розмічений тегами чи інструкціями форматування. Синтаксис markdown увібрав у себе риси деяких інших типів перетворення тексту на HTML, але найбільший вплив мали правила форматування звичайних текстових електронних листів.

Оскільки жодна пропозиція не дотримувалася цих вимог, я був проти ідеї вцілому.

А потім Чон К. Гальвез запропонував геніально простий синтаксис, що не ліз в очі. Додавання атрибутів до визначення посилання, яке вже відокремлене від основного тексту, не заважає читанню.

Приклад:

Відформатований ![малюнок][] та [посилання][] з атрибутами.

[малюнок]:    http://path.to/image "Заголовок малюнку" width=40px height=400px
[посилання]:  http://path.to/link.html "Якесь посилання" class=external
              style="border: solid black 1px;"

Таким чином малюнок матиме атрибути висоти й ширини, а посилання — рамку. Хоча можна заперечити, що це "виглядає ніби розмічене тегами чи інструкціями форматування", навіть я не можу багато протиставити цій пропозиції. Посилання та заголовок у лапках вже виглядають як розмітка, а додаткові теги не нав’язливі аж настільки, при цьому вони відкривають багато можливостей. Можливо в майбутньому їх буде використано й для інших речей (цитати?).

Атрибути мають слідувати після інших даних посилання/малюнка і можуть містити переноси рядків, але починатися повинні з початку рядка. Мають формат атрибут=значення або атрибут="значення з декількох слів". Наразі multimarkdown не використовує ці атрибути. Також ви не можете продовжувати атрибут з лапками на наступний рядок.

ВікіПосилання (не використовуються)

Увага: ВікіПосилання створювали більше проблем, ніж вирішували, і тому я їх прибрав. Ви можете скористатися власне вікі для роботи з ними. Наприклад, мій додаток multimarkdown до Oddmuse підтримує ВікіПосилання у варіанті Oddmuse.

Примітки

Я додав примітки у multimarkdown відповідно до пропозиції Джона Грубера. Втім, зауважте, що офіційної підтримки ще нема, тому формат виводу може змінитися, але вхідний формат виглядає визначеним.

Щоб зробити примітку, введіть щось подібне до:

Якийсь текст з приміткою.[^приміткадляприкладу]

[^приміткадляприкладу]: Текст примітки.

[якесьпосилання]: http://somelink.com

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

Ось так виглядає кінцевий результат:

Якийсь текст з приміткою.^приміткадляприкладу

Таблиці

Я зробив синтаксис таблиць подібним до того, що використовує PHP Markdown Extra Мішеля Фортіна.

По суті, він дозволяє вам перетворити:

|            |          Групування        ||
 Заголовок 1 | Заголовок 2  |  Заголовок 3 |
| ---------- | :----------: | -----------: |
Вміст        |      *Довга клітинка*      ||
Вміст        | **Клітинка** |     Клітинка |

Новий розділ |    Більше    |        Даних |
І ще         |            І ще             |
[Прототип таблиці]

на [таблицю][Прототип таблиці].

| | Групування || Заголовок 1 | Заголовок 2 | Заголовок 3 | | ---------- | :----------: | -----------: | Вміст | Довга клітинка || Вміст | Клітинка | Клітинка |

Новий розділ | Більше | Даних | І ще | І ще || [Прототип таблиці][Прототип таблиці]

Вимоги:

• на кожному рядку має бути присутнім принаймні один символ |;
• між заголовком та вмістом повинні міститися лише символи |, -, :, . або пробіли;
• вміст клітинки має розташовуватися на одному рядку;
• колонки розділяються |;
• перший рядок і рядок-розділювач мають починатися з початку рядка.

Інші примітки:

• Розділювальні | на початку і в кінці рядка необов’язкові (якщо, звичайно, таблиця складається з більш ніж одної колонки).

• Ви можете використовувати двокрапки на розділювальному рядку, щоб вказати вирівнювання у колонках, як це показано вище. Якщо двокрапку не вказано, використовується типове для вашої системи вирівнювання (у більшості випадків - ліве). Якщо замість двокрапок ви використаєте крапку (.), буде застосоване вирівнювання по символу — у майбутньому це дозволятиме вирівнювати значення у колонці по десятковій комі. Наразі переглядачі це не підтримують, тому використання крапки не має сенсу. Проте це може використовуватися стилями XSLT для інших форматів виводу (наприклад, LaTeX).

• Щоб позначити, що комірка має займати декілька колонок, просто додайте зайві лінії (|) в кінці комірки, як показано у прикладі. У випадку, коли комірка є останнью у рядку, кінцева лінія (|) таблиці, як неважко здогадатися, є обов’язковою.

• Ви можете використовувати звичайну розмітку markdown у клітинках таблиці.

• Підпис таблиці необов’язковий, але якщо присутній, то має починатися з початку рядка, і безпосередньо передувати чи слідувати за таблицею, починатися символом [ і закінчуватися ]. Якщо вказано підписи і перед і після таблиці, буде використаний перший.

• Якщо таблиця має підпис, можна також додати мітку, на яку можна буде посилатися. Якщо мітку не вказано, підпис слугуватиме як мітка.

• Клітинки можуть бути порожніми.

• Ви можете створити у таблиці декілька тегів <tbody> розділивши рядки таблиці одним порожнім рядком. Таким чином ваш стиль CSS може додавати горизонтальні межі для відокремлення розділів таблиці.

• Якщо для першої колонки не вказано заголовка, її клітинки будуть вважатися заголовками і мати відповідне форматування.

Література

У цій версії multimarkdown я додав базові засоби посилань на літературні джерела. Буду дуже вдячний за відгуки та поради щодо покращення, проте прошу враховувати, що:

1. Підртимка бібліографії у multimarkdown є рудиментарною. Мета — надати початкову незалежну підтримку, що може змінюватися за допомогою потрібних вам інструментів у більш гнучкий формат (наприклад, BibTeX, CiteProc). Мої файли XSLT покзують, як добитися сумісності з BibTeX, але я не збираюся особисто займатися сумісністю з іншими утилітами. Вітається публікація ваших ідей та інструментів на вікі.

2. Тим, кому потрібен більш детальний набір бібліографічних функцій, можуть знадобитися для цього пристосовані утиліти. Це — початковий інструмент, що має підходити у більшості випадків. Бібліотекарів цитування він, мабуть, не задовільнить.

У multimarkdown цитати використовують синтаксис, подібний до міток:

Твердження, що повинне бути приписане його
джерелу[стор. 23][#Доу:2006].

А наступне — опис посилання для секції літератури.

[#Доу:2006]: Джон Доу. *Певна велика цікава книжка*.  Престиждрук, 2006.

На виході отримаємо такий XHTML:

<p>Твердження, що повинне бути приписане його джерелу
<span class="markdowncitation"> (<a href="#Доу:2006">1</a>, <span 
class="locator">стор. 23</span>)</span>.</p>

<p>А наступне — опис посилання для секції літератури.</p>

<div class="bibliography">
<hr />
<p>Bibliography</p>

<div id="Доу:2006"><p>[1] Джон Доу. <em>Певна велика цікава книжка</em>.
Престиждрук, 2006.</p></div>

</div>

Позицію (тобто стор. 23 у прикладі) вказувати необов’язково. Ви не обмежені ніякими правилами щодо того, як позиція має виглядати.

Також немає обмежень щодо назви мітки (тобто Доу:2006 у прикладі), але вона повинна починатися з решітки (#), подібно до того, як зноски використовують ^.

Сам опис посилання може містити форматування markdown. Також я раджу залишати порожній рядок після опису, щоб запобігти з’єднанню декількох описів. Зауважте, що немає можливості переформатувати ці посилання відповідно до інших стилів бібліографії; для цього доведеться використовувати призначені для цього програми, наприклад, BibTeX.

Якщо вам потрібно додати джерело, яке ви не цитуєте, ви можете написати наступне:

[Not cited][#мітка]

Слова Not cited не чутливі до регістру літер.

Внутрішні джерела

Якщо ви визначите ваші цитати (як у прикладах вище), multimarkdown автоматично додасть в кінець документу базовий розділ літератури. Посилання на цитати виглядатимуть так:

<span class="markdowncitation"> (<a href="#мітка">#
</a>, <span class="locator">стор. 23</span>)</span>

Якщо ви не вкажете позицію, ви отримаєте натомість:

<span class="markdowncitation"> (<a href="#мітка">#
</a>)</span>

Якщо ви клацнете на # (замість якого у тексті буде конкретний порядковий номер), ви потрапите на відповідне місце у бібліографії. На відміну від зносок, там не буде зворотнього посилання.

Зовнішні джерела

Якщо ви не визначите мітку джерела, multimarkdown застосує інший формат, що XSLT тоді може використати для перетворення на розмітку для зовнішніх утиліт, наприклад, BibTeX.

<span class="externalcitation"> (<a id="мітка">мітка</a>, <span 
class="locator">стор. 23</span>)</span>

Без вказання позиції вийде:

<span class="externalcitation"> (<a id="мітка">мітка</a>)</span>

Зрозуміло, що мітки у тексті multimarkdown повинні відповідати їх відповідникам для зовнішньої утиліти.

Посилання на декілька джерел

Коли вам потрібно послатися на декілька джерел в одному місці, просто впишіть їх під ряд:

[стор. 3][#Доу:1996][стор. 10][#Сміт:2005]

З цього вийде:

(1, стор. 3) (2, стор. 10)

Я розумію, що це нестандартний формат, але знов-таки, нагадую, що підтримка бібліографії у multimarkdown мінімальна. Якщо вам потрібен більший контролю чи дотримання належних правил стилю, значить вам потрібен потужніший бібліографічний інструмент.

Я написав скрипт на perl (cleancites.pl), що поєднує ці послідовні цитування у одне. Він зазвичай запускається стандартними скриптами multimarkdown.

Підтримка BibTeX

Якщо ви використовуєте BibTeX, ви можете застосувати його для обробки цитувань. Просто встановіть поля мета-даних Bibtex та Bibliographystyle, як описувалося у розділі про [Мета-дані][], та візьміть мої файли XSLT xhtml2latex як приклад.

При використанні BibTeX вам необов’язково визначати джерела усередниі документу multimarkdown.

Розширене цитування з використанням natbib

Досвідчені користувачі LaTeX скоріше за все знайомі з пакунком natbib, що надає додаткові команди для бібліографічних цитат — \citet та \citep.

Щоб задіяти ці команди:

1. Повинен бути встановленим пакунок natbib для LaTeX.
2. Ви маєте використовувати відповідний файл XSLT, що використовує natbib (наприклад, memoir-natbib.xslt, ви можете створити свій власний).

Зазвичай цитати робляться за допомогою команди \citep.

Щоб застосувати команду \citet, зробіть як показано нижче:

У їх плідній статті, [Сміт та Джонсs; стор. 42][#Сміт1990] переконливо
доводять, що.....

[#Сміт1990]: Сміт, Р, та Джонс, К. *Якась химерна стаття* і т.д....

Текст перед крапкою з комою вказує, що нам потрібна текстова цитата. У версії XHTML введений текст вставляється у речення. При перетворенні на LaTeX текст прибирається, і natbib його опрацьовує. Текст після крапки з комою — звичайний рядок позиції у джерелі (якщо вам не потрібна позиція, просто залиште пусте місце після крапки з комою).

Якщо ви не вкажете крапку з комою, буде як звичайно використовуватися команда \citep.

Математичні вирази

Вступ

Зауваження: Математичні вирази у multimarkdown реалізовані за допомогою MathML. Багато переглядачів підтримують MathML неповністю, отож ви можете стикнутися з проблемами (якщо чесно — мені всеодно, працює це у Internet Explorer, чи ні — візьміть нормальний переглядач. Firefox підтримує MathML вельми непогано, але всеодно не повністю.) Втім, MathML працює у LaTeX, тож у вас не буде проблем при створенні PDF.

Для правильного відображення у Firefox файлу, що містить MathML, він повинен мати розширення «.xhtml». Я не знаю, чому так, це смішно — щоб у 2007 році розширення файлу мало таке значення. Але наразі такий стан речей.

Для перетворення текстового представлення на MathML multimarkdown використовує ASCIIMathML. MathML може використовуватися у правильних документах XHTML для відображення правильно складених математичних формул.

Раніше перетворення робилося за допомогою ASCIIMathPHP — PHP скрипта, що запускався окремо від multimarkdown. З версії 2.0b.b4 я використовую модуль perl Text::ASCIIMathML усередині самого скрипта multimarkdown

Математичні вирази multimarkdown

Використовуйте << та >> для позначення математичного виразу у документі. Ви можете таким чином додавати формули всередині рядка або незалежні вирази, кожен у своєму параграфі. Тоді їх також можна правильно перетворити на математичні оточення^mathenv LaTeX.

Також ви можете вставити тег [мітка] у кінці виразу, щоб посилатися на нього у документі. Наприклад:

<< e^(i pi) + 1 = 0 [Тотожність Ейлера] >>

<< x_(1,2) = (-b+-sqrt(b^2-4ac))/(2a) [рішення квадратного рівняння] >>

Формули також можуть бути усередині речення, ось приклад:
<< x^2 + y^2 = 1 >>. Також ви можете зробити посилання на
[Тотожність Ейлера].

Буде перетворене на^matheg:

<< e^{i pi} + 1 = 0 [Тотожність Ейлера] >>

<< x_(1,2) = (-b+-sqrt(b²-4ac))/(2a) [рішення квадратного рівняння] >>

Формули також можуть бути усередині речення, ось приклад: << x² + y² = 1 >>. Також ви можете зробити посилання на [Тотожність Ейлера].

Верхній індекс

За допомогою вищенаведених математичних виразів ви можете також додавати верхні індекси та подібне. Наприклад:

<<2^pi>>

стане

<< 2^pi >>.

Проте, звісно, таке використання всеодно має ті ж обмеження, що й MathML вцілому.

Проблеми MathML

При використанні MathML стикаєшся з деякими труднощами. По-перше, багато переглядачів неповністю підтримують MathML, іноді доводиться добряче пошукати, перш ніж вдається знайти щось, що правильно його покаже. Для прикладу, Firefox потрібне розширення .xhtml, щоб він вважав файл XHTML а не HTML. Це може бути не ідеальним рішенням, але воно дозволяє вам представляти математичні символи та формули простим текстом усередині документа, що й було моєю метою. Дехто може надати перевагу іншим рішенням, що використовують запис формул у LaTeX, але мені не хотілося вивчати математичний арсенал LaTeX.

Проте, з іншої сторони, це рішення дає прекрасний результат у поєднанні з моїми скриптами XSLT для створення LaTeX та PDF. Я відкритий до пропозицій у цій області, і підозрюю, що корисність цього рішення поступово зростатиме із покращенням підтримки MathML переглядачами.

Я написав статтю про підтримку MathML переглядачами, її можна знайти на моєму сайті.

Списки визначень

Для списків визначень у multimarkdown використовуються ті ж правила, що й у PHP Markdown Extra. Конкретніше:

Яблуко
:    Сім’янний фрукт рослин рослин роду Яблунь сім’ї Розоквітних.
:    Американська комп’ютерна компанія.

Апельсин
:    Фрукт вічнозеленого дерева роду Цитринових.

стане:

Яблуко : Сім’янний фрукт рослин рослин роду Яблунь сім’ї Розоквітних. : Американська комп’ютерна компанія.

Апельсин : Фрукт вічнозеленого дерева роду Цитринових.

Ви можете вказати декілька термінів для однго визначення, якщо кожен з термінів знаходитиметься на окремому рядку. Кожне визначення починається з двокрапки, і їх також може бути декілька на один термін. Ви також можете вставити один порожній рядок між термінами та визначеннями, але це не обов’язково.

Визначення можуть складатися з декількох блоків — списків, цитат, інших списків визначень тощо.

На відміну від PHP Markdown Extra, усі визначення огортаються у тег <p>. По-перше — мені не вдалося примусити markdown не створювати параграфи. По-друге, я не знайшов, де б це мало значення — відмінність, як на мене, чисто естетична, і, фактично, я надаю перевагу їх присутності. Повідомте мене, якщо це створює проблеми.

Більше можна дізнатися зі сторінки PHP Markdown Extra.

Додатки

Якщо ви хочете позначити завершальну підгрупу розділів як додатки, ви можете додати заголовок першого чи другого рівня (як більше пасує до документа) з назвою Appendices. Подальші розділи будуть вважатися додатками при перетворенні на LaTeX за допомогою мемуарного класу. Оскільки XHTML не має поняття додатків, там цей заголовок не має такого значення, але, принаймні, повідомить читача.

Глосарій

У multimarkdown ви можете використовувати примітки як визначення для глосарію. Це не має значення для документів XHTML, але файл XSLT, що перетворює документ на LaTeX створює з цих приміток розділ глосарію.

Примітки для глосарію оформлюються подібно до цього:

[^приміткаглосарію]: glossary: термін (необов’язковий скорочений ключ)
    Саме визначення починається з нового рядка, і оформлюється точно так же
як і інші визначення приміток.

Термін — це елемент глосарію. Скорочений ключ є необов’язковим і використовується, щоб вказати, що термін повинен з’явитися деінде у глосарії (що сортується у алфавітному порядку).

Для створення глосарію у PDF доведеться зробити ще одну річ:

1. Повинен бути встановленим файл basic.get, що йде з мемуарним класом.

2. Ви повинні запустити спеціальну команду makeindex, щоб створити файл .glo:
   makeindex -s `kpsewhich basic.gst` -o "filename.gls" "filename.glo"

3. Після цього ви, як звичайно, запускаєте кілька разів команди pdflatex.

Або ж ви можете використати нижченаведений код для створення файлу рушія TeXShop (його потрібно покласти у ~/Library/TeXShop/Engines). Можете його назвати MemoirGlossary.engine. І тоді, при створенні файлу, що потребує глосарію, ви один раз верстаєте файл за допомогою цього рушія та продовжуєте обробку звичайним рушієм LaTeX. Якщо ви використовуєте TeXShop, то цей метод для вас.

Увага: Примусити глосарії працювати у LaTeX є нетривіальною задачею, вам може знадобитися поекспериментувати, щоб отримати потрібний результат.

#!/bin/    

set path = ($path /usr/local/teTeX/bin/powerpc-apple-darwin-current 
    /usr/local/bin) # це, насправді, продовження попереднього рядка

set basefile = `basename "$1" .tex`

makeindex -s `kpsewhich basic.gst` -o "${basefile}.gls" "${basefile}.glo"

Поезія

Зазвичай, коли параграф тексту починається з відступу, multimarkdown вважає його уривком коду. У ньому ви маєте повний контроль пробілів та переносів, але це також робить шрифт моноширинним, як у XHTML так і у LaTeX. Зазвичай це використовується для додавання джерельного коду до документів.

Проте деякі автори пишуть не про код, але хотіли б мати контроль над переносами рядків (наприклад, для віршів).

Для цього multimarkdown має декілька альтернативних файлів XSLT, що позначені словом poetry у назві. Ці файли обробляють уривки коду дещо інакше, більш подібно до тексту. Спробуйте ними скористатися.

Наразі отримати обидва формати в одному документі можливо тільки ручним форматуванням. Проте це може змінитися в майбутньому, якщо Джон Грубер прийме деякі рішення щодо стандартних правил markdown.

Різне

Окрім вказаного вище, multimarkdown робить деякі речі трохи інакше:

• елементи © перетворюються на ©, щоб їх прийняв парсер XSLT

• * та _ не вважаються позначенням <strong> та <em>, якщо вони знаходяться усередині слова^emmiddle. Вони створювали забагато проблем для посилань.

Multimarkdown може передавати кольори відрізків тексту з XHTML до LaTeX за допомогою пакунку xcolor. Наприклад:

<span style="color:#888888">мережа</span>

стане:

{\color[HTML]{888888} мережа}

Наразі для кольорів не існує правил форматування, тож вам доведеться вручну вставляти теги <span>. Це використовується, наприклад, для підтримки анотацій Scrivener.

Multimarkdown та LaTeX

LaTeX є професійною системою для верстання документів, що перетворює текстову розмітку на високоякісні файли PDF, що можуть містити зміст, покажчик, глосарій тощо. Це доволі складна програма, але вона й може зробити більшість роботи за вас. Однією з моїх цілей при створенні multimarkdown було подальше спрощення процесу створення документу LaTeX і зведення до мінімуму потреби вивчення синтаксису LaTeX. Фактично, якщо він правильно встановлений, ви можете створювати доволі складні документи навіть не маючи уявлення про те, як LaTeX працює.

Проте multimarkdown не є препроцесором файлів LaTeX, отож завжди знайдуться команди LaTeX, що недоступні з multimarkdown. Якщо ви — експерт у LaTeX, ви можете пройтися по отриманим файлам LaTeX та підправити вручну тут і там. Але я підозрюю, що для «середньостатистичних» користувача та документа того, що дає multimarkdown повинно бути вдосталь.

Параметри, яким варто приділити особливу увагу:

• Ви повинні вказати файл XSLT, що перетворить створений XHTML на LaTeX; це робиться за допомогою поля мета-даних LaTeX XSLT. Якщо ви його не вкажете, типове значення — memoir.xslt. Більшість моїх файлів XSLT побудовані навколо пакунку memoir — я його добре знаю, він дуже гнучкий і дає високоякісний результат. При цьому вітається створення ваших власних файлів XSLT для зручних вам пакунків. Величезною перевагою перетворення за допомогою XSLT є те, що його можна повністю змінити за потреби.

• Залежно від типу документу вам може знадобитися вказати поле Base Header Level. Наприклад, для документів, де розділи найвищого рівня є розділами а не частинами, ви можете вказати тут 2. Це складніше описати, ніж зробити, але загалом таким чином усі рівні у структурі вашого документу зсуваються на вказану кількість рівнів.

• Скоріше за все варто буде вказати якмога більше основних мета-даних (тобто Title, Author, Date, Keywords тощо), оскільки більшість з них використовується у PDF.

Також multimarkdown підтримує BibTeX, глосарії, посилання html, внутрішні посилання між розділами документу, математичні вирази тощо. Більшість «основних» можливостей LaTeX доступні у стандартному форматуванні multimarkdown. Якщо вам чогось не вистачає — запитайте, воно може існувати, або я можу спробувати його додати.

Процес створення PDF через LaTeX подібний до звичайного використання multimarkdown, за виключенням додаткового кроку:

1. Створіть вхідний текстовий файл.

2. Отримайте з ного XHTML зручним вам методом і тоді перетворіть XHTML на LaTeX (більшість моїх утиліт зроблять це у один крок).

3. Отримайте PDF з LaTeX зручним вам методом (наприклад, за допомогою мого додатку, TeXShop, latexmk, вручну).

З-за складності джерельної розмітки LaTeX, буває складно виявити помилки у автоматично згенерованих документах. Якщо щось не працює, я рекомендую спочатку перевірити, чи у згенерованому XHTML все правильно. Тоді перетворити його на LaTeX, слідкуючи за повідомленнями — зазвичай вони дають підказку де шукати проблему. Пам’ятайте, що те, що XHTML проходить перевірку, не означає, що отриманий з нього LaTeX буде правильним.

Розширення та пристосування

На мою думку, для переважної кількості користувачів, multimarkdown прекрасно працює «з коробки» (звісно, я неупереджений і все таке...) Але користувачі з більшими вимогами рано чи пізно почнуть думати над можливостями, яких їм не вистачає. Деякі з цих можливостей — специфічні для конкретних документів та стилів, але деякі — більш загальні і стануть у нагоді будь-кому.

Де шукати інформацію щодо розширення X?

Я рекомендую такий підхід:

1. Перш за все, перевірте документацію на сайті (там є пошук), бо люди все більше питають про речі, які вже є.

2. Також пошукаєте у списку листування multimarkdown, може хтось вже питав щодо вашої проблеми, а може навіт і знайшов рішення.

3. Подумайте, можете ви самі спробувати зробити розширення, чи вам потрібна допомого у цьому. В будь-якому разі, результатами можна поділитися у мене на сайті, щоб допомогти іншим.

Як пристосовувати multimarkdown

По-перше, потрібно визначити, на якому етапі роботи multimarkdown потрібні зміни:

1. Чи потрібно змінювати скипт multimarkdown, щоб додати нові правила чи змінити результат його роботи? З стабілізацією multimarkdown потреба у таких змінах повинна спадати. Також, майте на увазі, що я вагаюся, перш ніж додавати такі зміни, бо вони збільшують складність розмітки. Вам доведеться мене переконати, що це єдиний шлях вирішити проблему.

2. Чи можна реалізувати це розширення зміною файлів XSLT? XSLT — дуже потужний інструмент, з його допомогою вивід у XHTML та LaTeX можна сильно змінити. (Багатьом користувачам скоріше за все стане у нагоді типовий файл XSLT для перетворення XHTML на RTF — я не зміг знайти щось, що б працювало, і мені не потрібні документи RTF. Для його розробки потрібно забагато роботи, а результату для мене ніякого, проте як впевнений, що комусь така штука потрібна.) Подивіться у теці XSLT, можливо ви знайдете стиль, який можна змінити під ваші потреби. Синтаксис XSLT не ткий вже й сакладний, але до нього потрібно звикнути. Для прикладу, xhtml-toc.xslt розбирає теги заголовків XHTML та автоматично створює зміст на початку документа. Файл xhtml-poetry-support.xslt знаходить блоки коду, що починаються з [poetry] та змінює їх на вірші (фактично, прибирає моноширинний шрифт).

3. Чи можна реалізувати це розширення як окремий скрипт післяобробки? Наприклад, для документів LaTeX, я використовую скрипт, що називається cleancites.pl, що шукає послідовні цитування та скорочує їх запис. Такі скрипти легко робляться та додаються до послідовності обробки документу.

У підсумку, користувачі можуть додати багато розширень та підлаштувань. Також прошу розглянути можливість поділитися з іншими вашими напрацюваннями — я буду радий розмістити файли чи посилання у себе на сайті.

Де що шукати у пакунку multimarkdown?

Знав-таки, місця пошукати натхенння:

• MultiMarkdown/bin - високорівневі скрипти, що поєднують інші утиліти у різні варіанти використання. Ви можете створювати свої власні скрипти, що додають додаткові кроки.

• MultiMarkdown/Utilities - деякі допоміжні скрипти плюс скрипт післяобробки cleancites.pl ви можете додавати сюди свої скрипти і використовувати їх у своїх варіантах використання.

• MultiMarkdown/XSLT - файли XSLT для зміни файлів XHTML чи створення LaTeX. Містить багато прикладів різних стилів виводу та зміни шляху, речі працюють.

• http://fletcherpenney.net/XSLT_Files - місце, куди я викладатиму різні файли, надіслані користувачами, що можуть представляти інтерес. Було б добре, якби ви теж поділилися своїми напрацюваннями тут.

Складові програми

Multimarkdown насправді складається з багатьох програм, що запускаються у визначеному порядку скриптами оболонки. Я написав утиліти, що поєднують їх а також модифікацію оригінального markdown Джона Грубера — multimarkdown, але я не можу присвоїти собі авторство інших.

MultiMarkdown [MMD]

• автор Флетчер Т. Пенні
• http://fletcherpenney.net/MultiMarkdown

Моє доповнення до markdown Джона Грубера. На ньому базується цей пакунок. Щоб дізнатися більше про нього, зазирніть на сайт.

SmartyPants

• автор Джон Грубер
• http://daringfireball.net/projects/smartypants/

Інша програма Джона Грубера, що додає «витончені» типографічні елементи у документи HTML, зокрема, правильні лапки, риски та еліпсис. Причому існує декілька версій SmartyPants для різних локалізацій (конкретно — данська, французька, німецька та шведська). Ці локалізації зроблені Йоахімом Герце.

Text::ASCIIMathML

• автор Марк Нодін
• http://search.cpan.org/~nodine/

Модуль perl, що перетворює розмітку ASCIIMathML на розмітку MathML, що можна вставляти у документи XHTML.

ASCIIMathPHP (не використовується)

• автор Кі-Лін Стівен Чан
• http://www.jcphysics.com/ASCIIMath/

Цей пакунок зокрема містить варіант ASCIIMathPHP, який використовувався multimarkdown. З його допомогою можна описувати математичні формули простим текстом.

Зараз його замінив Text::ASCIIMathML.

XSLTMathML

• автор Василь Ярошевич
• http://www.raleigh.ru/MathML/mmltex/index.php?lang=en

Цей пакунок містить варіацію XSLTMathML, що використовується у multimarkdown. Перетворює XHTML з розміткою MathML на LaTeX з кодом оточення. Дуже зручний у створенні добре зверстаних документів, набитих математикою.

Програми, що підтримують multimarkdown

Є декілька програм та утиліт, що використовують multimarkdown, і можуть ще більше полегшити вам життя.

Якщо вам зустрінеться щось, не наведене нижче, будь ласка повідомте мене про це.

Movable Type

Multimarkdown можна використовувати із Movable Type. Встановлення:

1. Покладіть MultiMarkdown.pl до теки mt/plugins/Markdown;
2. Скопіюйте ASCIIMathML.pm туди ж;
3. Перевірте, чи SmartyPants.pl теж там присутній.

Тепер multimarkdown має працювати у Movable Type. Проте, чомусь іноді він викидає коники. Мені не вдалося визначити чому, але у мене він так працює на локальній машині і на сервері мого хостера. Також працював у деяких інших людей.

MultiMarkdown Drag and Drop

Зі зростанням функціональності multimarkdown (і його складності), я дійшов висновку, що більшості користувачів потрібне щось простіше у використанні, ніж команди оболонки (доволі складні на той час).

Першим вирішенням цієї проблеми стали декілька програм для перетягування на них, створених за допомогою Platypus. Ви просто перетягуєте текстовий файл multimarkdown на іконку програми, і вона видає файл .xhtml, .pdf, .rtf чи .tex, в залежності від програми.

Їх досі можна дістати (оновлені для роботи з "стандартним" розташуванням multimarkdown) тут:

• http://files.fletcherpenney.net/MultiMarkdownDragAndDrop.zip

Scrivener

Scrivener це:

... система керування проектами для письменників, що подібна до вашого затишного письменницького укриття у глибині саду, де ви маєте коркові дошки для заміток, прес-папьє, фотографії, вирізки, прикріплені до заміток, записнички та стоси друкованих сторінок — разом з секретарем, що упорядковує це все у охайні стопки та використовує навички швидкочитання для того, щоб знайти потрібне в ту ж хвилину, як воно вам знадобиться.

Станом на третю бету, scrivener може експортувати у текстові файли multimarkdown або запускати інструменти перетворення у XHTML, RTF чи LaTeX. Також він підтримує мета-дані multimarkdown.

Scrivener (у тому, що стосуються multimarkdown), зокрема має можливість впорядковувати і перевпорядковувати ваш документ у режимі планування, коркової дошки та інших. Також він може (з обмеженнями) перетворювати грубий та курсивний шрифт RTF у форматування multimarkdown, що може стати в нагоді при перетворенні форматів.

Scrivener найперше фокусується на творчому письмі, але у поєднанні з multimarkdown він може бути дуже зручним і для академічного чи технічного письма, де є важливим вивід у LaTeX.

Кейт Блант добряче постарався над scrivener, і я був щасливий допомогти з підтримкою multimarkdown. Я сподіваюся й далі використовувати та покращувати цю програму.

Наразі scrivener знаходиться у стані публічного бета-тестування, та має з’явитися у продажу ближче до кінця 2006 — початку 2007 року. Проте ця бета вже придатна до повноцінного використання як є і дозволяє вам це робити до січня 2007 року.

За додатковою інформацією можете звертатися до створеного мною «Підручника користувача Scrivener із Multimarkdown»:

• http://fletcherpenney.net/Using_MultiMarkdown_with_Scrivener

OmniOutliner

Я написав втулок для OmniOutliner, що дазволяє вам створювати документ у OmniOutilner, і тоді експортувати його у текстовий файл multimarkdown (або теку з текстовим файлом та малюнками), що тоді можна згодувати markdown чи multimarkdown.

http://fletcherpenney.net/multimarkdown/multimarkdown_and_omnioutliner/

TextMate

TextMate — потужний редактор тексту, що:

переносить підхід Apple до операційних систем у світ текстових редакторів. Поєднуючи основу UNIX та графічний інтерфейс, TextMate бере найкраще з двох світів на благо як експертів-скриптувальників так і новачків...

Створений гіком UNIX, якого переманили на Mac простотою використання та елегантністю, TextMate описують як вершину розвитку Emacs та OS X, що вилилося у несчисленні прохання портувати його на Windows та Linux, але TextMate ексклюзивний для Mac, і нам це подобається

TextMate знаходиться десь посередині між редактором для програмістів та інструментом письменника. Якщо ви ціните можливість підігнати робоче середовище, а також наявність чудних інструментів, що зроблять форматування за вас — можливо TextMate — для вас.

Алан Одгаард створив найперший пакунок, що додавав підтримку markdown у TextMate. Там було й трохи базового multimarkdown. Проте, якщо чесно, навіть мені було важко примусити його працювати. А якщо у мене виникли проблеми, лише уявіть, скільки проблем виникало у інших.

Отож, я створив мій власний пакунок. Там є багато корисного, автоматичне форматування мета-даних, списків, таблиць, заголовків тощо. Він вміє почистити текст так, щоб він виглядав настільки красиво у текстовому форматі, наскільки можливо, а після цього автоматично з нього створити XHTML, RTF, Word чи LaTeX/PDF.

Згодом я переписав оригінальний пакунок як його відгалуження на гітхабі. Це має допомогти у перенесенні змін, і, згодом, злитті проектів у один пакунок.

• http://fletcher.github.com/markdown.tmbundle/

Scrivener та TextMate разом

Разом їх використовувати можна за допомогою властивості TextMate "Редагування у TextMate". В основі своїй вона дозволяє вам редагувати у TextMate буфер будь-якого редактора, заснованого на Cocoa. Отож ви можете редагувати текст документу Scrivener у TextMate, що надає вам автоматичне форматування, зберігаючи організаційну будову Scrivener.

Ця властивість має свої обмеження (наприклад, вона порушує стек скасувань у Scrivener) і рекомендована лише для досвідчених користувачів. Я не несу відповідальності за її роботу, оскільки Scrivener та TextMate писав не я, але вона може стати в нагоді...

Детальніше можна дізнатися з опису текстових полів Cocoa:

• http://macromates.com/textmate/manual/using_textmate_from_terminal

«Типове» розміщення multimarkdown

Під час бета-тестування підтримки multimarkdown у Scrivener була зроблена пропозиція зробити місцезнаходження multimarkdown постійним, що полегшить його оновлення та використання із іншими програмами.

Для користувачів Mac OS X він може встановлюватися в одне з двох місць, де його знайде будь-яка програма, яка знає про його стандартизацію:

• ~/Library/Application Support/MultiMarkdown
• /Library/Application Support/MultiMarkdown

Перше місце доступне лише для користувача, друге — для усіх програм на комп’ютері.

Коли Scrivener чи інша програма, що знає про стандартні місця, запускається, він перевіряє наявність multimarkdown у цих місцях. Якщо його там не знайдено (наприклад, при першому запуску програми), деякі програми тоді встановлюють туди свою версію multimarkdown; інші просто використовують вбудовану приватну версію.

Чим добрий такий підхід — якщо я зроблю оновлення multimarkdown, ви можете просто замінити оновлені файли у теці Application Support, без потреби оновлення інших програм.

Будь ласка, якщо ви знаєте як покращити цю систему чи збираєтесь додати підтримку multimarkdown у вашу програму, повідомте мене.

Звісно, така система працює лише у Mac OS X. Якщо ви зацікавлені у тому, щоб розробити подібний стандарт для інших систем — зв’яжіться зі мною.

Створіть свою власну програму

Між скриптами оболонки, applescript, Automator, та іншими інструментами часто є достатньо місця, щоб втулити multimarkdown у робочий процес. Якщо ви знаєте щось, що варто додати до цього списку — напишіть мені!

Технічні проблеми

Multimarkdown насправді є доволі складною системою програм, серед яких є декілька скриптів на perl, програма на PHP, та набір файлів XSLT. Я намагаюся зробити так, щоб система виглядала як суцільна програма, але насправді це декілька інструментів, написаних різними людьми.

У цьому розділі висвітлюються деякі наслідки цього, і що ці наслідки можуть означати для користувачів, програмістів тощо.

Проблеми з просторами імен XML

У версії 2.0.a3 було повністю змінено методи роботи з просторами імен XML. Для цього довелося внести зміни до усіх файлів XSLT, щоб "html" вважалося аліасом простору імен "http://www.w3.org/1999/xhtml".

Наразі, схоже що все працює, в тому числі й MathML.

Якщо у вас були власні файли XSLT, вам потрібно також їх трохи змінити, а саме:

Ваш опис таблиці стилів має виглядати подібно до цього:

<xsl:stylesheet
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:html="http://www.w3.org/1999/xhtml"
    version="1.0">

Також додайте "html:" до усіх згадок елементів XHTML, наприклад:

<xsl:template match="/">
    <xsl:apply-templates select="html/head"/>
    <xsl:apply-templates select="html/body"/>
    <xsl:call-template name="latex-footer"/>
</xsl:template>

потрібно змінити на:

<xsl:template match="/">
    <xsl:apply-templates select="html:html/html:head"/>
    <xsl:apply-templates select="html:html/html:body"/>
    <xsl:call-template name="latex-footer"/>
</xsl:template>

Я залишив параметри -novalid та -nonet, щоб запобігти зайвим повідомленням про помилку, коли ви не підключені до мережі, але якщо ви хочете, ви можете їх прибрати.

Підказки щодо XeLaTeX

Якщо ви використовуєте XeLaTeX для обробки вашого документу (корисно при використанні шрифтів Mac OS X), ви маєте описувати шрифти подібно до цього:

\font\addressbold="Garamond Bold:mapping=tex-text" at 8pt

Додавши ":mapping=tex-text" ви знов отримуєте правильні лапки, короткі та довгі тире тощо. Я впевнений, що користувачі XeLaTeX знають про це, але мені самому довелося трохи поекспериментувати, доки дійшов цього...

Подяки

Дякую наведеним нижче людям та групам за їхній вклад у покращення markdown та multimarkdown:

• John Gruber
• Michel Fortin
• Jonathan Weber
• Mark Eli Kalderon
• Choan C. Gálvez
• Dr. Drang
• Robert McGonegal
• David Green
• Trey Pickard
• Saleem
• Melinda Norris
• Sean Wallace
• Allan Odgaard
• Stefan Brantschen
• Keith Blount
• Amber Vaesca
• Gerd Knops
• John Purnell
• Jonathan Coulombe
• Jason Bandlow
• Joakim Hertze
• Kee-Lin Steven Chan
• Vasil Yaroshevich
• Matt Neuburg
• James Howison
• Edward Nixon
• etherean
• Özgür Gökmen
• Chad Schmidt
• Greg (gr)
• Ben Jennings
• Silvan Kaiser
• Tomas Doran
• Rob Walton
• Dan Rolander
• Duoyi wu
• Dan Dascalescu
• Ingolf Schäfer
• Chris Bunch
• Oblomov
• Alex Melhuish
• Stephan Mueller
• Josh Brown
• Rob Person
• Matthew D. Rankin

та багатьом іншим, кого я забув...

Відомі проблеми

• При вживанні <<...>>, може бути закодована як < лише перша <, якщо у виразі немає початкового відступу (тобто <<вираз>> а не << вираз >>). Я підозрюю, що мені доведеться вручну шукати та перетворювати кожне <<. Мені здається, технічно це проблема markdown, а не multimarkdown, просто вона раніше не зустрічалася.

• Я спробував прибрати залежність від пакунка varwidth. Але це порушує форматування виносок у таблицях а також експорт таблиць у RTF. І я не впевнений, що робити далі — varwidth несумісний з xcolor та не є стандартним пакунком. Буду вдячний за поради.

• Посилання на малюнки за міткою перестали працювати.

• Маю проблеми примусити глосарії працювати у не-мемуарних класах. Колись я розберуся з цим, але якщо хтось інший може вказати мою помилку, буду вдячний.

• Наразі RTF підтримується лише у Mac OS X. Перетворення XHTML на RTF робиться за допомогою інструменту textutil Apple. Написати файл XSTL для цього можливо, але мені це майже нецікаво, бо я RTF майже не використовую. Якщо хтось захоче це зробити — я з радістю допоможу. Додатковою перевагою буде те, що XSLT може зробити краще перетвоерння приміток та внутрішніх посилань. Напишіть мені, якщо ви хочете це зробити. Ну а поки, я рекомендую використовувати Google Docs для імпорту XHTML і потім експорту в RTF. Наразі результат значно кращий.

• Файл-приклад створює дві копії виноски у таблиці MultiMarkdown vs. Crayons, незважаючи на те, що я роблю лише одну. Не впевнений, звідки береться примітка a... Вітається допомога у відкопуванні коренів цієї проблеми.

Що треба зробити

• Додати правила, що дозволятимуть прибирати коментарії перед розбором синтаксису.

• Написати підпрограму (окрему від multimarkdown) для звантажування малюнків за посиланнями, збереження їх до тимчасової теки і тоді перетворення для додавання у PDF.

• Придумати щось для керування вирівнюванням у багатостовпчикових клітинках. Наразі використовується вирівнювання першого стовпчика (якщо markdown прийме керування вирівнюванням пробілами — його можна буде використати й тут).

• Вирішити, чи правила оформлення багатостовпчикових клітинок прийнятні чи ні.

• Подумати над правлами для індексів (обговорювалося раніше) — можливо змінити на розмтку MathML? Чи просто використовувати математичну розмітку замість цього, як описувалося у розділі [Верхній індекс][]

• Деякі правила застосовуються до заголовків, хоча не повинні, наприкладц <img>.

• Можливо застосувати правила оформлення списку визначень до глосарних приміток (або можливо взагалі не використовувати примітки для цього)?

Історія змін^untrans

Release early, release often!

Linus Torvalds

• 2.0.b6 - Fix support for base header level with Setext-style headers (thanks to Rob Walton); improve Windows support;

• 2.0.b5 - spaces at end of xslt filenames won't cause failure; use \url{} for "non-referenced" url's in LaTeX to allow linebreaks (though they still don't always break correctly --- this is a problem with hyperref not MMD); don't convert ^ to exponents in the clean-text-allow-latex.xslt file so that math code works properly; the S5 XSLT file at least partially works again now; update the TextMate bundle to work with Leopard; updated the envelope and letterhead files; include 6x9book-real-poetry XSLT that uses memoir's poetry features fairly well; rework the clean-text files to make them easier to update in the future and more modular; XHTML comments are now passed through as raw LaTeX; unescape encoding within comments;

• 2.0.b4 - empty labels for headers now produce valid XHTML (e.g. no id=""); fix bug in clean-text.xslt that caused a problem with closing double quotes; the .xslt extension is no longer required in metadata; added customizable letterhead XSLT; fix bug in table support that choked on extra spaces at end of lines; Major Change: switched to Text::ASCIIMathML for math support, meaning that everything is once again perl based (this enables math features on web sites using MultiMarkdown, for example); fix bug that occurred when 'Abstract' was not the first chapter;

• 2.0.b3 - move the clean-text routine from xhtml2latex.xslt into it's own file (to allow easier modification by users); create alternate version that does not protect certain characters in order to allow raw LaTeX code to be passed through; added latex-snippet.xslt stylesheet for inclusion in outside LaTeX template systems; added xhtml-poetry-support.xslt and xhtml-toc.xslt to demonstrate how to extend MMD functionality for XHTML output with new system; fix bug in SmartyPants that processed typography within <elyts> sections (thanks AmberV); fix handling of links by reference in headers and handling of attributes when links are referenced multiple times (thanks to Edward Nixon); fix bug in epigraphs (thanks etherean); improve id generation for footnotes - e.g. match behavior of PHP Markdown Extra (thanks to Özgür Gökmen); fix bug in id generation for ToC for XHTML documents; fix problem with \ldots command (thanks to etherean and James Howison); fix issue with   and tilde character; fix bug where footnote special characters were not unescaped (thanks to Chad Schmidt); clean up documentation a bit;

• 2.0.b2 - fix processing of footnotes so that ending in a blockquote doesn't break validity; fix bug in letter.xslt; overhaul XSLT system to allow for different XSLT files for different output formats (e.g. HTML, RTF, LaTeX);

• 2.0.b1 - fix bug in _StripLinkDefinitions that prevented detection of single character labels; change \textwidth to \linewidth in LaTeX export XSLT files (let me know if this causes problems); add Windoze compatibility to the perl scripts (thanks to Jason Bandlow for pointing out this problem, as well as for suggesting a fix);fix issues with glossary support and document the process; complete overhaul of the way namespaces are handled (stripnamespace.pl is no longer needed, XSLT files are rewritten, -nonet and -novalid should be optional for xsltproc); update the Drag and Drop applications to use the "Common" MMD Installation; update to Markdown 1.0.2b8 codebase; add support for natbib and \citep and \citet;

• 2.0.a2 - fix some minor problems with XSLTMathML; allow math to be enclosed in parentheses; change matching for bottomrule in tables; improve handling of tables with no header row (only a header column);

• 2.0.a1 - strip spaces from metadata keys for XHTML validity; make XHTML footnote output more compatible with Gruber's website and PHP Markdown Extra; update XSLT to address these changes (Note: this breaks compatibility with prior versions); add support for definition lists; fix bug when escaping WikiWords in code; add XHTML Header metadata, and update XSLT to ignore <elyts> tags; add support for the XSLT File metadata tag, which allows a single command to parse any MultiMarkdown file; add additional XSLT files; add the multimarkdown2XHTML.pl and related commands; article XSLT now uses the article option in memoir, rather than the article class; delete the report class (use memoir instead); fix a lot of "minor" bugs; add the "6x9book.xslt" option; allow custom cross-reference labels to headers; give preference to defined links over automatic cross-references; add "poetry" versions of several XSLT files (treat code blocks as formatted text, rather than code --- useful for formatting poetry)

• 2.0.a - New version numbering scheme; update to Markdown.pl 1.0.2b7 code; add support for [link reference] shortcut syntax (i.e. no trailing []) for MultiMarkdown crossrefs; add an extra newline in verbatims to add space before the next paragraph; synchronize numbering schemes of all related MultiMarkdown tools to make it easier to ensure compatibility; add revision numbers to source documents to help track incompatibilities; add LaTeX support for i.e. and e.g.; TextMate MultiMarkdown bundle available; update MultiMarkdownDragAndDrop tools to new codebase; now distributed as a zipfile.

• 1.0.1Multi19.4 - major update; fix issue where cross-references to images defined by alt text had to follow the image in the document; add support for MathML via ASCIIMathPHP; change name to id for footnotes; move DoHeaders in front of DoTables to allow cross-references inside tables; fix handling of citations without locator; a table with no header titles and no column alignment row is interpreted as a pull-quote - this is experimental and may be changed; the Bibliography Title metadata field is available for LaTeX to rename the bibliography section; multiple changes to XSLT files to improve compatibility; support for << math >> syntax using ASCIIMathPHP; change HeaderLevel to Base Header Level and process it in XSLT rather than in the OmniOutliner tool; support for Affiliation metadata element; add equation label to possible cross-reference list; compatible with epigraph feature for XSLT conversion to LaTeX; document table labeling feature and default to caption if no label present;

• 1.0.1Multi19.2 - require leading space before unescaping \WikiWord; fixed bug where attributes not included with images; add Bibliography Title metadata key; fix bug with invalid leading characters in header id attributes; allow '-' and '_' in metadata; fix handling of citations in footnotes; fix issue with quotes in link attributes.

• 1.0.1Multi19.1 - minor change to bibliography formatting to allow translation into a \BibTeX compatible format without the use of a .bib file;

• 1.0.1Multi19 - Major update; fix bugs discovered by testing with MarkdownTest 1.0; don't add leading blank line if no metadata exists; fix parsing of link definitions, including attribute parsing; various clean- ups to code and documentation; improve cross-reference handling of special characters; fix bug in handling of wiki links (/ is not automatically added any more); fix bug in title attributes of images; re-enable the inclusion of DOCTYPE in complete documents (this requires the use of the -nonet and -novalid options in xsltproc; fix bug in handling of **; fix bug where WikiWords in code blocks and spans were not unescaped; fix bug where digits were not allowed in metadata keys; fix numbering of footnotes so that they remain in proper order; add basic citation and bibliography features; major bug fixes and testing to precede the release of version 20 (2.0)

• 1.0.1Multi18 - further work to make WikiWord escaping work properly...

• 1.0.1Multi17 - add support for "char" alignment in table columns (NOTE: browsers do not currently support this); fix bug with \ in code spans when WikiWords are disabled; fix bug in bold/italic detection

• 1.0.1Multi16 - can now optionally have header in first cell of each row; fix bug in footnote counting (thanks to Mark Eli Kalderon for pointing this out);

• 1.0.1Multi15 - allow for multiple <tbody> span's within a table; ensure that the variable$g_empty_element_suffix is used everywhere; protect code spans from table parsing

• 1.0.1Multi14 - captions can now be before or after table; add syntax for column spanning within tables (body and header)

• 1.0.1Multi13 - added support for CSS metadata key; allow no alignment option on table cells; support for captions for tables

• 1.0.1Multi12 - added support for image/link attributes; fixed bug in table handling

• 1.0.1Multi11 - added support for table syntax

• 1.0.1Multi10 - allow emphasis at beginning of line

• 1.0.1Multi9 - fix bug in metadata parsing

• 1.0.1Multi8 - first draft of fix for "underscore within a word" problem that causes so many errors with URL's. Now a leading whitespace is required in front of the "opening" _ or * for it to be interpreted as emphasis or strong.

• 1.0.1Multi7 - add Wiki Links support

• 1.0.1Multi6 - correct bug in footnote id handling (Thanks to Jonathan Weber for pointing this out)

• 1.0.1Multi5 - allow disabling of metadata feature

• 1.0.1Multi4 - convert © entities to © (compatible with XSLT); generate cross-refs for images

• 1.0.1Multi3 - fix metadata parsing in the event a key was empty

• 1.0.1Multi2 - add support for footnotes. Major change - no longer use templates, but rather will focus on using XSLT to convert from XHTML output to other formats. I think this will be more flexible and less error prone.

• 1.0.1M - initial release

  прим. пер.

  Якщо хтось знає точний переклад — прошу виправити.
  прим. пер.

  залишиться у вихіднму коді (ASCIIMathML).

  англійських слів.
  прим. пер.

  Якщо хтось вважає це за потрібне — може перекласти.
  прим. пер.

http://daringfireball.net/projects/markdown/

http://macromates.com/

http://www.literatureandlatte.com/scrivener.html