Документация это просто

[vak]

Какой нынче имеется простой способ писать документацию? Чтобы не заморачиваться, и чтобы сразу и HTML вариант и PDF вариант образовывались.

Есть такой метод! Показываю. Ключевые моменты: Pandoc и Tectonic.

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

# Задача

В школьной столовой Петя заметил, что количество котлет на тарелке уменьшается по формуле
$$
K(t) = K_0 - t,
$$
где $K_0$ — начальное число котлет, а $t$ — время в минутах, прошедшее с момента, как Петя сел за стол.

Если у Пети было 5 котлет, то через сколько минут Петя обратится к маме со словами:
*«Мам, а добавки можно?»*

# Таблица умножения

|   | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 |
|---|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|
| 1 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 |
| 2 | 2 | 4 | 6 | 8 | 10| 12| 14| 16| 18|
| 3 | 3 | 6 | 9 | 12| 15| 18| 21| 24| 27|
| 4 | 4 | 8 | 12| 16| 20| 24| 28| 32| 36|
| 5 | 5 | 10| 15| 20| 25| 30| 35| 40| 45|
| 6 | 6 | 12| 18| 24| 30| 36| 42| 48| 54|
| 7 | 7 | 14| 21| 28| 35| 42| 49| 56| 63|
| 8 | 8 | 16| 24| 32| 40| 48| 56| 64| 72|
| 9 | 9 | 18| 27| 36| 45| 54| 63| 72| 81|

![](kozak.svg){width=100}

Преобразуем это дело в HTML:

pandoc example.md -o example.html --standalone --mathjax

Получаем:


Аналогичным образом соорудим PDF:

pandoc example.md -o example.pdf --pdf-engine=tectonic --template=template.tex

Сравниваем:


Стиль PDF-документа можно задавать, меняя template.tex. Для HTML тоже есть аналогичный флаг --css=style.css.

Comments

[chaource]

А что дѣлать, если надо пронумеровать уравненiя и ссылаться на нихъ въ текстѣ?

[vak]

Смотрите документацию на Pandoc и Tectonic. Ссылки я дал.

[henry_flower]

Преобразуем это дело в HTML

хформули ув такому випадку лише обгортаються для подальшого рендерингу mathjax, який вантажиться зі cdn.jsdelivr.net (разом з необхідними шрифтами), тобто ув офлайні нічого не вийде

(шоб це побороти, я колись брав для того кєкнувшийся потім phantomjs і рендерив хформули ув інлайнові svg)

але для pdf це є неважливо, т.я. там md->tex->pdf

[vak]

Якщо потрібний зовсім онлайновий HTML, є якісь тулзи, що встромлюють всі зовнішні JS-скрипти прямо у документ.

[henry_flower]

тоді документа виросте на ~1.5MB, навіть якщо там 1 формула

я подивився як поліпшився mathjax за ці роки (став ще більшим) і спробував зрендерити його ув ноудівському jsdom

$ wc -l *js mathjax.conf.json 
  24 loader.js
 112 mathjax-embed.js
  12 mathjax.conf.json
 148 total

example.md ним можна обробити напилком як

$ pandoc -s example.md -t html --mathjax | mathjax-embed > example.html

результат виглядає ось так

src скрипта на ґітгабі. ноуд v22.20.0

[vak]

Тому PDF і зручніше для офлайнових документів. 😀

[henry_flower]

це так, але epub-рідери, наприклад, розуміють лише сабсет html (і ніякого js)

[vak]

Pandoc може створювати EPUB безпосередньо:

pandoc example.md -o example.epub --standalone --mathml

[henry_flower]

--mathml

якби все було так просто. прублема є не ув генерації epub (для того у мене свої скрипти), а ув тому шо не всі рідери підтримують mathml, тому svg залишається найпортабельнішим варіянтом

[henry_flower]

на федорі можна без Tectonic:

pandoc example.md -o example.pdf --pdf-engine=xelatex -V mainfont="Noto Sans"

[vak]

Можна і без Tectonic, якщо не ліниво встановлювати XeLaTeX. Взагалі Pandoc підтримує цілу купу PDF-енджинів.

[spamsink]

Если "в школьной столовой", то почему "к маме"?

[vak]

Не сечёт ИИ разницы между семьёй и социумом. 😀