Комментарии 79
В этом плане у AsciiDoc синтаксис для таблиц гораздо гибче и читаемей (ну и стандарт единый). Сам AsciiDoc, увы, куда менее распространён, но если нам надо просто выгружать HTML/PDF/etc. - то вполне заслуживающий рассмотрения вариант.
Это будет следующая статья, "прекратите использовать Markdown".
AsciiDoc нативно поддерживается всеми публичными репозитариями (github, gitlab), намного более гибкий и продуманный чем markdown + нормальное форматирование таблиц. Мы работали с бюрократами из PCI DSS, вся оригинальная документация была в AsciiDoc, и нормально конвертировалась в PDF включая сложные графики (использовали Mermaid). В markdown даже графику вставить нельзя. Весьма позорный формат, который должен уйти на свалку истории.
Весьма позорный формат, который должен уйти на свалку истории.
У них же область применения разная. Markdown - это для случаев, когда минимального форматирования хочется. А AsciiDoc - оно 'semantically equivalent to DocBook'. (Вот интересно, про существование этого самого DocBook еще кто-нибудь помнит, кроме узких специалистов?) И делать его полноценную поддержку (чтобы все, что по спецификации положено, могло) - наверняка сильно сложно.
Зачем DocBook, если есть DITA, если уж мы про XML-based форматы? А DITA прекрасна, если нет острой потребности писать руками именно текстовый исходник и есть немного денежек на Oxygen XML Editor. Я часто думаю, насколько бы лучше были документы и светлее мозги у типичного офисного гуманитария, если бы все документы он вместо Word'а в чём-то подобном создавал...
Зачем DocBook, если есть DITA, если уж мы про XML-based форматы?
Если склероз мне ни изменяет - у них тоже слегка разная область применения. DocBook - оно именно для книжек, которые сплошной текст с оглавлением в начале и представляет из себя 'законченное произведение', про которое подразумевается, что его таки можно прочитать от начала до конца, не спотыкаясь. И средства там, соответственно, больше на такой формат подачи материала заточены.
А DITA - это про набор кусочков, которые потом можно компоновать, читать отдельно и прыгать по ним.
DITA никто не мешает использовать и в режиме "законченного произведения", а вот у DocBook с "компонованием кусочков" возможности как раз ограниченные, да. AsciiDoc тут вполне тягается с DITA, кстати, и превосходит DocBook.
А вот есть ли настолько функциональный и удобный нетехническому пользователю редактор для AsciiDoc, как Oxygen для DITA, - вопрос интересный... Пока что я вижу, что для таких пользователей массово пилят свои велосипеды под конкретную задачу там, где что DITA, что AsciiDoc справились бы из коробки (пример - всяческие конструкторы договоров, составляющие оные на основе типовых форм, заполняемых полей и опросников с выбором условий).
Сам AsciiDoc, увы, куда менее распространён
На самом деле распространен. Его любят как разрабы, так и аналитики и техписы.
но если нам надо просто выгружать HTML/PDF/etc
Да и для хостинга бложиков или публичных спек к фреймворку - тоже пойдет.
Загляните на https://docs.spring.io/spring-framework/reference/integration/rest-clients.html#rest-message-conversion (там табличка) и у нее вполне человеколюбивые исходники https://github.com/spring-projects/spring-framework/blob/v6.1.12/framework-docs/modules/ROOT/pages/integration/rest-clients.adoc?plain=1#L380.
Благодаря анторе, акциидоктор получил второе дыхание. Что бы проникнуться, можно полистать https://antora.org/ и ее документацию. Аккуратнее, там тяжеловато в спеках.
Про таблицы и asciidoc.
Как бе, если таблица не очень широкая или не очень длинная, она вполне неплохо разворачивается в "одну колонку". Пример выше как раз такое содержит.
Но делать на нем скоринг для выбора либы/решения/платформы - не очень подходит, эксель лучше справится.
Прискорбно, что ни adoc ни rst до сих пор не завезли ни в joplin ни в obsidian. Так бы этот богомерзкий md быстрее бы ушел в забытие)
А вообще-то, если env-file переименовать в txt-file (или в исходом виде вставить в любой документ), то и так будет очень читаемо и никуда не надо преобразовывать.
Если маркдаун генерируется, то нечего ему делать в репозитории; отложи его генерацию на этап сборки проекта
Таблица — хорошо там, где представляются табличные данные; если по каким-то причинам в табличные данные пролез кусок, к ним не относящийся, оформи его отдельным блоком под таблицей, а в ячейке проставь ссылку-сноску
Генерируемый файл следует сопровождать именованием вида filename.g.ext; PullRequest pipeline должен строго следить, чтобы никто не мог смержить файлы, имеющие .g. в имени, чтобы любой разработчик, посмотрев на готовый билд, знал, взглянув на имя файла, что его содержимое не подлежит ручной правке, то есть, сгенерировано автоматически, а, следовательно, править надо не этот файл, а генератор (а в файле можно проставить ссылку на этот самый генератор и другую информацию, например, исходник, из которого сгенерировано, чтобы долго не искать)
"Любое категоричное утверждение ошибочно, включая и это" (с).
Если маркдаун генерируется, то нечего ему делать в репозитории; отложи его генерацию на этап сборки проекта
Контрпримеры навскидку - "README.md", "CHANGELOG.md" файлы в репозитории. Вполне нужны прямо в репозитории, причём changelog вполне может быть сгенерированным (на основе закрытых тасков и тп).
Генерируемый файл следует сопровождать именованием вида filename.g.ext;
Это если у вас весь тулинг в проекте свой. А если какой-то внешний инструмент использует эти файлы?
К примеру - часть кода в проекте автогенерится и заливается в репозиторий, чтоб какой-то другой инструмент его просто достал и начал использовать. Например, у меня для веба компилится вся статика и хранится в репозитории, чтобы на каждом сервере не приходилось этого делать.
Контрпримеры навскидку - "README.md", "CHANGELOG.md" файлы в репозитории. Вполне нужны прямо в репозитории, причём changelog вполне может быть сгенерированным (на основе закрытых тасков и тп).
В репозитории должны быть исходные файлы, а артефакты сборки/обработки/генерации на основе исходников следует версионировать отдельно (не абсолютное правило, но рекомендация на уровне «не устанавливайте туалет на кухне»).
README.md не является артефактом.
CHANGELOG.md может быть результатом генерации, но не на основе исходников.
В статье рассматривается именно случай генерации из файла, который, предположительно, уже лежит в репе.
Это если у вас весь тулинг в проекте свой. А если какой-то внешний инструмент использует эти файлы?
Та же ситуация, что и с любыми другими артефактами сборки. Собственно, как было замечено на примере статики, вопрос шире обсуждаемой здесь темы. От себя скажу, что у нас сейчас ещё нет достаточно продвинутой системы версионирования, чтобы единообразно и систематически решать подобные задачи.
Таблица может не отобразится
tsya.ru
Для подобных замечаний на хабре есть удобная фича - выделяете фрагмент и нажимаете Ctrl-Enter, чтобы отправить информацию об опечатке в ЛС автору.
Все минусующие поддерживают незнание правил русского языка?
Многим плевать на ошибки, не меняющие смысл текста, а такие отдельные комментарии с исправлениями просто раздражают, отвлекая внимание при чтении.
А мне не плевать на ошибки, и как раз они меня при чтении раздражают, иногда даже до конца осилить текст не получается. Про пунктуацию я уж молчу, тут вообще она рукалицо.
А мне не плевать
Вы поинтересовались, ставят ли вам минусы за исправление ошибок - вам пояснили, что не за исправление, а за форму, в которую облечено это исправление. Дальше есть лишь четыре варианта решения проблемы по убыванию оптимальности:
изменить канал, по которому отправляются сообщения об ошибках (сообщать в личку)
ничего не менять и забить на минусы
прекратить сообщать об ошибках вовсе
перейти на какой-то иной ресурс, где все ваши действия будут вызывать лишь коллективный одобрямс
Ну а всем плевать что вас там раздражает. Вам бы ко психологу подлечить раздражительность.
А мне не плевать на ошибки, и как раз они меня при чтении раздражают, иногда даже до конца осилить текст не получается. Про пунктуацию я уж молчу, тут вообще она рукалицо.
Лично для меня такие ошибки — своеобразный измеритель интересности текста. Если статья интересна, я их просто не замечаю. А если начинаю считать запятые или проверять правильность слов, то, видимо, статья не очень (по крайней мере для меня), и на нее не стоит тратить время.
плевать на ошибки, не меняющие смысл текста
Данная ошибка кардинально меняет смысл текста. Но мы догадываемся, что автор наверное не хотел высказать такую странную мысль и сами додумываем правильный вариант. Всё это отвлекает от чтения исходного текста и заставляет терять драгоценное время на коррекцию ошибок. И теряется желание читать дальше.
Спасибо, исправил.
Сожалею, что раньше не смог добраться добраться с ответом и это породило столько волнений.
И как быть если нужна именно таблица? Показывать какие то табличные данные. Оформлять просто списком? оформлять отступами?
Маркдаун же ест и html
Простые таблицы выглядят нормально и в маркдауне
Если таблицы выходят за рамки простых, отказаться от маркдауна. Например, в asciidoc очень богатый и удобный синтаксис для таблиц почти любой сложности, а в rst можно сделать двухуровневый список который отрендерится как таблица
Если разработчики не знают pandoc и просто холиварят про TeX и markdown, это профнепригодность.
В командной строке набираем:
pandoc README.md -t plain
Если речь зашла о таблицах, то меня, как юзера, раздражают сайты/документы, из которых таблицы не копируются таблицы в виде таблиц. Захочешь такую скопипастить в условный ворд или эксель, а она вставляется, как набор строк, а не таблица.
Пфф.. Markdown... Таблицы...
Это вы ещё не видели как "таблица" может выглядеть внутри pdf ! И не пытались вытащить этот текст оттуда (потому что прайс опубликован на сайте в pdf, а надо их тащить с разных сайтов). Две внешне рядом стоящие буквы одного слова могут относиться к разным блокам, в которых ориентация текста вертикальная. Почему? Ну вот так документ решил сохраниться. И все попытки вытащить текст через "стандартное" API pdf приводят к кровавым слезам, в итоге проще перевести документ в картинку и загнать в OCR.
Если уж на то пошло - давайте запретим и csv-файлы. Вот у меня pandas читает файл: 30 колонок, 6k+ строк с float числами. Вроде и текстовый файл, но открывать лучше всё равно экселем.
Отступы в табличке Markdown вам не нравятся? А вы неформатированный json больше хотя бы 500 байт видели? Быстро сможете найти там вторую запись в массиве строк? Меж тем, форматированный вид - всего лишь опция.
В каждом инструменте есть свои недостатки. Возможно, мегабайтную таблицу в markdown запихивать не стоит, но для всех решений есть свои причины. "надо отрефакторить, техдолг" - чтож, тоже причина.
Выравнивать не пробовали? Например GNU/Emacs столбцы при редактировании автоматически выравнивает пробелами и так сохраняет:
| header 1 | header 2 |
|----------+----------|
| text 1 | text 2 |
| text 3 | text 4 |
Это значительно улучшает читабельность. Претензии к формату всё равно остаются, например нет возможности мультистрочных данных, но для простых кейсов явно удобнее более строгих языков разметки, как HTML.
Если приведенная автором статьи утилита это не умеет, то это вопрос к утилите, не к формату.
я, поправив немного его верхнюю часть и не заметил таблицу далеко внизу, то при сохранении автоматически запустится форматирование. После, я без зазрений совести, коммичу и пушу правки, зная, что изменил лишь одну строку в начале, но позже меня может ожидать неприятный сюрприз в виде шумного коммита.
Поэтому я завёл полезную привычку просматривать дифф с внесёнными изменениями перед коммитом.
поздравил коллегу с успехом
да уж, богданов в следующий раз 100 раз подумает, прежде чем делать мир лучше
а по теме: но если все-таки делать отображение столбцами, то почему бы не ввести 4-й столбец. видно же, что в каждом описании хранится допустимое значение параметра. если сделать 3-й столбец с допустимым значением параметра, то справа, в 4-м столбце можно будет сделать описание параметра
Я уверен, что это ни как не скажется на Андрее, и он по прежнему будет делать мир лучше.
Статья всё же не про утилиту, а про таблицы. Да, можно конечно добавить и 4й столбец, но лучше от этого не станет, а вот проблем от этого новых добавит. Как минимум, это потребует описать некий стандарт комментария, что бы описать данные 4-го столбца, и прочие вытекающие последствия.
Есть как минимум три расширения vscode для форматирования таблиц md.
Очень грустно, что не поддерживается многосторонность строк в таблицах md, приходится отключать перенос строк, чтобы использовать горизонтальный скролл, но жить можно.
Если таблица очень сложная, ее нужно хранить отдельно где-то.
Самый кошмар начинается, когда нужно сделать вложенную таблицу. Как известно, средствами Markdown это сделать нельзя, а значит — придётся прибегать к HTML, использование которого сведёт все преимущества Markdown к нулю (а также не факт, что на конкретном сайте такая таблица будет корректно отображена).
Я просто оставлю здесь... Табулятор.
Символ, кнопка, про который почему-то забыли.
А он позволяет вполне сносно отображать таблицы, если бы система могла ширину столбцов автоматические подгонять, плюс можно напрямую в текстовые процессоры копировать.
Сложности только с объединенными ячейками...
Используйте нормальные форматы и не будет всех этих проблем. https://marked.hyoo.ru/
Чем оно лучше AsciiDoc'а?
Очевидно, простотой, независимостью от раскладки клавиатуры, выравниваением столбцов, и возможностью вкладывать в ячейки произвольный контент, включая другие таблицы.
(поглядывая на LaTeX) Он тоже простой, да...
Как только начинается 'возможностью вкладывать в ячейки произвольный контент, включая другие таблицы.' - любой формат становится нечитаемыми и сложным.
Лучше бы вы по ссылке сходили, да поглядели, как делается простое и читаемое текстовое представление вложенных таблиц.
Ну да, конечно. Вот это(Отсюда, по ссылке ниже.):
! Dimensions
! 2
! 3
! Rotation
! " ! ;;cos A;;
! " ! ;;sin A;;
! " ! ;;- sin A;;
! " ! ;;cos A;;
! " ! ;;cos A;;
! " ! ;;sin A;;
! " ! 0
! " ! ;;- sin A;;
! " ! ;;cos A;;
! " ! 0
! " ! 0
! " ! 0
! " ! 1
Я не могу назвать не простым, ни читабельным.
Однако ux исследования показывают, что люди прекрасно справляются с чтением и редактированием таких таблиц. Глаза боятся - руки делают.
Люди, скорее всего, плохо справляются в любом случае. Возмем случай попроще.
!
! table
! header
! a
! There are many variations of passages of Lorem Ipsum available, but the majority have suffered alteration in some form, by injected humour, or randomised words which don't look even slightly believable.
! row
! b
! table
! row
Как тут просто найти, где находится ячейка на пересечении header и b? Особенно если таблица - побольше и на экране оно все сразу не помещается.
Чем оно лучше AsciiDoc'а?
Очевидно, у AsciiDoc'а есть фатальный недостаток.
У вас ссылка битая. Вот правильная: https://page.hyoo.ru/#!=6lqg5m_deygy0
Почитал.
Вы там много аппелируете к "не только английским" раскладкам, но что-то мне подсказывает, что речь исключительно про кириллицу, да? И точно ли это проблема формата разметки что на вашей клавиатуре нет []<>#?
P.S. В AsciiDoc в таблицы тоже можно вкладывать всё что угодно.
Я много к чему апеллирую.
Это решение проблемы. Можете предложить лучшее.
Можно пример, как в аскидоке вложить таблицу в таблицу?
[cols="1,2a"]
|===
| Col 1 | Col 2
| Cell 1.1
| Cell 1.2
| Cell 2.1
| Cell 2.2
[cols="2,1"]
!===
! Col1 ! Col2
! C11
! C12
!===
|===То, что начинается с '|' - это внешняя таблица. То, что '!' - вложенная.
Прекрасная читаемость. А для 3 уровня вложенности какой символ?
Ну написано же: 'you can choose another character by defining the separator attribute on the table.'
А про читаемость - мой тезис в том, что читабельность таких конструкций будет никакая в любом формате.
Раз уж тут начали рекламировать свои языки разметки, позвольте и мне вставить 5 коп. Вот так данная «таблица в таблице» выглядит в пк-разметке:
T‘
H‘‘Col 1’ ‘Col 2’’
‘‘Cell 1.1’ ‘Cell 1.2’’
‘‘Cell 2.1’ ‘Cell 2.2
[[[ ]]]T‘H‘‘Col1’ ‘Col2’’
‘‘C11’ ‘C12’’’’’
’
Да, набирать такое не очень удобно, но читаемость вполне себе неплоха.
Не согласен, выше приведенные примеры как раз решают проблему с отображением длинных строк, размещая их в виде списка.
А в pq, мы всё также вынуждены все ячейки одной строки, разместить в одной исходной строке. Большой объем содержимого здесь так же нарушит читаемость исходника.
А в pq, мы всё также вынуждены все ячейки одной строки, разместить в одной исходной строке.
Это ещё почему?
Хотите, всю таблицу вообще в одну строку, а хотите, в виде списка вот так:
T‘
H‘‘Col 1’
‘Col 2’’
‘‘Cell 1.1’
‘Cell 1.2’’
‘‘Cell 2.1’
‘Cell 2.2
T‘H‘‘Col1’ ‘Col2’’
‘‘C11’ ‘C12’’’’’
’
Я уж не говорю про возможность куда угодно вставлять [[[комментарии]]]. (Может быть полезно, чтобы давать подписи строкам или ячейкам таблицы.)
Некоторые могут возразить, мол, эпоха перфокарт давно прошла, и с современными 8K мониторами нет никаких проблем писать строки длиной от начала до конца экрана. Но мой аргумент простой: это создает лишний шум в коммитах и увеличивает нагрузку на ревьюера.
Но и короткие строки создают кучу шума в коммитах, если поддерживать консистентную ширину, особенно при добавлении или удалении каких-то слов в начале абзаца. А если не поддерживать — после нескольких правок из правого края абзаца получится жуткая пила со случайными переносами.
На мой взгляд рендер для документации куда важнее, чем исходник. Результат будут видеть намного чаще, чем страшную сгенерированную таблицу в markdown. Раз она сгенерированная из какого-то там исходника - в чём проблема редактировать исходник и из него готовить рендер?
Вообще беда конкретно вашего примера с конфигом nginx - это ширина второй колонки с дефолтным значением. Посмотрите, как Яндекс решает эту проблему:
Картинка
Можно просто убрать дефолтное значение в описание и контент будет выглядеть хорошо. Также обратите внимание на стиль таблицы зеброй - очень хорошо видно, где заканчивается текст, относящийся к конкретной опции. В вашем примере со списками на мой взгляд строчки смешиваются друг с другом и выглядит чуть ли не как книга какая-то.
На каждую ситуацию свой инструмент. Я бы не стал отказываться от таблиц только потому, что в IDE писателю-ревьюверу будет тяжело пару минут, а вместо этого почитал бы книжки от типографов, редакторов текста, гайдлайны интерфейсов в конце концов, где точно что-нибудь будет по этому поводу.
Да, любопытный холивар. Но смысла воевать не вижу. Первое, что пришло в голову — зачем понадобится лезть в исходник автоматически сгенерированного markdown документа?
Если его назначение — либо отобразиться в готовом виде, либо преобразоваться в PDF —генериться такое должно при сборке и не подразумевать рукопашку.
Ещё интересно было бы посмотреть, как вы управляетесь с этим "кусочком ограмного списка переменных" в самом env-файле. Для автогенерации все эти тексты со всей разметкой изначально должны храниться именно в нём? Тогда здесь, на мой взгляд, и заключается ваша болезненная рукопашка.
Вообще есть три вопроса, на которые нужно ответить перед написанием документации:
Для кого пишется документ?
Если документ пишется для себя, то формат, используемые фичи и т.п. вещи - не имеют значения. Делайте так, как вам будет удобно потом воспринимать текст.
Если пишите для команды, пользователей, руководства и т.д., то следует использовать те инструменты, с которыми они знакомы и которые им будет удобно воспринимать.
Я, например, периодически использую plantuml в markdown файлах, но для многих без "итоговых картинок" - это будет не читаемо.
Где будут читать документ наиболее часто?
Удаленный терминал с низким разрешением экрана - строгие ограничения под него. 128к монитор - ограничения под него. Сайт - ограничения под сайт. И т.д.
В каком формате будут читать документ?
Сам исходный файл - тогда делаем его максимально понятным для чтения, таблицы только небольшие, однострочные и т.д. и т.п.
Сгенерированный документ PDF или предпросмотр - хоть смайлик розового слона верхом на единороге используй для выделения заголовков вместо #, главное чтоб в итоговом виде было читабельно.
Как видно, восприятие таблицы в PDF значительно ухудшается: три страницы против одной.
О нет, используя таблицы в документации вы провоцируете производить больше виртуальной бумаги и тем самым лишаете домика множество индексов БД!
А вообще это отличный пример того, как автор нарушает собственный же совет (не перегружать ячейки содержимым) для доказательства своей точки зрения :)
Скрытый текст
Поиграться со шрифтами убрать колонтитулы и глядишь все уместится на один лист.
Если выкинуть допустимые значения NGINX_GZIP_PROXIED в отдельную таблицу и поставить на нее ссылку, то будет еще лучше.
Цветовая схема не очень, да, правится в конфиге.
К сожалению, я не нашел явных преимуществ использования таблиц в данном контексте
Оно ровно такое же, как и везде - наглядность.
Меня больше всего поражает то, что в далёкие времена учёные специально изобретали html для того, чтобы отображать самые разные документы. И не только отображать, а связывать их гиперссылками. К чему эта беготня за md я не могу понять.
Если так сильно нужно все уместить в одном файле, то даже для этого кейса есть mht.
Я воспринимаю markdown в качестве output-формата данных. Понятное дело, когда верстка тривиальна, то можно, не напрягаясь, писать в блокноте. Но таблички - это не совсем тривиальная вещь. А вложенные - это вообще не просто.
Поэтому для сорсов проще заюзать вообще базовый html, который будет конвертироваться в markdown. В ходе конвертации можно спокойно устанавливать ширину страницы в символах, а визуальные и иные средства редактирования html могут помочь определиться с шириной колонок. Плюс можно было бы запоминать конфигурации для конкретной платформы. Например, где-то будет считаться новым абзацем символ перевода строки, а где-то пробел и символ перевода строки.
Короче, я за то, чтобы markdown создавать через специализированные редакторы или html.
П.с. Правда немного смешно получается: из html мы делаем md, чтобы на том же github отобразили это в гипертексте.
Прекратите делать таблицы в Markdown