LINUX.ORG.RU
Форум — General  

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

 


1

2

Требуется инструкции кое какие оформить, нужен редактор какой-то, чтоб вывод консоли красивым Droid Sans Mono Slashed и чтобы понятно было что прям консоль-консоль и конфиги как-то выделить. Скриншоты вставить (нет). И с кнопочками редактор, выделил фрагмент - «Это код, делай красиво». Даже markdown устроил бы, но редактора не вижу и как распространять, надо людям в чём-то привычном отдать, хоть в pdf выгнать. Вы как документацию создаёте?

★

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

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

Kolins ★★★★
()
Ответ на: комментарий от Kolins

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

TepakoT ★
() автор топика
Ответ на: комментарий от Zhbert

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

...

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

---

VSCode

Фи
---

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

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

Kolins ★★★★
()
Последнее исправление: Kolins (всего исправлений: 1)
Ответ на: комментарий от Zhbert

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

TepakoT ★
() автор топика

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

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

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

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

debugger ★★★★★
()
Последнее исправление: debugger (всего исправлений: 1)

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

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

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

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

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

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

qulinxao3 ★
()

Привет!

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

Самый простой способ – 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 (возможны нюансы, сам не пробовал). Но использование нативной разметки явно лучше, меньше проблем потом.

dunmaksim ★
()
Ответ на: комментарий от dunmaksim

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

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

wandrien ★★
()
General