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:
Re: FarHelpDown — конвертер md -> htm -> hlf
Latest post of the previous page:
https://github.com/nightroman/FarHelpDown/downloadsv0.0.22.6 - Lists.
markdown.hrc
* Fixed span stoppers in definition lists.
* Amended ListMark region bounds.
- NightRoman
- Posts: 6225
- Joined: Fri 18 Aug, 2006 13:52
- Location: Cambridge, UK
- Has thanked: 42 times
- Been thanked: 62 times
- Contact:
Re: FarHelpDown — конвертер md -> htm -> hlf
Начал думать о поддержке таблиц в HLF конвертере. Ничего лучшего не придумывается, чем только пару колонок разрешать. Ширину каждой можно более менее оптимально посчитать, но общая ширина таблицы должна быть фиксированной и довольно узкой, чтобы работать в 80-колоночном окне Фара, да и еще и при неполном окне хелпа. Т.е. 70 колонок (или даже чуть меньше) получается. Вопрос: оно такое надо вообще?
- NightRoman
- Posts: 6225
- Joined: Fri 18 Aug, 2006 13:52
- Location: Cambridge, UK
- Has thanked: 42 times
- Been thanked: 62 times
- Contact:
Re: FarHelpDown — конвертер md -> htm -> hlf
Впрочем, если не рисовать разделитель колонок таблицы (а хотелось бы..), то можно-таки вторую колонку сделать с заворачивающимся текстом, но для первой колонки тогда придется требовать только очень коротких строк без заворота.
- HaRT
- Moderator
- Posts: 11458
- Joined: Tue 30 Aug, 2005 17:21
- Has thanked: 270 times
- Been thanked: 417 times
Re: FarHelpDown — конвертер md -> htm -> hlf
Ответьте профану, а в чём принципиальная сложность-то?
Вот, даже консольные браузеры неплохо вроде поддерживают таблицы…
Вот, даже консольные браузеры неплохо вроде поддерживают таблицы…
Фар есть инструмент, а не нянька. © 2009 DrKnS
- NightRoman
- Posts: 6225
- Joined: Fri 18 Aug, 2006 13:52
- Location: Cambridge, UK
- Has thanked: 42 times
- Been thanked: 62 times
- Contact:
Re: FarHelpDown — конвертер md -> htm -> hlf
Они динамически форматируют текст под текущее окно. А наш случай - другой. Нам надо сгенерить фиксированный HLF файл. Годный для любого окна (то есть минимально возможного, около 70). Фар не будет там таблицы форматировать динамически во время показа.HaRT wrote:Ответьте профану, а в чём принципиальная сложность-то?
Вот, даже консольные браузеры неплохо вроде поддерживают таблицы…
- HaRT
- Moderator
- Posts: 11458
- Joined: Tue 30 Aug, 2005 17:21
- Has thanked: 270 times
- Been thanked: 417 times
Re: FarHelpDown — конвертер md -> htm -> hlf
Ага, ясно. Но тогда откуда ограничение в 2 колонки?
Нам надо отформатировать под фиксированную ширину 70, притом минимизировать надо общую высоту таблицы, перераспределяя слова (а в плохом случае — отдельные символы) между строками.
В ужасном случае на 1 колонку надо 2 знакоместа внутри и 1 — на разделитель справа. Всяко больше 2 колонок поместится.
Нам надо отформатировать под фиксированную ширину 70, притом минимизировать надо общую высоту таблицы, перераспределяя слова (а в плохом случае — отдельные символы) между строками.
В ужасном случае на 1 колонку надо 2 знакоместа внутри и 1 — на разделитель справа. Всяко больше 2 колонок поместится.
Фар есть инструмент, а не нянька. © 2009 DrKnS
- NightRoman
- Posts: 6225
- Joined: Fri 18 Aug, 2006 13:52
- Location: Cambridge, UK
- Has thanked: 42 times
- Been thanked: 62 times
- Contact:
Re: FarHelpDown — конвертер md -> htm -> hlf
Ну можно и больше, да... Но все равно надо рассчитывать на ширину 70, либо делать без разделителей и с заворотом текста только последней колонки.
А о чем вообще писать в хелпе с таблицами в 3+ колонок? Просто юз-кейс какой-нибудь хотелось бы иметь. Не приходит в голову пока.
А о чем вообще писать в хелпе с таблицами в 3+ колонок? Просто юз-кейс какой-нибудь хотелось бы иметь. Не приходит в голову пока.
- HaRT
- Moderator
- Posts: 11458
- Joined: Tue 30 Aug, 2005 17:21
- Has thanked: 270 times
- Been thanked: 417 times
Re: FarHelpDown — конвертер md -> htm -> hlf
Что-нибудь типа такого.NightRoman wrote:А о чем вообще писать в хелпе с таблицами в 3+ колонок? Просто юз-кейс какой-нибудь хотелось бы иметь. Не приходит в голову пока.
Или, скажем, описание, как осуществить какие-то действия с помощью клавиатуры и с помощью мыши.
Фар есть инструмент, а не нянька. © 2009 DrKnS
- NightRoman
- Posts: 6225
- Joined: Fri 18 Aug, 2006 13:52
- Location: Cambridge, UK
- Has thanked: 42 times
- Been thanked: 62 times
- Contact:
Re: FarHelpDown — конвертер md -> htm -> hlf
А. Хорошо. Первый пример подпадает под заворачивать только последнюю колонку. Второй под 2-ю и 3-ю (жестко). ОК, буду думать дальше. Таблицы пригодятся, конечно. Кстати, как они в маркдауне реализованы - это не очень это удобно для длинных текстов. Но инлайн HTML тоже возможен на худой конец.
- John Doe
- Бюрократ
- Posts: 14582
- Joined: Wed 27 Apr, 2005 20:42
- Location: github.com/FarManagerLegacy
- Has thanked: 92 times
- Been thanked: 514 times
- Contact:
Re: FarHelpDown — конвертер md -> htm -> hlf
Придумать можно разного, но на практике почему-то больше 2х колонок никто не использует. Я про реальные *.hlfHaRT wrote:Что-нибудь типа такого.
Или, скажем, описание, как осуществить какие-то действия с помощью клавиатуры и с помощью мыши.
Зато в правой колонке бывает выравнивание по правому краю.
Не знаю надо ли это поддерживать в md, но обратите внимание.
- NightRoman
- Posts: 6225
- Joined: Fri 18 Aug, 2006 13:52
- Location: Cambridge, UK
- Has thanked: 42 times
- Been thanked: 62 times
- Contact:
Re: FarHelpDown — конвертер md -> htm -> hlf
Выравнивание-то не проблема, и у маркдауна в таблицах этот синтакс есть. В общем, подумаю еще, 2 колонки поддерживать или 2+ (и вообще таблицы, ха-ха).
Сами таблицы в маркдауне весьма примитивные, оказывается (или я не знаю продвинутый синтаксис). Взамен HTML таблицы иной раз имеет смысл пользовать для длинных текстов, иначе придется в редакторе длинные строки иметь, что в Фаре не очень удобно.
Сами таблицы в маркдауне весьма примитивные, оказывается (или я не знаю продвинутый синтаксис). Взамен HTML таблицы иной раз имеет смысл пользовать для длинных текстов, иначе придется в редакторе длинные строки иметь, что в Фаре не очень удобно.
- John Doe
- Бюрократ
- Posts: 14582
- Joined: Wed 27 Apr, 2005 20:42
- Location: github.com/FarManagerLegacy
- Has thanked: 92 times
- Been thanked: 514 times
- Contact:
Re: FarHelpDown — конвертер md -> htm -> hlf
Большинство таких простых таблиц (как в справке фара) семантически представляют собой definition lists.
Именно семантически, но ведь и визуально definition list можно изобразить таблицей (с помощью стилей).
Именно семантически, но ведь и визуально definition list можно изобразить таблицей (с помощью стилей).
- NightRoman
- Posts: 6225
- Joined: Fri 18 Aug, 2006 13:52
- Location: Cambridge, UK
- Has thanked: 42 times
- Been thanked: 62 times
- Contact:
Re: FarHelpDown — конвертер md -> htm -> hlf
Думал об этом. Мысль стоящая. Причем, списки определений удобно набирать в маркдауне, не то что таблицы. Подумаю, но это уже получается конвенция, да и вид в броузере (без стилей) будет отличаться существенно от хелп вьюера. Такие отличия и конвенции надо бы минимизировать (но не обязательно сводить к 0, конечно).
- John Doe
- Бюрократ
- Posts: 14582
- Joined: Wed 27 Apr, 2005 20:42
- Location: github.com/FarManagerLegacy
- Has thanked: 92 times
- Been thanked: 514 times
- Contact:
Re: FarHelpDown — конвертер md -> htm -> hlf
А в md нельзя аккуратненько класс указать?
Чтобы всё было "по-честному", без конвенций.
Чтобы всё было "по-честному", без конвенций.
- NightRoman
- Posts: 6225
- Joined: Fri 18 Aug, 2006 13:52
- Location: Cambridge, UK
- Has thanked: 42 times
- Been thanked: 62 times
- Contact:
Re: FarHelpDown — конвертер 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:
Re: FarHelpDown — конвертер md -> htm -> hlf
https://github.com/nightroman/FarHelpDown/downloads
v0.0.22.7 - Nested lists up to level 3 support all features
(речь о схеме markdown.hrc, хелп-конвертер не поддерживает вложенные списки)
В итоге схема markdown.hrc теперь делает все, что от нее было задумано получить, со следующими оговорками:
* Inline HTML should be valid XML.
* Opened spans are always colored.
* Blockquote contents is not parsed.
* List levels 4: only items are parsed.
* List levels 5+: all is colored as code.
* List levels: 4, 8, 12 spaces or 1, 2, 3 tabs.
Дальше будет в основном оптимизация и вылавливание ошибок, можно начинать жаловаться на них.
v0.0.22.7 - Nested lists up to level 3 support all features
(речь о схеме markdown.hrc, хелп-конвертер не поддерживает вложенные списки)
В итоге схема markdown.hrc теперь делает все, что от нее было задумано получить, со следующими оговорками:
* Inline HTML should be valid XML.
* Opened spans are always colored.
* Blockquote contents is not parsed.
* List levels 4: only items are parsed.
* List levels 5+: all is colored as code.
* List levels: 4, 8, 12 spaces or 1, 2, 3 tabs.
Дальше будет в основном оптимизация и вылавливание ошибок, можно начинать жаловаться на них.