HelpDown — конвертер md -> htm -> hlf
- NightRoman
- Posts: 6184
- Joined: Fri 18 Aug, 2006 13:52
- Location: Cambridge, UK
- Has thanked: 32 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 для удобного просмотра хелпа в браузере.
Предыстория в теме Встроенная справка в удобном формате
- John Doe
- Бюрократ
- Posts: 13855
- Joined: Wed 27 Apr, 2005 20:42
- Has thanked: 73 times
- Been thanked: 428 times
- Contact:
Re: Встроенная справка в удобном формате
Неплохо!
Выходит что если интегрировать такой конвертер в фар, то можно было бы напрямую использовать html-справку?
Версия 0.0.1 намекает на продолжение развития. Что планируется сделать в первую очередь?
Значит hlf получается из html?NightRoman wrote:md -> htm -> hlf
Выходит что если интегрировать такой конвертер в фар, то можно было бы напрямую использовать html-справку?
Версия 0.0.1 намекает на продолжение развития. Что планируется сделать в первую очередь?
- NightRoman
- Posts: 6184
- Joined: Fri 18 Aug, 2006 13:52
- Location: Cambridge, UK
- Has thanked: 32 times
- Been thanked: 62 times
- Contact:
Re: Встроенная справка в удобном формате
Да. Любители HTML могут прямо в нем и ваять (правда, сомневаюсь, что их много найдется). Но HTML очень простой (пока), легко что-то заюзать, что не поддерживается. В случае с исходником в маркдауне шансы таких ошибок сильно уменьшаются. Но тоже есть не поддерживаемые фичи.John Doe wrote:Значит hlf получается из html?
Пас. Ноу комментс.John Doe wrote:Выходит что если интегрировать такой конвертер в фар, то можно было бы напрямую использовать html-справку?
Ну конечно будет развитие, я ж на это уже перелез Что сделать планируется? Сначала хочу схему колорера для маркдауна привести в порядок и туда же добавить. Потом можно будет подумать о таблицах. Потом о много-уровневых списках (пока только один уровень). Увидим.John Doe wrote:Версия 0.0.1 намекает на продолжение развития. Что планируется сделать в первую очередь?
- John Doe
- Бюрократ
- Posts: 13855
- Joined: Wed 27 Apr, 2005 20:42
- Has thanked: 73 times
- Been thanked: 428 times
- Contact:
Re: Встроенная справка в удобном формате
В hlf бросились в глаза некоторые вещи
1. Нестандартный wrap-маркер (вначале не мог взять в толк что это такое :-)
2. Нестандартный выступ абзаца (вместо отступа)
Маркер ерунда, а насчёт выступа - хотелось бы видить настройки элементов (таблицы, заголовки, абзацы, списки, код, ...).
На полноценные стили это не потянет, но отступы (со разных сторон) и подсветку можно понастраивать.
1. Нестандартный wrap-маркер (вначале не мог взять в толк что это такое :-)
2. Нестандартный выступ абзаца (вместо отступа)
Маркер ерунда, а насчёт выступа - хотелось бы видить настройки элементов (таблицы, заголовки, абзацы, списки, код, ...).
На полноценные стили это не потянет, но отступы (со разных сторон) и подсветку можно понастраивать.
- NightRoman
- Posts: 6184
- Joined: Fri 18 Aug, 2006 13:52
- Location: Cambridge, UK
- Has thanked: 32 times
- Been thanked: 62 times
- Contact:
Re: Встроенная справка в удобном формате
А мне такой нравится А если серьезно, какая разница? Вся суть в том, чтобы вообще в HLF не заглядывать. Неважно что там будет внутри, важно, как выглядит при F1.John Doe wrote:1. Нестандартный wrap-маркер (вначале не мог взять в толк что это такое
Это не понял. Что это, как надо, как не надо?John Doe wrote:2. Нестандартный выступ абзаца (вместо отступа)
Предлагайте параметры и объясняйте, на что и как они должны влиять в выходном HLF.John Doe wrote:хотелось бы видить настройки элементов (таблицы, заголовки, абзацы, списки, код, ...).
На полноценные стили это не потянет, но отступы (со разных сторон) и подсветку можно понастраивать.
Но вообще буду это все критично оценивать. Идея, имхо, чтобы наоборот особо стилей не было и все хелпы выглядели под одну гребенку, а не как кому захочется.
- John Doe
- Бюрократ
- Posts: 13855
- Joined: Wed 27 Apr, 2005 20:42
- Has thanked: 73 times
- Been thanked: 428 times
- Contact:
Re: Встроенная справка в удобном формате
Сравните ваш выступ со стандартным фаровским отступом:NightRoman wrote:Это не понял. Что это, как надо, как не надо?John Doe wrote:2. Нестандартный выступ абзаца (вместо отступа)
Согласен на 100%NightRoman wrote:Идея, имхо, чтобы наоборот особо стилей не было и все хелпы выглядели под одну гребенку, а не как кому захочется.
Но дело в том, что даже в hlf фара нет единого порядка.
Поэтому этот порядок ещё предстоит выработать, а для этого должна быть возможность как-то крутить настройки.
Надо взять список всех сущностей как их понимает markdown, и подумать в отображении каких из них есть варианты.NightRoman wrote:Предлагайте параметры и объясняйте, на что и как они должны влиять в выходном HLF.
Например:
- Заголовок: подсветка (кстати 2 вида) | отступ | центрирование
Параграф: отступ абзац | отступ текст
Список (n-й уровень): наличие и символ маркера | отступ (отдельно перед маркером и перед текстом) | подсветка маркера
Код (блок): отступ | подсветка
Код (текст): подсветка
Следует разделить Код на примеры, сочетания клавиш, и т.п.
Таблица: отступ (отдельно каждой колонки) | выравнивание ( каждой )
Думаю 2х колонок более чем достаточно
- NightRoman
- Posts: 6184
- Joined: Fri 18 Aug, 2006 13:52
- Location: Cambridge, UK
- Has thanked: 32 times
- Been thanked: 62 times
- Contact:
Re: Встроенная справка в удобном формате
А, про отступы абзаца вроде понял. Сделать как в Фаре, 4 пробела вначале? Наверное, это можно. Можно считать, что Фар-хелп это стандарт, под который и нужно подбить конвертацию (даже хоть мне и не совсем нравится, но я за единообразие).
- John Doe
- Бюрократ
- Posts: 13855
- Joined: Wed 27 Apr, 2005 20:42
- Has thanked: 73 times
- Been thanked: 428 times
- Contact:
Re: Встроенная справка в удобном формате
Да, но этот стандарт не писан, и поэтому не вполне единообразен сам по себе.
Но ваш инструмент способен эту ситуацию улучшить :-)
Но ваш инструмент способен эту ситуацию улучшить :-)
- NightRoman
- Posts: 6184
- Joined: Fri 18 Aug, 2006 13:52
- Location: Cambridge, UK
- Has thanked: 32 times
- Been thanked: 62 times
- Contact:
Re: Встроенная справка в удобном формате
Предложения разумные, спасибо. Буду иметь в виду и по возможности внедрять.
(Хоть и почти хак, но можно иметь в виду и *инструкции* в маркдауне в виде HTML комментов особого вида. Это на далекое будущее. Сейчас - нет. Но иметь в виду можно при дизайне всего остального).
(Хоть и почти хак, но можно иметь в виду и *инструкции* в маркдауне в виде HTML комментов особого вида. Это на далекое будущее. Сейчас - нет. Но иметь в виду можно при дизайне всего остального).
- John Doe
- Бюрократ
- Posts: 13855
- Joined: Wed 27 Apr, 2005 20:42
- Has thanked: 73 times
- Been thanked: 428 times
- Contact:
Re: Встроенная справка в удобном формате
Возможно для задания параметров стоит использовать синтаксис css (упрощённо).
Во-первых это позволит не изобретать велосипед.
Во-вторых для html всё равно требуется css, для hlf просто значения будут другими.
Во-первых это позволит не изобретать велосипед.
Во-вторых для html всё равно требуется css, для hlf просто значения будут другими.
- NightRoman
- Posts: 6184
- Joined: Fri 18 Aug, 2006 13:52
- Location: Cambridge, UK
- Has thanked: 32 times
- Been thanked: 62 times
- Contact:
Re: Встроенная справка в удобном формате
Но если еще подумать, то другим критерием является то, как это выглядит в броузере. То, как сделано сейчас, у меня почти одинаково выглядит и в броузере, и в Фар-хелпе (кроме того, что в Фаре в принципе нельзя пока). Тем более, у меня цвета хелпа перенастроены на белую схему, оригинальную Фара я не могу читать нормально, не различаю текст. Так что подбивал стиль я скорей под браузер. И в этом тоже есть своя логика, ибо один и тот же хелп теперь есть и в HTML и в HLF. Желательно, чтобы они были похожи по виду.
---
css.. что-то пока я не хочу в это дело. Всякие таблицы и вложенные списки пока важней, чем продвинутые стили. Но почему бы и нет, со временем.
---
css.. что-то пока я не хочу в это дело. Всякие таблицы и вложенные списки пока важней, чем продвинутые стили. Но почему бы и нет, со временем.
Last edited by NightRoman on Sat 25 Feb, 2012 11:05, edited 1 time in total.
- NightRoman
- Posts: 6184
- Joined: Fri 18 Aug, 2006 13:52
- Location: Cambridge, UK
- Has thanked: 32 times
- Been thanked: 62 times
- Contact:
Re: Встроенная справка в удобном формате
Еще раз сличил, как выглядит в браузере и в Фаре. Можно кой-что подкрутить, чтобы было более похоже, вообще-то. Отступы отличаются. Пожалуй, кой-какие параметры для отступов добавлю, можно будет выбирать (во всяком случае, пока, чтоб можно было генерить и сравнивать разные варианты на "красивость").
- NightRoman
- Posts: 6184
- Joined: Fri 18 Aug, 2006 13:52
- Location: Cambridge, UK
- Has thanked: 32 times
- Been thanked: 62 times
- Contact:
Re: Встроенная справка в удобном формате
Добавил параметры TabList=3, TabPara=1. Дефолтные значения выбраны, чтобы получить вид Фар-хелпа более похожий на то, что в получается в броузере (в IE без стилей, во всяком случае).
- NightRoman
- Posts: 6184
- Joined: Fri 18 Aug, 2006 13:52
- Location: Cambridge, UK
- Has thanked: 32 times
- Been thanked: 62 times
- Contact:
Re: Встроенная справка в удобном формате
https://github.com/nightroman/FarHelpDown/downloads
Большое дело, привел в порядок и добавил в пакет Markdown.hrc для Colorer. Без схемы маркдауна вся эта технология была бы несовершенна. Схема на удивление простая и приличная получилась, лучше, чем это планировалось. Совершенство пока не достигнуто, схему местами можно сбить с толку хитрыми конструкциями, однако, на практике эти случаи будут редки при использовании "нормального стиля", так сказать.
Большое дело, привел в порядок и добавил в пакет Markdown.hrc для Colorer. Без схемы маркдауна вся эта технология была бы несовершенна. Схема на удивление простая и приличная получилась, лучше, чем это планировалось. Совершенство пока не достигнуто, схему местами можно сбить с толку хитрыми конструкциями, однако, на практике эти случаи будут редки при использовании "нормального стиля", так сказать.
- NightRoman
- Posts: 6184
- Joined: Fri 18 Aug, 2006 13:52
- Location: Cambridge, UK
- Has thanked: 32 times
- Been thanked: 62 times
- Contact:
Re: Встроенная справка в удобном формате
В PowerShellFar 5.0.15 добавлен скрипт, который позволяет открывать маркдаун из редактора Фара прямо на текущем топике - либо как HLF в окне справки Фара, либо как HTML в дефолтном броузере. Очень полезно при работе с большими текстами, чтобы не искать нужное для просмотра место после открытия.