В чём создавать документацию со вставками конфигов и выводом консоли?

Любой markdown редактор умеет генерить в pdf.

libreOffice write
код вставляю как таблицу из 1 элемента с черкой заливкой и нужным цветом/шрифтом текста. Можно вставлять скриншоты, есть автооглавление (через боль конечно, но в MSO не лучше), можно экспортировать в pdf, разбивает текст на листы a4 что удобно если результат надо напечатать.

Ну и TeX кончено, но его для начала изучить придется, зато когда разберешся то будишь только в нем писать

Md или TeX

Не нашёл редактора. Плохо искал. Не попалось прям на первой странице. Онлайны в основном.

org-mode

Хотелось бы обойтись без извратов, типа экпорта в xml из Notepad++ в Word или форматированием таблицей. Хотя html форматировал жы. Приму во внимание.

если для md, посмотри на Retext (Qt) и Apostrophe (GTK), может устроит, я сколько этих редакторов не пробовал от всех плевался, особенно когда документ большой

Не нашёл редактора

Редактор любой, конвертировать можно через pandoc.

Для либры есть хайлайтер-модуль, он еще и разметку текста подсветит.

Редактора чего? Маркдауна?

Нахрена для него специальный редактор-то? VSCode умеет и редачиить, и лайв-превью, и подсветку синтаксиса.

Retext (Qt)

Python, не нужно.
QOwnNotes можно попробовать.

Нахрена для него специальный редактор-то?

...

И с кнопочками редактор, выделил фрагмент - «Это код, делай красиво».

---

VSCode

Фи
---

Для либры есть хайлайтер-модуль, он еще и разметку текста подсветит.

Не встрачал, да я и не кодер, но звучит интересно. Вообще офисные пакеты и созданы для подобного

QOwnNotes

да можно и его, но мне он больше «для заметок» показался, сейчас глянул скрины, кнопки разметки на месте

Основная цель не создавать маркдауны, подсвечивать ошибки синтаксиса маркдауна, чтобы потом красиво их публиковать в веб. Нахрен оно мне надо. Цель - создавать документацию с конфигами и выводом консоли. Офисные пакеты с этим справляются плохо. Я markdown разметку вообще не должен видеть. Максимум в левом окне набирать, а в правом видеть как это будет выглядеть. И экспорт в pdf, а то те, кому буду это распространять, зависнут на md. Да, всё так плохо.

QOwnNotes

О!

Максимум в левом окне набирать, а в правом видеть как это будет выглядеть.

Надо попробовать. И к nextcloud своему прикрутить можно.

Ещё есть https://github.com/Waqar144/CuteMarkEd-NG от частого контрибьютера QOwnNotes.

A Qt-based, free and open source markdown editor with live HTML preview, math expressions, code syntax highlighting and syntax highlighting of markdown document.

Просто отправляй им готовый PDF. А верстать его можно хоть в LaTeX.

Если объём небольшой — инструкция к проге на несколько страниц — то я рекомендую markdown как формат и pandoc как конвертер из маркдауна во что душа пожелает — html/pdf/man/ватеверелсе. Редактор — любой текстовый, по вкусу. Пандок умеет даже синтаксис в примерах кода подсвечивать, причём всё настраивается. Иногда (на мой вкус) не слишком удобно, но настраивается.

Однако, предупреждаю: если объём большой, то маркдаун уже не лучший выбор, ибо все известные мне конвертеры слишком толерантены: забыл квадратные скобки закрыть — ну и хрен с ними, значит, это не ссылка а просто открывающая квадратная скобка; указал метку не ту — ну и хрен с ней, значит это не ссылка а просто слово в квадратных скобках.

Я markdown разметку вообще не должен видеть.

А, тебе визивиг нужен? Тогда Мелкософт Ворд велкам.

попробуй Jupyter Notebook как не странно

как получишь желаемый вид можешь экспортнуть в (список прилагается в тетрадке у чуня)

на выходе статический документ - почти по заветам кнутия программирования литературного (ага literate programming)

зы т.е подключаешь в качестве движка свой шелл

делаешь нужные ячейки -> твой код выдача шелла в перемешку - о как красиво

сохраняешь в тот же pdf - получаешь малыми усилиями док чё как

Привет!

Я профессиональный технический писатель, и ответ на вопрос «Как вы создаёте документацию?» не так-то прост.

Самый простой способ – Confluence. Там есть визуальный редактор и импорт в PDF. Кажется, этого должно хватить.

Варианты поинтересней – использование языков разметки:

• Sphinx:

  • Поддержка экспорта во множество форматов: HTML, EPUB, MAN, PDF…
  • Экспорт в PDF через LaTeX / XELaTeX.
  • Требуется знание ReStructured Text и самого Sphinx.
  • Кривая обучения не сильно крутая, за неделю можно освоить основы.
  • Требует наличия на компьютере Python.
  • Настраивать темы не очень сложно, уж шрифты в CSS поменять – дело двух минут. Но если мы говорим про PDF, то там всё не так однозначно – нужно знать LaTeX.

• AsciiDoc:

  • Поддержка экспорта в PDF, HTML и ещё несколько форматов.
  • Кривая обучения значительно круче чем у Sphinx, но возможности разметки мощнее.
  • Для погружения по-хорошему нужен месяц, лучше два.
  • На компьютере должен быть установлен Ruby и какой-нибудь менеджер его пакетов, например, Bundler.
  • Тема настраивается путём правки TOML-файла, где всё интуитивно понятно.

  На AsciiDoc я пишу свою книгу «GNU Emacs для технических писателей». PDF’ку можно скачать в одноименном Telegram-канале. Исходники не дам, но поделиться опытом могу.

Ещё есть такая штука Pandoc, позволяет конвертировать из одного формата в другой. Т. е. можно накидать что-то в Markdown а потом преобразовать в AsciiDoc и из него собрать PDF, используя нужную тему. Или напрямую из Markdown в PDF (возможны нюансы, сам не пробовал). Но использование нативной разметки явно лучше, меньше проблем потом.

Варианты поинтересней – использование языков разметки

На Расте есть интересный https://typst.app.

Спасибо, полезная информация.

Вот в таких случаях я жалею о том, что в рамках сайта нет возможности добавлять в избранное отдельные сообщения, а не просто тему целиком. (Уж лучше бы такая фича была вместо реакций.)