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.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.
Дальше будет в основном оптимизация и вылавливание ошибок, можно начинать жаловаться на них.
- 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.8 - markdown.hrc, nested lists
* Fixed exotic cases of stoppers in nested lists.
* Used different regions for link text and marks.
v0.0.22.8 - markdown.hrc, nested lists
* Fixed exotic cases of stoppers in nested lists.
* Used different regions for link text and marks.
- NightRoman
- Posts: 6225
- Joined: Fri 18 Aug, 2006 13:52
- Location: Cambridge, UK
- Has thanked: 42 times
- Been thanked: 62 times
- Contact:
Re: HelpDown — конвертер md -> htm -> hlf
Проект теперь называется HelpDown и включен в исходники FarNet. Сборки выкладываются вместе с остальными сборками FarNet тут:
http://code.google.com/p/farnet/downloads/list
http://code.google.com/p/farnet/downloads/list
- NightRoman
- Posts: 6225
- Joined: Fri 18 Aug, 2006 13:52
- Location: Cambridge, UK
- Has thanked: 42 times
- Been thanked: 62 times
- Contact:
Re: HelpDown — конвертер md -> htm -> hlf
Следующий этап развития проекта.
Far 3.0.3831 поддерживает горизонтальные разделительные линии в файлах помощи (Mantis#0002619). Поддержка этого добавлена и в HtmlToFarHelp. Удалена лишняя теперь опция CenterRule.
Приложения распространяются не через Google Code downloads, а как два NuGet пакета:
https://www.nuget.org/packages/MarkdownToHtml
https://www.nuget.org/packages/HtmlToFarHelp
Разделение сделано, так как MarkdownToHtml имеет применение сам по себе, не обязательно в связке с HtmlToFarHelp для генерации файлов помощи.
Far 3.0.3831 поддерживает горизонтальные разделительные линии в файлах помощи (Mantis#0002619). Поддержка этого добавлена и в HtmlToFarHelp. Удалена лишняя теперь опция CenterRule.
Приложения распространяются не через Google Code downloads, а как два NuGet пакета:
https://www.nuget.org/packages/MarkdownToHtml
https://www.nuget.org/packages/HtmlToFarHelp
Разделение сделано, так как MarkdownToHtml имеет применение сам по себе, не обязательно в связке с HtmlToFarHelp для генерации файлов помощи.
- NightRoman
- Posts: 6225
- Joined: Fri 18 Aug, 2006 13:52
- Location: Cambridge, UK
- Has thanked: 42 times
- Been thanked: 62 times
- Contact:
Re: HelpDown — конвертер md -> htm -> hlf
HtmlToFarHelp Release Notes
v1.0.2
Added missing HLF option PluginContents. Without it help files are not shown in the plugin help list ([F1] [ShiftF2]).
v1.0.2
Added missing HLF option PluginContents. Without it help files are not shown in the plugin help list ([F1] [ShiftF2]).
- NightRoman
- Posts: 6225
- Joined: Fri 18 Aug, 2006 13:52
- Location: Cambridge, UK
- Has thanked: 42 times
- Been thanked: 62 times
- Contact:
Re: HelpDown — конвертер md -> htm -> hlf
HtmlToFarHelp v1.0.3, MarkdownToHtml v1.0.2
Исправлены смешанные окончания строк в обоих приложениях. Приложение HtmlToFarHelp на выходе должно давать \r\n, а MarkdownToHtml - \n (потому что внутренний конвертер использует \n, и это не настраивается, кажется).
Исправлены смешанные окончания строк в обоих приложениях. Приложение HtmlToFarHelp на выходе должно давать \r\n, а MarkdownToHtml - \n (потому что внутренний конвертер использует \n, и это не настраивается, кажется).
- 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
Да. MarkdownToHtml основан на MarkdownDeep, который вроде перестал использоваться.John Doe wrote: Wed 08 Nov, 2017 12:30 Правильно ли я понимаю, что сейчас вместо MarkdownToHtml рекомендуется pandoc?
Я проводил сравнительные тесты, pandoc показал себя ничуть не хуже (а, в сущности, гораздо лучше).
Только одно НО - https://github.com/jgm/pandoc/issues/2617
Используйте pandoc. Если если проблемы, пишите, будет полезно и знать, и подумать.
Но MarkdownToHtml тоже еще поживет, прямо сейчас не выкидываю.
- 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
Что это значит?NightRoman wrote: Wed 08 Nov, 2017 13:46Да. MarkdownToHtml основан на MarkdownDeep, который вроде перестал использоваться.
pandoc интересен тем, что поддерживает разные типы mardown, плюс ещё кучу всего.
(Интересно, сойдёт ли Word docx как исходник hlf.)
Last edited by John Doe on Wed 08 Nov, 2017 15:07, 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
Я имел в виду MarkdownDeep перестал развиваться.
А pandoc - классная вещь в любом случае, да.
> Интересно, сойдёт ли Word docx как исходник hlf.
Сомневаюсь...
А pandoc - классная вещь в любом случае, да.
> Интересно, сойдёт ли Word docx как исходник 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
Жаль нет конвертера в bbcode.
А что именно лучше?NightRoman wrote: Wed 08 Nov, 2017 13:46Я проводил сравнительные тесты, pandoc показал себя ничуть не хуже (а, в сущности, гораздо лучше).
Demo.text использует все его возможности, или что-то можно удобнее сделать?
- 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/toptensoftware/markd ... /issues/12
Вроде пофиксили, но пакет так и не обновили.
Но вообще, тестировал давно. И подзабыл детали (но где-то есть) и пандок с тех пор мог поменяться.
Когда-нибудь вернусь к этим вопросам.
Не падает на некоторых конструкциях
Вроде пофиксили, но пакет так и не обновили.
Но вообще, тестировал давно. И подзабыл детали (но где-то есть) и пандок с тех пор мог поменяться.
Когда-нибудь вернусь к этим вопросам.
- 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
Проблемы понятно, а принимаются ли пожелания по HtmlToFarHelp?NightRoman wrote: Wed 08 Nov, 2017 13:46Если если проблемы, пишите, будет полезно и знать, и подумать.
Есть не праздный интерес, касающийся перевода Энциклопедии.
- 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
В консоли (по крайней мере мне) место дорого, поэтому важно разместить информацию компактно.
Для этого сейчас не хватает средств: абзацы всегда предваряются пустой строкой.
Пожелание: добавить опцию конвертации (<!--HLF:), позволяющую не разделять пустой строкой абзацы (или в целом блочные элементы).
Менее существенные пожелания:
И сейчас HtmlToFarHelp.exe не вполне поддерживает такие вещи:
Для больших проектов может быть неудобно собирать всё в один html файл.
Для Энциклопедии это например неприемлемо.
Надо подумать о какой-то пре/пост-обработке.
Для этого сейчас не хватает средств: абзацы всегда предваряются пустой строкой.
Пожелание: добавить опцию конвертации (<!--HLF:), позволяющую не разделять пустой строкой абзацы (или в целом блочные элементы).
Менее существенные пожелания:
И сейчас HtmlToFarHelp.exe не вполне поддерживает такие вещи:
- Тэг <br/> воспринимается буквально, и дальнейший текст (чаще всего) начинается с нулевой позиции новой строки, что приводит к результату прямо противоположному ожидаемому.
Хочется чтобы после <br/> сохранялся текущий отступ.
https://github.com/nightroman/FarNet/issues/44 - Если в definition list текст не заключён в <p>, то в hlf он форматируется неверно
Update это уже исправлено - Не поддерживаются такие линки:
- Есть ещё ряд конструкций, которые могут встретиться в html, а в hlf не нужны. Здорово было бы их просто пропускать.
Для больших проектов может быть неудобно собирать всё в один html файл.
Для Энциклопедии это например неприемлемо.
Надо подумать о какой-то пре/пост-обработке.
- 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
Принято к сведению. Надо подумать, что стоит или нет. Прямо сейчас не получится, работаю над другими проектами.
В какой схеме колорера недочет? В markdown? Тогда подробнее (я уж забыл немного, что там и как).
В какой схеме колорера недочет? В markdown? Тогда подробнее (я уж забыл немного, что там и как).