HelpDown — конвертер md -> htm -> hlf

Хотите говорить о Far и не знаете, куда обратиться?
User avatar
NightRoman
Posts: 5911
Joined: Fri 18 Aug, 2006 13:52
Location: Cambridge, UK
Has thanked: 10 times
Been thanked: 11 times
Contact:

HelpDown — конвертер md -> htm -> hlf

Post by NightRoman » Wed 22 Feb, 2012 20:35

Проект называется HelpDown и включен в исходники FarNet.
Приложения распространяются как два NuGet пакета:

https://www.nuget.org/packages/MarkdownToHtml
https://www.nuget.org/packages/HtmlToFarHelp

Реализован следующий сценарий. Документация (хелп к плагину) пишется в markdown. Затем markdown конвертируется в HTML с помощью MarkdownToHtml. Полученный файл конвертируется в HLF с помощью HtmlToFarHelp. Промежуточный HTML либо удаляется, либо тоже включается в поставку вместе с HLF для удобного просмотра хелпа в браузере.

Предыстория в теме Встроенная справка в удобном формате

User avatar
John Doe
Бюрократ
Posts: 12236
Joined: Wed 27 Apr, 2005 20:42
Has thanked: 32 times
Been thanked: 162 times

Re: Встроенная справка в удобном формате

Post by John Doe » Thu 23 Feb, 2012 11:02

Неплохо!
NightRoman wrote:md -> htm -> hlf
Значит hlf получается из html?
Выходит что если интегрировать такой конвертер в фар, то можно было бы напрямую использовать html-справку?

Версия 0.0.1 намекает на продолжение развития. Что планируется сделать в первую очередь?

User avatar
NightRoman
Posts: 5911
Joined: Fri 18 Aug, 2006 13:52
Location: Cambridge, UK
Has thanked: 10 times
Been thanked: 11 times
Contact:

Re: Встроенная справка в удобном формате

Post by NightRoman » Thu 23 Feb, 2012 11:33

John Doe wrote:Значит hlf получается из html?
Да. Любители HTML могут прямо в нем и ваять (правда, сомневаюсь, что их много найдется). Но HTML очень простой (пока), легко что-то заюзать, что не поддерживается. В случае с исходником в маркдауне шансы таких ошибок сильно уменьшаются. Но тоже есть не поддерживаемые фичи.
John Doe wrote:Выходит что если интегрировать такой конвертер в фар, то можно было бы напрямую использовать html-справку?
Пас. Ноу комментс.
John Doe wrote:Версия 0.0.1 намекает на продолжение развития. Что планируется сделать в первую очередь?
Ну конечно будет развитие, я ж на это уже перелез :) Что сделать планируется? Сначала хочу схему колорера для маркдауна привести в порядок и туда же добавить. Потом можно будет подумать о таблицах. Потом о много-уровневых списках (пока только один уровень). Увидим.

User avatar
John Doe
Бюрократ
Posts: 12236
Joined: Wed 27 Apr, 2005 20:42
Has thanked: 32 times
Been thanked: 162 times

Re: Встроенная справка в удобном формате

Post by John Doe » Thu 23 Feb, 2012 16:49

В hlf бросились в глаза некоторые вещи
1. Нестандартный wrap-маркер (вначале не мог взять в толк что это такое :-)
2. Нестандартный выступ абзаца (вместо отступа)
Маркер ерунда, а насчёт выступа - хотелось бы видить настройки элементов (таблицы, заголовки, абзацы, списки, код, ...).
На полноценные стили это не потянет, но отступы (со разных сторон) и подсветку можно понастраивать.

User avatar
NightRoman
Posts: 5911
Joined: Fri 18 Aug, 2006 13:52
Location: Cambridge, UK
Has thanked: 10 times
Been thanked: 11 times
Contact:

Re: Встроенная справка в удобном формате

Post by NightRoman » Thu 23 Feb, 2012 17:16

John Doe wrote:1. Нестандартный wrap-маркер (вначале не мог взять в толк что это такое :-)
А мне такой нравится :) А если серьезно, какая разница? Вся суть в том, чтобы вообще в HLF не заглядывать. Неважно что там будет внутри, важно, как выглядит при F1.
John Doe wrote:2. Нестандартный выступ абзаца (вместо отступа)
Это не понял. Что это, как надо, как не надо?
John Doe wrote:хотелось бы видить настройки элементов (таблицы, заголовки, абзацы, списки, код, ...).
На полноценные стили это не потянет, но отступы (со разных сторон) и подсветку можно понастраивать.
Предлагайте параметры и объясняйте, на что и как они должны влиять в выходном HLF.

Но вообще буду это все критично оценивать. Идея, имхо, чтобы наоборот особо стилей не было и все хелпы выглядели под одну гребенку, а не как кому захочется.

User avatar
John Doe
Бюрократ
Posts: 12236
Joined: Wed 27 Apr, 2005 20:42
Has thanked: 32 times
Been thanked: 162 times

Re: Встроенная справка в удобном формате

Post by John Doe » Thu 23 Feb, 2012 17:36

NightRoman wrote:
John Doe wrote:2. Нестандартный выступ абзаца (вместо отступа)
Это не понял. Что это, как надо, как не надо?
Сравните ваш выступ со стандартным фаровским отступом:
NightRoman wrote:Идея, имхо, чтобы наоборот особо стилей не было и все хелпы выглядели под одну гребенку, а не как кому захочется.
Согласен на 100%
Но дело в том, что даже в hlf фара нет единого порядка.
Поэтому этот порядок ещё предстоит выработать, а для этого должна быть возможность как-то крутить настройки.
NightRoman wrote:Предлагайте параметры и объясняйте, на что и как они должны влиять в выходном HLF.
Надо взять список всех сущностей как их понимает markdown, и подумать в отображении каких из них есть варианты.
Например:
  • Заголовок: подсветка (кстати 2 вида) | отступ | центрирование
    Параграф: отступ абзац | отступ текст
    Список (n-й уровень): наличие и символ маркера | отступ (отдельно перед маркером и перед текстом) | подсветка маркера
    Код (блок): отступ | подсветка
    Код (текст): подсветка
    Следует разделить Код на примеры, сочетания клавиш, и т.п.
    Таблица: отступ (отдельно каждой колонки) | выравнивание ( каждой )
    Думаю 2х колонок более чем достаточно

User avatar
NightRoman
Posts: 5911
Joined: Fri 18 Aug, 2006 13:52
Location: Cambridge, UK
Has thanked: 10 times
Been thanked: 11 times
Contact:

Re: Встроенная справка в удобном формате

Post by NightRoman » Thu 23 Feb, 2012 17:36

А, про отступы абзаца вроде понял. Сделать как в Фаре, 4 пробела вначале? Наверное, это можно. Можно считать, что Фар-хелп это стандарт, под который и нужно подбить конвертацию (даже хоть мне и не совсем нравится, но я за единообразие).

User avatar
John Doe
Бюрократ
Posts: 12236
Joined: Wed 27 Apr, 2005 20:42
Has thanked: 32 times
Been thanked: 162 times

Re: Встроенная справка в удобном формате

Post by John Doe » Thu 23 Feb, 2012 17:41

Да, но этот стандарт не писан, и поэтому не вполне единообразен сам по себе.
Но ваш инструмент способен эту ситуацию улучшить :-)

User avatar
NightRoman
Posts: 5911
Joined: Fri 18 Aug, 2006 13:52
Location: Cambridge, UK
Has thanked: 10 times
Been thanked: 11 times
Contact:

Re: Встроенная справка в удобном формате

Post by NightRoman » Thu 23 Feb, 2012 17:52

Предложения разумные, спасибо. Буду иметь в виду и по возможности внедрять.

(Хоть и почти хак, но можно иметь в виду и *инструкции* в маркдауне в виде HTML комментов особого вида. Это на далекое будущее. Сейчас - нет. Но иметь в виду можно при дизайне всего остального).

User avatar
John Doe
Бюрократ
Posts: 12236
Joined: Wed 27 Apr, 2005 20:42
Has thanked: 32 times
Been thanked: 162 times

Re: Встроенная справка в удобном формате

Post by John Doe » Thu 23 Feb, 2012 18:01

Возможно для задания параметров стоит использовать синтаксис css (упрощённо).
Во-первых это позволит не изобретать велосипед.
Во-вторых для html всё равно требуется css, для hlf просто значения будут другими.

User avatar
NightRoman
Posts: 5911
Joined: Fri 18 Aug, 2006 13:52
Location: Cambridge, UK
Has thanked: 10 times
Been thanked: 11 times
Contact:

Re: Встроенная справка в удобном формате

Post by NightRoman » Thu 23 Feb, 2012 18:08

Но если еще подумать, то другим критерием является то, как это выглядит в броузере. То, как сделано сейчас, у меня почти одинаково выглядит и в броузере, и в Фар-хелпе (кроме того, что в Фаре в принципе нельзя пока). Тем более, у меня цвета хелпа перенастроены на белую схему, оригинальную Фара я не могу читать нормально, не различаю текст. Так что подбивал стиль я скорей под браузер. И в этом тоже есть своя логика, ибо один и тот же хелп теперь есть и в HTML и в HLF. Желательно, чтобы они были похожи по виду.

---
css.. что-то пока я не хочу в это дело. Всякие таблицы и вложенные списки пока важней, чем продвинутые стили. Но почему бы и нет, со временем.
Last edited by NightRoman on Sat 25 Feb, 2012 11:05, edited 1 time in total.

User avatar
NightRoman
Posts: 5911
Joined: Fri 18 Aug, 2006 13:52
Location: Cambridge, UK
Has thanked: 10 times
Been thanked: 11 times
Contact:

Re: Встроенная справка в удобном формате

Post by NightRoman » Thu 23 Feb, 2012 18:27

Еще раз сличил, как выглядит в браузере и в Фаре. Можно кой-что подкрутить, чтобы было более похоже, вообще-то. Отступы отличаются. Пожалуй, кой-какие параметры для отступов добавлю, можно будет выбирать (во всяком случае, пока, чтоб можно было генерить и сравнивать разные варианты на "красивость").

User avatar
NightRoman
Posts: 5911
Joined: Fri 18 Aug, 2006 13:52
Location: Cambridge, UK
Has thanked: 10 times
Been thanked: 11 times
Contact:

Re: Встроенная справка в удобном формате

Post by NightRoman » Fri 24 Feb, 2012 07:23

Добавил параметры TabList=3, TabPara=1. Дефолтные значения выбраны, чтобы получить вид Фар-хелпа более похожий на то, что в получается в броузере (в IE без стилей, во всяком случае).

User avatar
NightRoman
Posts: 5911
Joined: Fri 18 Aug, 2006 13:52
Location: Cambridge, UK
Has thanked: 10 times
Been thanked: 11 times
Contact:

Re: Встроенная справка в удобном формате

Post by NightRoman » Sat 25 Feb, 2012 09:55

https://github.com/nightroman/FarHelpDown/downloads
Большое дело, привел в порядок и добавил в пакет Markdown.hrc для Colorer. Без схемы маркдауна вся эта технология была бы несовершенна. Схема на удивление простая и приличная получилась, лучше, чем это планировалось. Совершенство пока не достигнуто, схему местами можно сбить с толку хитрыми конструкциями, однако, на практике эти случаи будут редки при использовании "нормального стиля", так сказать.

User avatar
NightRoman
Posts: 5911
Joined: Fri 18 Aug, 2006 13:52
Location: Cambridge, UK
Has thanked: 10 times
Been thanked: 11 times
Contact:

Re: Встроенная справка в удобном формате

Post by NightRoman » Sat 25 Feb, 2012 10:23

В PowerShellFar 5.0.15 добавлен скрипт, который позволяет открывать маркдаун из редактора Фара прямо на текущем топике - либо как HLF в окне справки Фара, либо как HTML в дефолтном броузере. Очень полезно при работе с большими текстами, чтобы не искать нужное для просмотра место после открытия.

User avatar
NightRoman
Posts: 5911
Joined: Fri 18 Aug, 2006 13:52
Location: Cambridge, UK
Has thanked: 10 times
Been thanked: 11 times
Contact:

Re: Встроенная справка в удобном формате

Post by NightRoman » Mon 27 Feb, 2012 08:30

https://github.com/nightroman/FarHelpDown/downloads
v0.0.4
- Improved Markdown.hrc.
- Ordered lists are supported.
- Mixed bold + italic is supported.
- Renamed command keys Tab* to Indent*

Post Reply

Return to “Обсуждение Far Manager”