HelpDown — конвертер md -> htm -> hlf
- NightRoman
- Posts: 6225
- Joined: Fri 18 Aug, 2006 13:52
- Location: Cambridge, UK
- Has thanked: 42 times
- Been thanked: 62 times
- Contact:
HelpDown — конвертер md -> htm -> hlf
Проект называется HelpDown и включен в исходники FarNet.
Приложения распространяются как два NuGet пакета:
https://www.nuget.org/packages/MarkdownToHtml
https://www.nuget.org/packages/HtmlToFarHelp
Реализован следующий сценарий. Документация (хелп к плагину) пишется в markdown. Затем markdown конвертируется в HTML с помощью MarkdownToHtml. Полученный файл конвертируется в HLF с помощью HtmlToFarHelp. Промежуточный HTML либо удаляется, либо тоже включается в поставку вместе с HLF для удобного просмотра хелпа в браузере.
Предыстория в теме Встроенная справка в удобном формате
Приложения распространяются как два NuGet пакета:
https://www.nuget.org/packages/MarkdownToHtml
https://www.nuget.org/packages/HtmlToFarHelp
Реализован следующий сценарий. Документация (хелп к плагину) пишется в markdown. Затем markdown конвертируется в HTML с помощью MarkdownToHtml. Полученный файл конвертируется в HLF с помощью HtmlToFarHelp. Промежуточный HTML либо удаляется, либо тоже включается в поставку вместе с HLF для удобного просмотра хелпа в браузере.
Предыстория в теме Встроенная справка в удобном формате
- NightRoman
- Posts: 6225
- Joined: Fri 18 Aug, 2006 13:52
- Location: Cambridge, UK
- Has thanked: 42 times
- Been thanked: 62 times
- Contact:
HelpDown — конвертер md -> htm -> hlf
Latest post of the previous page:
Принято к сведению. Надо подумать, что стоит или нет. Прямо сейчас не получится, работаю над другими проектами.В какой схеме колорера недочет? В markdown? Тогда подробнее (я уж забыл немного, что там и как).
- John Doe
- Бюрократ
- Posts: 14582
- Joined: Wed 27 Apr, 2005 20:42
- Location: github.com/FarManagerLegacy
- Has thanked: 92 times
- Been thanked: 514 times
- Contact:
HelpDown — конвертер md -> htm -> hlf
Markdown
Если в конце строки добавить два пробела, то последний подсветится (в обычном тексте, в списках).
В blockquote не подсветится.
А смысл двух пробелов это принудительный перенос строки (в html будет <br/>)
Edit:
Ещё в схеме не предусмотрена возможность атрибутов в fenced code block:
Если в конце строки добавить два пробела, то последний подсветится (в обычном тексте, в списках).
В blockquote не подсветится.
А смысл двух пробелов это принудительный перенос строки (в html будет <br/>)
Edit:
Ещё в схеме не предусмотрена возможность атрибутов в fenced code block:
Last edited by John Doe on Sun 12 Nov, 2017 21:45, edited 1 time in total.
- John Doe
- Бюрократ
- Posts: 14582
- Joined: Wed 27 Apr, 2005 20:42
- Location: github.com/FarManagerLegacy
- Has thanked: 92 times
- Been thanked: 514 times
- Contact:
HelpDown — конвертер md -> htm -> hlf
А пока оставлю последующим поколениям инструкцию с чего начать при использовании pandoc.
pandoc поддерживает ряд расширений стандарта markdown, детально описано тут: https://pandoc.org/MANUAL.html#pandocs-markdown.
Расширения можно произвольно (де)активировать, например auto_identifiers будет мешать (в HtmlToFarHelp используется конвенция: каждый заголовок с id это новая статья hlf).
Ещё при использовании с HtmlToFarHelp имеет значение ключ командной строки
Чтобы установить заголовок для html можно воспользоваться такой конструкцией в начале файла
Вот мои ассоциации:
md->html | *.md;*.text
html->hlf | *.html
pandoc поддерживает ряд расширений стандарта markdown, детально описано тут: https://pandoc.org/MANUAL.html#pandocs-markdown.
Расширения можно произвольно (де)активировать, например auto_identifiers будет мешать (в HtmlToFarHelp используется конвенция: каждый заголовок с id это новая статья hlf).
Ещё при использовании с HtmlToFarHelp имеет значение ключ командной строки
--wrap=preserve (на отображении не сказывается, но всё же удобнее когда абзацы в исходнике hlf свёрнуты).Чтобы установить заголовок для html можно воспользоваться такой конструкцией в начале файла
Вот мои ассоциации:
md->html | *.md;*.text
Code: Select all
pandoc --wrap=preserve -s -f markdown-auto_identifiers -o "!\!.html" "!\!.!"Code: Select all
HtmlToFarHelp.exe from="!\!.!" to="!\!.hlf"- NightRoman
- Posts: 6225
- Joined: Fri 18 Aug, 2006 13:52
- Location: Cambridge, UK
- Has thanked: 42 times
- Been thanked: 62 times
- Contact:
HelpDown — конвертер md -> htm -> hlf
Все-таки пожелание потребовало целой статьи 
Спасибо, это все полезно будет.
Спасибо, это все полезно будет.
- John Doe
- Бюрократ
- Posts: 14582
- Joined: Wed 27 Apr, 2005 20:42
- Location: github.com/FarManagerLegacy
- Has thanked: 92 times
- Been thanked: 514 times
- Contact:
HelpDown — конвертер md -> htm -> hlf
Большинство того, что попалось онлайн работает плохо.
Подошёл вот этот https://web.liferay.com/de/community/fo ... e/84206009
Для командной строки нашёл пока только под perl https://github.com/pjf/Markdown-phpBB, https://github.com/ohnonot/md2bb.pl
Под pandoc тоже существует, но haskell готовить я не умею.
- NightRoman
- Posts: 6225
- Joined: Fri 18 Aug, 2006 13:52
- Location: Cambridge, UK
- Has thanked: 42 times
- Been thanked: 62 times
- Contact:
HelpDown — конвертер md -> htm -> hlf
Пофиксил, пул реквест в очереди с еще одним фиксом.
https://github.com/colorer/Colorer-schemes/pull/61
Последнее время ждать "приема" приходится долго...
- John Doe
- Бюрократ
- Posts: 14582
- Joined: Wed 27 Apr, 2005 20:42
- Location: github.com/FarManagerLegacy
- Has thanked: 92 times
- Been thanked: 514 times
- Contact:
HelpDown — конвертер md -> htm -> hlf
Спасибо, подключил, то что надо.
"Ещё один фикс" тоже весьма кстати.
Соберу тут пожелания по раскраске:
"Ещё один фикс" тоже весьма кстати.
Соберу тут пожелания по раскраске:
- Возможно ли раскрашивать fenced code blocks соответственно указанному типу?
- И сложно ли распознавать setext-заголовки (т.е. подчёркнутые)?
- Расширенное использование бэкслеша для экранирования.
- В конце строки для индикации жёсткого переноса, отображать с ярким фоном (как и завершающие два пробела)
- Перед пробелом отображать бэкслеш бледно (как и перед остальными escape-символами)
Last edited by John Doe on Fri 17 Nov, 2017 11:43, edited 1 time in total.
- NightRoman
- Posts: 6225
- Joined: Fri 18 Aug, 2006 13:52
- Location: Cambridge, UK
- Has thanked: 42 times
- Been thanked: 62 times
- Contact:
HelpDown — конвертер md -> htm -> hlf
Первое можно для некоторого забитого набора языков из тех, что есть у колорер. Пробовал, работает. Пока неохота.
Второе не знаю, как. И можно ли вообще. Конструкция (начало определяется концом) не вписывается в обычную схему парсинга колорера.
- John Doe
- Бюрократ
- Posts: 14582
- Joined: Wed 27 Apr, 2005 20:42
- Location: github.com/FarManagerLegacy
- Has thanked: 92 times
- Been thanked: 514 times
- Contact:
HelpDown — конвертер md -> htm -> hlf
https://github.com/FarManagerLegacy/HelpDown-scripts | Скачать
Makefile for documents converting using pandoc. Source: *.text (extension defined by SOURCE_EXT). Target(s): enumerated in commandline (otherwise can be set in .DEFAULT_GOAL) Usage: make some_doc.html Convert some_doc.text to some_doc.html. Instead of ".html" any other pandoc-supported file type can be used. make html Convert *.text to *.html. Instead of ".html" any other supported extension can be used, incl. hlf (must be enumerated in TARGET_EXT). make some_doc.hlf make hlf Convert to .hlf using pandoc and HtmlToFarHelp. make some_doc.forum make forum Convert to phpBB-flavored markdown (Litedown). make clean Clean current directory from all files with extensins specified in TARGET_EXT. make help This help make install Copy *.lua to $(APPDATA)\pandoc\filters Or to $$(DATA_DIR)\filters (if defined). Notes: 1. pandoc.exe and HtmlToFarHelp.exe must be available. It is also possible to define full paths in env variables PANDOC/HTMLTOFARHELP. 2. Some conversions may require additional lua filters, which must be present in current directory. Alternatively they can reside in $(DATA_DIR)\filters (See `make install`) 3. Some conversions may require lua writers, which must be present in current directory. Alternatively they can reside in $(DATA_DIR)\custom 4. The best way to customize this Makefile is including it in own Makefile, adding new rules and (re)defining corresponding variables.
https://t.me/FarManager — Telegram чат
- John Doe
- Бюрократ
- Posts: 14582
- Joined: Wed 27 Apr, 2005 20:42
- Location: github.com/FarManagerLegacy
- Has thanked: 92 times
- Been thanked: 514 times
- Contact:
HelpDown — конвертер md -
Предлагается система сборки документации
в различных форматах (.hlf, .html, и .md для форума)
из единого источника на базе Markdown.
Система представляет собой базовый
необходимых для тонкой настройки вывода.
Предполагается использовать это наподобие конструктора: для каждого проекта создаётся свой локальный
в котором подключается базовый, и указываются необходимые фильтры (имеющиеся в наборе, либо добавленные локально).
Требования:
Всё, теперь при наличии исходного документа в файле с расширением *.text достаточно запустить команду
Или же явно указать цель:
В качестве цели также может быть указано имя результирующего файла.
в различных форматах (.hlf, .html, и .md для форума)
из единого источника на базе Markdown.
Система представляет собой базовый
Makefile, и несколько lua-скриптов (“фильтров”),необходимых для тонкой настройки вывода.
Предполагается использовать это наподобие конструктора: для каждого проекта создаётся свой локальный
Makefile,в котором подключается базовый, и указываются необходимые фильтры (имеющиеся в наборе, либо добавленные локально).
Требования:
- pandoc
- HtmlToFarHelp (или прямая ссылка на файл пакета)
- make или
winget install ezwinports.make Makefile+ cкрипты из данного репозитория. Или архив.
- Для md, в частности для публикации на Github:
- При конвертации в Github-flavored Markdown у заголовков пропадают
id, указанные посредством attribute syntax,
а значит ломаются ссылки. Их можно исправить, используя “автоматические идентификаторы” (Implicit Headers IDs). - DefinitionList (Description List) не является стандартной фичей маркдауна, его надо заменить на BulletList.
- При конвертации в Github-flavored Markdown у заголовков пропадают
- Для hlf:
- Cформировать индекс справки, и в каждый раздел добавить перекрёстные ссылки на другие
(например в верхнем блоке как в справке LuaCheck. Или в нижнем, как в BufferScroll). - Выделить внутренние заголовки, добавив их содержимому дополнительный отступ.
- Cформировать индекс справки, и в каждый раздел добавить перекрёстные ссылки на другие
- Для презентации какого-либо скрипта на форуме его документацию стоит специально подготовить, в частности:
Никто в здравом уме не станет сам с этим возиться, но если всё автоматически, то почему бы и нет.
Предусмотрена также автоматизация обновления соответствующего поста на форуме. - Для html полезно Title не оставлять пустой, а продублировать туда первый Header.
Makefile подобного примеру в Makefile.sample. Всё, теперь при наличии исходного документа в файле с расширением *.text достаточно запустить команду
make для создания *.hlf. Или же явно указать цель:
make hlf, make html, make forum. В качестве цели также может быть указано имя результирующего файла.
- HaRT
- Moderator
- Posts: 11458
- Joined: Tue 30 Aug, 2005 17:21
- Has thanked: 270 times
- Been thanked: 417 times
HelpDown — конвертер md -> htm -> hlf
Не лучше ли ради единообразия заменить
forum на BBCode/bbcode? Или хотя бы дополнить…Фар есть инструмент, а не нянька. © 2009 DrKnS
- John Doe
- Бюрократ
- Posts: 14582
- Joined: Wed 27 Apr, 2005 20:42
- Location: github.com/FarManagerLegacy
- Has thanked: 92 times
- Been thanked: 514 times
- Contact:
HelpDown — конвертер md -> htm -> hlf
Сообщения для форума представляют собой markdown лишь с некоторыми вкраплениями bbcode.
Когда-то я делал скрипт который действительно полностью конвертировал маркдаун в bbcode, но с некоторых пор в такой конвертации необходимости нет.
Но расширение bbcode у меня зарезервировано у меня именно для настоящего bbcode.
Когда-то я делал скрипт который действительно полностью конвертировал маркдаун в bbcode, но с некоторых пор в такой конвертации необходимости нет.
Но расширение bbcode у меня зарезервировано у меня именно для настоящего bbcode.
https://t.me/FarManager — Telegram чат
-
Yegor
- Posts: 1506
- Joined: Mon 04 Apr, 2005 13:41
- Location: San Ramon, CA / Kharkov, UA
- Has thanked: 52 times
- Been thanked: 94 times
HelpDown — конвертер md -> htm -> hlf
О, а можно сконвертировать hlf назад в md? а то я тут начал для себя писать утилиту (но пока отложил)
Мы не можем ждать милостей от Фара, взять их у него — наша задача! (C) Мичурин
- John Doe
- Бюрократ
- Posts: 14582
- Joined: Wed 27 Apr, 2005 20:42
- Location: github.com/FarManagerLegacy
- Has thanked: 92 times
- Been thanked: 514 times
- Contact:
HelpDown — конвертер md -> htm -> hlf
Хм, даже внутри фара парсер hlf несколько глючный (см. багтрекер).а можно сконвертировать hlf назад в md
И перед фаром ведь стоит узкая задача: отобразить полу-отформатированный текст на экране.
Тогда как для конвертации из hlf куда-либо ещё всегда будет не хватать семантической информации: где список, где таблица, где абзац. Где жирный текст, а где курсив, или код.
Лучшее что можно тут сделать, это принять некие умолчания, и попытаться сделать преобразование, предполагая что наш hlf использует разметку в целом совместимую с Markdown (естественно за исключением ссылок).
Такая задача выполнима, но к сожалению она не поможет нам с зоопарком уже существующих hlf.
Вернее поможет, но только как промежуточный этап перед дальнейшей (в основном ручной) обработкой.
Pandoc предоставляет тут некоторые возможности.а то я тут начал для себя писать утилиту
Достаточно написать парсер на lua, который должен будет классифицировать элементы текста в соответствии с типами Pandoc, а о конвертации в кучу других форматов он позаботится сам.
Есть примеры подобных парсеров, например для самого маркдауна.
https://t.me/FarManager — Telegram чат
- John Doe
- Бюрократ
- Posts: 14582
- Joined: Wed 27 Apr, 2005 20:42
- Location: github.com/FarManagerLegacy
- Has thanked: 92 times
- Been thanked: 514 times
- Contact:
HelpDown — конвертер md -> htm -> hlf
Логичным дополнением тут будет и автоматическая актуализация соответствующего поста на форуме.John Doe wrote: Sat 11 May, 2024 18:52 Предлагается система сборки документации
в различных форматах (.hlf, .html, и .md для форума)
из единого источника на базе Markdown.
Вот дошли руки разобраться как это можно сделать: https://github.com/FarManagerLegacy/Hel ... te_post.sh
https://t.me/FarManager — Telegram чат