Язык разметки org-mode

2021-10-14 · 10 мин. для прочтения
blog computer-science

Язык разметки org-mode.

Содержание

1 Внешний вид

1.1 Изображения

  • Изображение можно вставлять просто в виде имени файла:
    ./img/cat.jpg
  • Можно задать заголовок и метку для изображения. Тогда изображение вставляется в виде ссылки.
    #+CAPTION: Заголовок изображения
#+NAME:   fig:image-a
[[./img/a.jpg]]
  • Такие изображения можно отобразить в буфере с помощью команды: C-c C-x C-v (org-toggle-inline-images).
  • При вызове с префиксом также отображать изображения, у которых есть заголовок: C-u C-c C-x C-v.
  • Можно активировать отображение встроенных изображений при запуске:
    • настроив переменную org-startup-with-inline-images;
    • установив в буфере параметр STARTUP в inlineimages (или noinlineimages).

1.2 Сноски

2 Заголовки разделов

* Самый большой заголовок (уровень 1)

Новая глава.

** Больший заголовок (уровень 2)

Новый раздел.

*** Большой заголовок (уровень 3)

Новый подраздел.

**** Заголовок (уровень 4)

Новый подподраздел.
  • Можно создавать нумерованные заголовки до определенного уровня, задав параметр:
#+OPTIONS: H:4

3 Абзацы

3.1 Обычные

Один перевод строки не имеет эффекта.
Эта строка является частью того же абзаца.

Пустая строка

разграничивает абзацы.

3.2 Горизонтальные линии

  • Для горизонтальной линии вставьте не менее 5 тире.
    Текст над горизонтальной линией.
-----
Текст под горизонтальной линией.

4 Форматирование текста

4.1 Полужирный и курсив

  • Выделение текста.

    /Emphasize/ (курсив), *strongly* (жирный) и */very strongly/* (жирный курсив).

  • Элементы разметки могут быть вложенными:

    Это /курсивный текст, содержащий _подчёркнутый текст_ внутри себя/, тогда как _это обычный подчёркнутый текст_.

  • Разметка может занимать несколько строк, по умолчанию не более 2:

*Это
не
жирный шрифт.*
  • Режим Org не интерпретирует маркер, окруженный буквенно-цифровыми символами, как маркер выделения.
  • Поэтому нельзя выделить только часть слова.

4.2 Моноширинный, верхний и нижний индексы.

- моноширинный шрифт пишущей машинки для ~встроенного кода~
- моноширинный шрифт пишущей машинки для =дословного текста=
- +удаленный текст+ (в отличие от _вставленного текста_)
- текст с верхним индексом, например, 2^{10}
- текст с нижним индексом, например, H_{2}O

5 Списки

  • Разметка Org позволяет создавать маркированные или нумерованные списки.
  • Допускается любая комбинация типов списков.

5.1 Неупорядоченные списки

  • Списки с пунктами помечаются маркерами.
  • Создавайте их с помощью знака минус или плюс.
    ​- Пункт с длинным текстом, переносящимся, желательно, на несколько строк. Добавлено несколько слов, чтобы наглядно показать перенос строк.
​- Маркер.
​  + Маркер.
​    * Маркер.

5.2 Контрольные списки

  • Отмечется с помощью C-c C-c.
- [X] Отмечено.
- [-] Отмечено наполовину.
- [ ] Не отмечено.
- Обычный пункт списка.

5.3 Упорядоченные списки

  • Нумерованные списки помечаются цифрами или буквами:
1. Элемент списка с арабской (десятичной) нумерацией.
   A. Элемент списка с номером, начинающимся с заглавной буквы.
      a. Строчная буква.
      b. Строчная буква.
   B. Заглавная буква.
2. Номер.
  • Можно иметь упорядоченные списки с заданием номера:
    2. [@2] Начинаем с пункта номер 2.
3. Элемент с автоматической нумерацией.

5.4 Списки определений

  • Помеченные многострочные списки.
    ​- Первый термин для определения ::
     Определение первого термина. Добавляем несколько слов, чтобы показать перенос строк, чтобы увидеть, что происходит при длинных строках.

- Второй термин ::
     Объяснение второго термина с помощью *встроенной разметки*.

     Во многих абзацах.

5.5 Разделение списков

  • Смежные списки иногда сливаются.
  • Чтобы начать новый список, сместите два списка на пустую строку комментария:
    ​- apples
​- oranges
​- bananas

# Комментарий.

- carrots
​- tomatoes
​- celery

6 Таблицы

  • Таблицы легко создавать и читать.

6.1 Простая таблица

  • В таблицах Org ячейки имеют длину не более одной строки.
  • В Org не существует многострочных ячеек таблиц.
    | Ячейка в столбце 1, строка 1 | Ячейка в столбце 2, строка 1 |
| Ячейка в столбце 1, строка 2 | Ячейка в столбце 2, строка 2 |

6.2 Форматирование столбцов

  • Столбцы выравниваются автоматически:
    • числовые столбцы — справа;
    • строковые столбцы — слева.

6.2.1 Таблица с выровненными ячейками

  • Чтобы изменить автоматическое выравнивание, используйте <r>, <c> или <l>.
    #+caption: Таблица с выровненными столбцами
|          <r> |     <c>      | <l>          |
|            1 |      2       | 3            |
|       Справа |  По центру   | Слева        |
| xxxxxxxxxxxx | xxxxxxxxxxxx | xxxxxxxxxxxx |

6.3 Строка заголовка

  • Можно создать таблицу со строкой заголовка
  • Используем горизонтальную линию тире для отделения ее от остальной части таблицы.
    #+caption: Таблица с заголовком
| Название столбца 1 | Название столбца 2   | Название столбца 3 |
|--------------------+----------------------+--------------------|
| Верхний левый угол | Верхний средний угол |                    |
|                    |                      | Справа             |
| Нижний левый угол  | Нижний средний угол  |                    |

6.4 Размещение таблицы

#+ATTR_LATEX: :center nil
| a | b |
| 1 | 2 |

XXX Отличается от следующего:

| a | b |
| 1 | 2 |

6.5 Выравнивание таблиц по странице

  • Выравнивание при экспорте в LaTeX.

6.5.1 По левому краю

  • Параметр noindent просто убирает отступ первой строки абзаца, которая в данном случае является таблицей.
  • Параметр hfill добавляет бесконечное растяжение после таблицы, поэтому он сдвигает таблицу влево.
    #+LATEX: \noindent
#+ATTR_LATEX: :center nil
| a | b | c |
|---+---+---|
| 1 | 2 | 3 |
| 4 | 5 | 6 |
#+LATEX: \hfill

6.5.2 По центру

| a | b | c |
|---+---+---|
| 1 | 2 | 3 |
| 4 | 5 | 6 |

6.5.3 Справа

  • hfill добавляет бесконечное растяжение перед таблицей, поэтому она сдвигает таблицу вправо.
#+LATEX: \hfill
#+ATTR_LATEX: :center nil
| a | b | c |
|---+---+---|
| 1 | 2 | 3 |
| 4 | 5 | 6 |

6.6 Размер таблицы

#+ATTR_HTML: :width 100%
#+ATTR_LATEX: :width 100%
| Ячейка в столбце 1, строка 1 | Ячейка в столбце 2, строка 1 |
| Ячейка в столбце 1, строка 2 | Ячейка в столбце 2, строка 2 |

7 Ссылки

7.1 Внешние ссылки

http://orgmode.org/ (автоматически форматируется).
[[http://orgmode.org/][Веб-сайт Org mode]].

7.1.1 Относительные ссылки

[[../README.html][Главная]]

7.1.2 Ссылки на электронную почту

[[mailto:john.doe@example.com][email John Doe]]

7.1.3 Ссылки на изображения

[[file:images/org-mode-unicorn.png]]

7.2 Внутренние ссылки

7.2.1 Встроенные якоря

  • Якоря используются для указания целей гипертекстовых ссылок.
<<anchor>> Встроенные якоря позволяют ссылаться на произвольный контент.

7.2.2 Внутренние перекрестные ссылки

  • Ссылки обычно указывают на заголовок.
См. главу [[#links][Links]].

  • Добавить ссылку на рисунок (например, «См. рисунок 1»):

    #+caption: caption
#+name: fig-imagename
[[file:imagename.png]]

См. рисунок [[fig-imagename]].

  • Можно создать гипертекстовую ссылку на якорь документа в текущем документе или в другом документе.

    См.:
​- Расположение [[якорь][перекрестная ссылка]].
​- Раздел [[id:0d2b0cb2-116c-4a61-a076-4c641faf4346][Внутренние ссылки]]

8 Изображения

8.1 Встроенное изображение

#+caption: Логотип Org mode
[[file:images/org-mode-unicorn.png]]

Нажмите, чтобы увидеть [[file:images/org-mode-unicorn.png][Изображение единорога]].

8.2 Атрибуты и значения изображения

АтрибутЗначение(я)
:altАльтернативный текст
:height
:widthРазмер, заданный пользователем в пикселях
:align
:border
:bordercolor
:hspace
:vspace
:titleТекст, определяемый пользователем
#+attr_latex: :width 0.25\linewidth
[[file:images/org-mode-unicorn.png]]

9 Блок example (пример)

: 17.10.97 9:04 <DIR> bin
: 16.10.97 14:11 <DIR> DOS
: 16.10.97 14:46 <DIR> TEMP
: 16.10.97 14:37 <DIR> WINNT
: 16.10.97 14:25 119 AUTOEXEC.BAT
: 13.02.94 6:21 54,619 COMMAND.COM
  • Или
#+begin_example
17.10.97 9:04 <DIR> bin
16.10.97 14:11 <DIR> DOS
16.10.97 14:46 <DIR> TEMP
16.10.97 14:37 <DIR> WINNT
16.10.97 14:25 119 AUTOEXEC.BAT
 13.02.94 6:21 54,619 COMMAND.COM
#+end_example

10 Цитирование

10.1 Цитата

  • Блок quote для контента, не требующего сохранения переносов строк.
#+begin_quote
Давайте изменим наше традиционное отношение к построению программ:
вместо того, чтобы представлять, что наша главная задача --- инструктировать компьютер, что делать,
давайте сосредоточимся на объяснении людям, что мы хотим,
чтобы компьютер делал.

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

-- Дональд Кнут
, #+end_quote

, #+begin_quote
Всё должно быть максимально простым,
но не проще. -- Альберт Эйнштейн
, #+end_quote

10.2 Стих

  • Блок verse в конце каждой строки неявно делается перенос строки, а отступ сохраняется:

     #+begin_verse
Всё должно быть максимально простым,
но не проще. -- Альберт Эйнштейн
 #+end_verse

  • Обычно используется для цитирования отрывков из электронного письма:

 #+begin_verse
>> Встреча перенесена на следующую пятницу.
>
> Перенесен ли также срок сдачи отчета?

Да. И проверьте http://www.doodle.com/ для переноса встречи.

В основном тексте
   отступы
сохраняются.
#+end_verse

11 Комментарии

  • Можно добавлять комментарии в документ.

    # Этот комментарий Org здесь отображаться не будет.

  • Org не поддерживает комментарии внутри абзацев, поскольку комментарий завершает абзац.

  • Однако вы можете имитировать встроенные комментарии с помощью фрагментов экспорта, например, @@comment:...@@.

  • Если у вас есть таблицы, которые вы хотите игнорировать при экспорте, один из вариантов — использовать блоки комментариев или поддеревья :noexport:.

12 Замены

12.1 Общие замены

#+MACRO: longtext this very very long text

Вставьте {{{longtext}}} везде, где это необходимо.

Вставьте this very very long text везде, где это необходимо.

12.2 Стилизованные ссылки

#+MACRO: color @@html:<span style="color: $1">$2</span>@@

{{{color(blue, "Этот текст выделен синим цветом.")}}}

{{{color(red, "Другой текст выделен красным.")}}}

“Этот текст выделен синим цветом."

“Другой текст выделен красным."

Примеры макросов: https://github.com/fniessen/org-macros.

13 Исходный код

13.1 Встроенный код

Справочный код, например, ~variables~ или ~functions~ inline.

13.2 Блоки кода

  • Блоки исходного кода поддерживают подсветку синтаксиса:
/*
 * Приложение, которое выводит сообщение "Hello" в стандартный вывод.
 */
int main(int arc, char **argv)
{
  printf("Hello, %s!\n", (argc>1) ? argv[1] : "World");
  return 0;
}

(defvar hello "Hello")

(defun hello (name &optional greeting)
  (message "%s %s" (or greeting "Hello") name))

(setq tab-width 4)

13.3 Номера строк

  • Как в example, так и в src в фрагментах кода можно добавить оператор -n в конец строки begin, чтобы получить нумерацию строк:
#+begin_src emacs-lisp -n
(defun org-xor (ab)
  "Исключающее ИЛИ."
#+end_src

1(defun org-xor (ab)
2  "Исключающее ИЛИ."
  • При использовании оператора +n нумерация из предыдущего пронумерованного фрагмента будет продолжена в текущем:
#+begin_src emacs-lisp +n
  (if a (not b) b))
#+end_src

3(if a (not b) b))

13.4 Выноски

  • В примерах Org интерпретирует строки типа (ref:name) как метки и использует их в качестве целей для специальных гиперссылок, таких как [[(name)]] (т.е. имя ссылки, заключенное в одинарные скобки).

  • В HTML при наведении курсора мыши на такую ​​ссылку будет удаленно подсвечиваться соответствующая строка кода.

  • Можно добавить ключ -r, который удаляет метки из исходного кода.

  • С ключом -n ссылки на эти ссылки будут помечены номерами строк из листинга кода, в противном случае ссылки будут использовать метки без скобок.

1(save-excursion ;
2  (goto-char (point-min))) ;

В строке 1 мы запоминаем текущую позицию. Line 2 переходит к point-min.

14 Математика

  • Можно встраивать математическое форматирование LaTeX в файлы Org mode.

14.1 Строчные математические выражения

  • Для встроенных математических выражений используйте обозначение в скобках \(...\).
  • Использовать конструкцию $...$ не рекомендуется.
    Формула \(a^2 + b^2 = c^2\) была открыта Пифагором.

Пусть \(a=\sin(x) + \cos(x)\). Тогда \(a^2 = 2\sin(x)\cos(x)\), потому что \(\sin^2x + \cos^2x = 1\).

Формула \(a2 + b2 = c^2\) была открыта Пифагором.

Пусть \(a=\sin(x) + \cos(x)\). Тогда \(a2 = 2\sin(x)\cos(x)\), потому что \(\sin2x + \cos^2x = 1\).

14.2 Выключные математические выражения

  • Для математических выражений, которые вы хотите выделить, центрировав на отдельной строке, используйте \[...\].
  • Двойные знаки доллара ($$) использовать не следует.
    Теорема Эйлера:

\[
\int_0^\infty e^{-x^2} dx = {{\sqrt{\pi}} \over {2}}
\]

LaTeX позволяет встраивать такие конструкции ~\[...\]~:
\[ \frac{-b \pm \sqrt{b^2 - 4 ac}}{2a} \]

Теорема Эйлера:

\[ \int_0^\infty e^{-x^2} dx = {{\sqrt{\pi}} \over {2}} \]

LaTeX позволяет встраивать такие конструкции \[...\]: \[ \frac{-b \pm \sqrt{b^2 - 4 ac}}{2a} \]

\[
\left( \int_{0}^{\infty} \frac{\sin x}{\sqrt x}\,\mathrm{d}x \right)^{2} - \prod_{k=1}^{\infty} \frac{4k^{2}}{4k^{2}-1} + \frac{\lambda}{2n}\sum_{k=1} ^{n} \theta_{k} ^{2} x^{n} = 0.
\]

\[ \left( \int_{0}{\infty} \frac{\sin x}{\sqrt x}\,\mathrm{d}x \right){2} - \prod_{k=1}{\infty} \frac{4k{2}}{4k^{2}-1} + \frac{\lambda}{2n}\sum_{k=1} ^{n} \theta_{k} {2} x{n} = 0. \]

14.3 Номера уравнений

  • К выключному уравнению можно добавить метку и ссылаться на уравнение по имени (метке) в других частях текста.
    Теорема Пифагора:

#+name: eq-pythag
\begin{equation}
a^2 + b^2 = c^2
\end{equation}

См. уравнение [[eq-pythag]].

Теорема о синусах может быть записана в виде уравнения:

\begin{equation}
\label{eq-sinalpha}
\frac{\sin\alpha}{a}=\frac{\sin\beta}{b}
\end{equation}

См. уравнение [[eq-sinalpha]].

15 Подключение файлов

15.1 Включение файлов Org

  • Можно включить другой файл Org и пропустить его заголовок, используя аргумент :lines для #+INCLUDE:
#+INCLUDE: "chapter1.org" :lines "2-"
  • Включение файлов с помощью ключевых слов INCLUDE является функцией, доступной только при экспорте.

16 Сноски

Можно определить именованные сноски[fn:myfootnote] или сноски с автоматическими якорями[fn:2].
Emacs Org-Mode
Дмитрий Сергеевич Кулябов
Authors
Дмитрий Сергеевич Кулябов
Профессор кафедры теории вероятностей и кибербезопасности
Работаю профессором на кафедре теории вероятностей и кибербезопасности Российского университета дружбы народов им. Патриса Лумумбы. Научные интересы относятся к области теоретической физики и математического моделирования.