Реализован следующий сценарий. Документация (хелп к плагину) пишется в markdown. Затем markdown конвертируется в HTML с помощью MarkdownToHtml. Полученный файл конвертируется в HLF с помощью HtmlToFarHelp. Промежуточный HTML либо удаляется, либо тоже включается в поставку вместе с HLF для удобного просмотра хелпа в браузере.
Значит hlf получается из html?
Выходит что если интегрировать такой конвертер в фар, то можно было бы напрямую использовать html-справку?
Версия 0.0.1 намекает на продолжение развития. Что планируется сделать в первую очередь?
Re: Встроенная справка в удобном формате
Posted: Thu 23 Feb, 2012 11:33
by NightRoman
John Doe wrote:Значит hlf получается из html?
Да. Любители HTML могут прямо в нем и ваять (правда, сомневаюсь, что их много найдется). Но HTML очень простой (пока), легко что-то заюзать, что не поддерживается. В случае с исходником в маркдауне шансы таких ошибок сильно уменьшаются. Но тоже есть не поддерживаемые фичи.
John Doe wrote:Выходит что если интегрировать такой конвертер в фар, то можно было бы напрямую использовать html-справку?
Пас. Ноу комментс.
John Doe wrote:Версия 0.0.1 намекает на продолжение развития. Что планируется сделать в первую очередь?
Ну конечно будет развитие, я ж на это уже перелез Что сделать планируется? Сначала хочу схему колорера для маркдауна привести в порядок и туда же добавить. Потом можно будет подумать о таблицах. Потом о много-уровневых списках (пока только один уровень). Увидим.
Re: Встроенная справка в удобном формате
Posted: Thu 23 Feb, 2012 16:49
by John Doe
В hlf бросились в глаза некоторые вещи
1. Нестандартный wrap-маркер (вначале не мог взять в толк что это такое :-)
2. Нестандартный выступ абзаца (вместо отступа)
Маркер ерунда, а насчёт выступа - хотелось бы видить настройки элементов (таблицы, заголовки, абзацы, списки, код, ...).
На полноценные стили это не потянет, но отступы (со разных сторон) и подсветку можно понастраивать.
Re: Встроенная справка в удобном формате
Posted: Thu 23 Feb, 2012 17:16
by NightRoman
John Doe wrote:1. Нестандартный wrap-маркер (вначале не мог взять в толк что это такое
А мне такой нравится А если серьезно, какая разница? Вся суть в том, чтобы вообще в HLF не заглядывать. Неважно что там будет внутри, важно, как выглядит при F1.
John Doe wrote:2. Нестандартный выступ абзаца (вместо отступа)
Это не понял. Что это, как надо, как не надо?
John Doe wrote:хотелось бы видить настройки элементов (таблицы, заголовки, абзацы, списки, код, ...).
На полноценные стили это не потянет, но отступы (со разных сторон) и подсветку можно понастраивать.
Предлагайте параметры и объясняйте, на что и как они должны влиять в выходном HLF.
Но вообще буду это все критично оценивать. Идея, имхо, чтобы наоборот особо стилей не было и все хелпы выглядели под одну гребенку, а не как кому захочется.
Re: Встроенная справка в удобном формате
Posted: Thu 23 Feb, 2012 17:36
by John Doe
NightRoman wrote:
John Doe wrote:2. Нестандартный выступ абзаца (вместо отступа)
Это не понял. Что это, как надо, как не надо?
Сравните ваш выступ со стандартным фаровским отступом:
This file is an example of "FarHelpDown" markdown designed for conversion to
Far help via HTML. It contains examples of supported markdown features and
special cases covered by tests.
This file is an example of "FarHelpDown" markdown designed for conversion
to Far help via HTML. It contains examples of supported markdown features
and special cases covered by tests.
NightRoman wrote:Идея, имхо, чтобы наоборот особо стилей не было и все хелпы выглядели под одну гребенку, а не как кому захочется.
Согласен на 100%
Но дело в том, что даже в hlf фара нет единого порядка.
Поэтому этот порядок ещё предстоит выработать, а для этого должна быть возможность как-то крутить настройки.
NightRoman wrote:Предлагайте параметры и объясняйте, на что и как они должны влиять в выходном HLF.
Надо взять список всех сущностей как их понимает markdown, и подумать в отображении каких из них есть варианты.
Например:
Заголовок: подсветка (кстати 2 вида) | отступ | центрирование Параграф: отступ абзац | отступ текст Список (n-й уровень): наличие и символ маркера | отступ (отдельно перед маркером и перед текстом) | подсветка маркера Код (блок): отступ | подсветка Код (текст): подсветка
Следует разделить Код на примеры, сочетания клавиш, и т.п. Таблица: отступ (отдельно каждой колонки) | выравнивание ( каждой )
Думаю 2х колонок более чем достаточно
Re: Встроенная справка в удобном формате
Posted: Thu 23 Feb, 2012 17:36
by NightRoman
А, про отступы абзаца вроде понял. Сделать как в Фаре, 4 пробела вначале? Наверное, это можно. Можно считать, что Фар-хелп это стандарт, под который и нужно подбить конвертацию (даже хоть мне и не совсем нравится, но я за единообразие).
Re: Встроенная справка в удобном формате
Posted: Thu 23 Feb, 2012 17:41
by John Doe
Да, но этот стандарт не писан, и поэтому не вполне единообразен сам по себе.
Но ваш инструмент способен эту ситуацию улучшить :-)
Re: Встроенная справка в удобном формате
Posted: Thu 23 Feb, 2012 17:52
by NightRoman
Предложения разумные, спасибо. Буду иметь в виду и по возможности внедрять.
(Хоть и почти хак, но можно иметь в виду и *инструкции* в маркдауне в виде HTML комментов особого вида. Это на далекое будущее. Сейчас - нет. Но иметь в виду можно при дизайне всего остального).
Re: Встроенная справка в удобном формате
Posted: Thu 23 Feb, 2012 18:01
by John Doe
Возможно для задания параметров стоит использовать синтаксис css (упрощённо).
Во-первых это позволит не изобретать велосипед.
Во-вторых для html всё равно требуется css, для hlf просто значения будут другими.
Re: Встроенная справка в удобном формате
Posted: Thu 23 Feb, 2012 18:08
by NightRoman
Но если еще подумать, то другим критерием является то, как это выглядит в броузере. То, как сделано сейчас, у меня почти одинаково выглядит и в броузере, и в Фар-хелпе (кроме того, что в Фаре в принципе нельзя пока). Тем более, у меня цвета хелпа перенастроены на белую схему, оригинальную Фара я не могу читать нормально, не различаю текст. Так что подбивал стиль я скорей под браузер. И в этом тоже есть своя логика, ибо один и тот же хелп теперь есть и в HTML и в HLF. Желательно, чтобы они были похожи по виду.
---
css.. что-то пока я не хочу в это дело. Всякие таблицы и вложенные списки пока важней, чем продвинутые стили. Но почему бы и нет, со временем.
Re: Встроенная справка в удобном формате
Posted: Thu 23 Feb, 2012 18:27
by NightRoman
Еще раз сличил, как выглядит в браузере и в Фаре. Можно кой-что подкрутить, чтобы было более похоже, вообще-то. Отступы отличаются. Пожалуй, кой-какие параметры для отступов добавлю, можно будет выбирать (во всяком случае, пока, чтоб можно было генерить и сравнивать разные варианты на "красивость").
Re: Встроенная справка в удобном формате
Posted: Fri 24 Feb, 2012 07:23
by NightRoman
Добавил параметры TabList=3, TabPara=1. Дефолтные значения выбраны, чтобы получить вид Фар-хелпа более похожий на то, что в получается в броузере (в IE без стилей, во всяком случае).
Re: Встроенная справка в удобном формате
Posted: Sat 25 Feb, 2012 09:55
by NightRoman
https://github.com/nightroman/FarHelpDown/downloads
Большое дело, привел в порядок и добавил в пакет Markdown.hrc для Colorer. Без схемы маркдауна вся эта технология была бы несовершенна. Схема на удивление простая и приличная получилась, лучше, чем это планировалось. Совершенство пока не достигнуто, схему местами можно сбить с толку хитрыми конструкциями, однако, на практике эти случаи будут редки при использовании "нормального стиля", так сказать.
Re: Встроенная справка в удобном формате
Posted: Sat 25 Feb, 2012 10:23
by NightRoman
В PowerShellFar 5.0.15 добавлен скрипт, который позволяет открывать маркдаун из редактора Фара прямо на текущем топике - либо как HLF в окне справки Фара, либо как HTML в дефолтном броузере. Очень полезно при работе с большими текстами, чтобы не искать нужное для просмотра место после открытия.