Что нового

Генерация HTML/CHM для WinAPIEx.au3

Yashied

Модератор
Команда форума
Глобальный модератор
Сообщения
5,379
Репутация
2,724
Друзья, нужна ваша помощь. Я хочу сделать небольшую справку для своей библиотеки WinAPIEx.au3. Она должна выглядеть наподобии оффициальной справки AutoIt (это то, когда вы нажимаете F1 в SciTE). Описания для всех функций находятся внутри библиотеки в стандартной шапке для каждой функции, например:

Код:
; #FUNCTION# ====================================================================================================================
; Name...........: _WinAPI_GradientFill
; Description....: Fills rectangle or triangle gradient.
; Syntax.........: _WinAPI_GradientFill ($hDC, $aVertex [, $iStart [, $iEnd [, $fRotate]]] )
; Parameters.....: $hDC     - Handle to the destination device context.
;                  $aVertex - The 2D array ([x1, y1, $rgb1], [x2, y2, $rgb2], ... [xN, yN, $rgbN]) that contains the necessary
;                             gradient vertices. Each vertex in this array contains the following parameters.
;
;                             x   - The x-coordinate, in logical units.
;                             y   - The y-coordinate, in logical units
;                             rgb - The color information at the point of x, y.
;
;                  $iStart  - The index of array to start filling at.
;                  $iEnd    - The index of array to stop filling at.
;                  $fRotate - Specifies whether fills a rectangle from left to right edge (horizontal gradient). $fRotate used
;                             only for the rectangular gradients, for the triangular gradients this parameter will be ignored,
;                             valid values:
;                  |TRUE    - Fills from left to right edge.
;                  |FALSE   - Fills from top to bottom edge. (Default)
; Return values..: Success  - 1.
;                  Failure  - 0 and sets the @error flag to non-zero.
; Author.........: Yashied
; Modified.......:
; Remarks........: If the number of vertices defined by using $iStart and $iEnd parameters is 2, _WinAPI_GradientFill() function
;                  fills a rectangle. If the number of vertices is 3, fills a triangle. For the rectangle, the vertices must
;                  specify its upper left and lower right corners. Note that $aVertex array may contain any number of vertices
;                  of the gradient, but only 2 or 3 vertices may be used at the same time from this array.
;                  Otherwise, the function is fails.
;
;                  _WinAPI_GradientFill() function can only fill the rectangle or triangle at one call. Use multiple calls this
;                  function to fill a complex gradients.
; Related........:
; Link...........: @@MsdnLink@@ GdiGradientFill
; Example........: Yes
; ===============================================================================================================================


В идеале нужен .au3 файл для генерации .html, но можно и .chm или .html файл(ы). То, что его можно сгенерировать автоматом, я уверен на 100%, но загвоздка в том, что я не работаю с Web, и понятия не имею как это все должно выглядеть, а на изучение всего этого катастрофически не хватает времени. В будующем, я думаю эту библиотеку присоединят к стандартной WinAPI библиотеке, а пока, наверное многие будут рады иметь под рукой удобный справочный файл для этой UDF, чтобы постоянно не лазить внутрь .au3 файла и искать нужную функцию.

Так что буду рад, если кто-нибудь, хорошо знающий HTML (и возможно регулярные выражения), поможет в этом деле. Естественно, ваше имя/ник обязательно будет (если конечно хотите) в справочном файле.

:smile:
 

CreatoR

Must AutoIt!
Команда форума
Администратор
Сообщения
8,671
Репутация
2,481
На Английском?

На счёт автоматической генерации, я где то на оф. форуме читал про это, кажется даже сам валинок (Valik) выкладывал скрипт для генераций справки из скриптов, но я могу ошибаться, может это что то другое было...

P.S
Я бы сам осилил только несложный формат в виде Html-страничек, где просто будет список функций как ссылки, каждая ссылка откроет страницу с описанием функций, если такой вариант подходит, могу попробовать.
 
Автор
Yashied

Yashied

Модератор
Команда форума
Глобальный модератор
Сообщения
5,379
Репутация
2,724
CreatoR сказал(а):

Пока на английском.

CreatoR сказал(а):
Я бы сам осилил только несложный формат в виде Html-страничек, где просто будет список функций как ссылки, каждая ссылка откроет страницу с описанием функций, если такой вариант подходит, могу попробовать.

Давай так, буду рад.

:smile:
 

Garrett

Модератор
Локальный модератор
Сообщения
3,999
Репутация
967
Yashied
Я уже этим давно занялся, правда, не афишировал, потому, как делаю по мере свободного времени. Собирался выложить на общественный суд, когда доделаю. Но раз вы сами завели разговор, то решился отметиться в теме. :smile:
Правда, я делаю на русском, так как английский мой очень плох. :-[ Ваши комментарии на английском, будут, конечно же, без изменений.

Весь материал справочный черпаю с форума в прекрасно оформленных вами топиках. :smile:

Если вы хотите сделать просто справку, именно по WinAPIEx, то я тоже готов вам помочь. Как я понимаю исходя из кода в первом топике, вы хотите именно в таком формате? Просто оформить всё в HTML. Так?
 

CreatoR

Must AutoIt!
Команда форума
Администратор
Сообщения
8,671
Репутация
2,481
Yashied
Принимай работу (в аттаче). Получилось сделать по аналогий с форматом оф. справки по AutoIt, работал с исходниками online справки :smile:.

* Могут быть ошибки, на прочность сильно не проверял.
* Использовался AutoIt 3.3.6.0.
* Проверялось на WinAPIEx 2.2.

Я только что осознал, что я просто обожаю заниматься подобными парсерами :laugh:, много нового узнаю для себя!


Добавлено:
Сообщение автоматически объединено:

Немного обновил. Теперь отображение списка функции почти(?) аналогично оригиналу.
 
Автор
Yashied

Yashied

Модератор
Команда форума
Глобальный модератор
Сообщения
5,379
Репутация
2,724
CreatoR, это просто супер! .chm, я думаю, сгенерю из этого сам, благо программ для этого полно. Правда есть несколько багов и пожеланий... Позже проверю более внимательно, а пока вот:

  • "Return Value" затисалась в параметры...
  • Можно сделать шрифт не такой мелкий?
  • Я еще думаю добавить туда примеры... Можешь подправить код для генерации примеров после слова "Example"? Я подправлю описания, в строке "Example........: Yes" вместо "Yes" будет стоять путь к .au3 файлу с примером (в текущей папке).
  • И еще, можно убрать переносы строк при генерации .html, а то не очень красиво выгдядит.

А в целом просто супер!

:beer:


Добавлено:
Сообщение автоматически объединено:

Ну вот, пока писал, некоторый замечания стали неактуальны.


Добавлено:
Сообщение автоматически объединено:

Еще можно сделать как-нибудь покрасивее "|TRUE" и "|FALSE", см. например _WinAPI_AlphaBlend().


Добавлено:
Сообщение автоматически объединено:

Я еще думаю добавить туда примеры... Можешь подправить код для генерации примеров после слова "Example"? Я подправлю описания, в строке "Example........: Yes" вместо "Yes" будет стоять путь к .au3 файлу с примером (в текущей папке).

Лучше пусть "цепляет" одноименный (что и функция) файл в этой же папке. Я имею ввиду не открывать файл в SciTE (хотя это тоже прикольно), а включить сам текст примера непосредственно в .html. У тебя, я видел, даже была программа для раскраски AutoIt кода (ну можно и без раскраки).

:whistle:
 

CreatoR

Must AutoIt!
Команда форума
Администратор
Сообщения
8,671
Репутация
2,481
Yashied [?]
"Return Value" затисалась в параметры...
Fixed...


подправлю описания, в строке "Example........: Yes" вместо "Yes" будет стоять путь к .au3 файлу с примером (в текущей папке).
Добавил поддержку распознавания путей, если там не Yes а путь к файлу (существующему), то пример будет читаться с него.


можно убрать переносы строк при генерации .html, а то не очень красиво выгдядит.
Поточнее можно, где именно?


можно сделать как-нибудь покрасивее "|TRUE" и "|FALSE", см. например _WinAPI_AlphaBlend().
Ну так записано в самом заголовке. А что нужно с этим сделать?


включить сам текст примера непосредственно в .html
Так он так и включается, или я что-то не понял?


У тебя, я видел, даже была программа для раскраски AutoIt кода
Не, это геморно, лучше подключить Geshi, тот что у нас на форуме, подсветка будет такая же (и унаследует теже глюки) :smile:
 

gregaz

AutoIT Гуру
Сообщения
1,166
Репутация
299
Yashied [?]
CreatoR, это просто супер!

Отличная идея и классное ее воплощение :ok:
По отдельным примерам лазить было конечно тяжко.
В принципе теперь можно сделать какой-то путеводитель по отдельным функциям.

Наверное для этого достаточно оперировать файлами Index.htm ?

А можно добавить кнопочку : Open this Script , а может быть Run Script ? (Аппетит приходит ...) Хотя это наверное уже на уровне конвертирования


Добавлено:
Сообщение автоматически объединено:

Yashied [?]
.chm, я думаю, сгенерю из этого сам, благо программ для этого полно.

А какая сейчас наиболее совершенная.
Пользовался раньше некоторыми (давно правда ) , но тогда не нашел однозначно выполяющих Конвертирование - Обратное конвертирование ?
 

Garrett

Модератор
Локальный модератор
Сообщения
3,999
Репутация
967
CreatoR парсер замечательный! :thumbs_up:
Как говорится - дело мастера боится!
:ok:
 
Автор
Yashied

Yashied

Модератор
Команда форума
Глобальный модератор
Сообщения
5,379
Репутация
2,724
CreatoR сказал(а):
можно сделать как-нибудь покрасивее "|TRUE" и "|FALSE", см. например _WinAPI_AlphaBlend().
Ну так записано в самом заголовке. А что нужно с этим сделать?

На самом деле нужно просто отделить пустыми строками блок с "|" (еще может встречаться "|0", "|1" и т.д) в разделе Parameters (а лучше заменить "|TRUE" на "1", "|FALSE" на "0", "|0" на "0" и т.д.). Также лучше убрать переносы текста в этом разделе, если после предложения идет пустая строка, то далее должен идти список значений/констант. Это возможно?

CreatoR, сейчас самое время навести марафет (давай доведем ее до совершенства). Вот, как у меня это выглядит:



"Проблемные" места я обвел красным + еще несколько пожеланий:

  • В разделе Remarks для некоторых функций, у меня текст разделен (по смыслу) пустыми строками. Хорошо бы эти отбивки оставить.
  • В примерах лучше заменить TAB на 4 или более (на твое усмотрение) пробела.
  • Если для функции нет входных или выходных параметров, или примера, то написать None.

И еще, можно сделать так, как на скриншоте, но только там, где есть список (если после предложения в разделе Success идет пустая строка, то перед Failure тоже добавляется пустая строка).

WinAPIEx_Help_2.png



Добавлено:
Сообщение автоматически объединено:

Dreadfulangel сказал(а):
Возможно вопрос уже снят, но на официальном сайте есть файл http://www.autoitscript.com/autoit3/files/archive/autoit/autoit-docs-v3.3.6.0-src.exe , в котором находяться все исходники официальной справки, в том числе и скрипты для её генерации.

Я это видел, но там еще больше гемороя + не хватает некоторых файлов...
 

CreatoR

Must AutoIt!
Команда форума
Администратор
Сообщения
8,671
Репутация
2,481
Yashied [?]
"Проблемные" места я обвел красным
* Синяя полоска это изображение, если я его расширю то на некоторых мониторах оно будет вызывать полосу прокрутки по горизонтали, у тебя видимо монитор широкий (как и муня впрочем), ты это не почувствуешь.
- Хотя есть наверное вариант заполнения градиентом, но это нужно искать в доках по css.
* Переносы строк это проблематично, я конечно могу всё поместить в одну строку, но это будет некрасиво (на некоторых мониторах). И тем более, оно так встречается в заголовках, может проще там поправить?


В примерах лучше заменить TAB на 4
Если для функции нет входных или выходных параметров, или примера, то написать None.
Ок.

можно сделать так, как на скриншоте, но только там, где есть список (если после предложения в разделе Success идет пустая строка, то перед Failure тоже добавляется пустая строка).
Попробуем...
 
Автор
Yashied

Yashied

Модератор
Команда форума
Глобальный модератор
Сообщения
5,379
Репутация
2,724
Эта полоска в IE вообще не показывается, может быть лучше одним цветом (хотя градиент лучше). Примеры в .chm вообще без отступов (что это может быть?). Вообщем, вот что пока получается. Да, и убери пожалуйста везде Title, а то неверно создается TOC (WinAPIEx UDF - _WinAPI_AboutDlg, нужно просто название функции).

WinAPIEx.chm
 

CreatoR

Must AutoIt!
Команда форума
Администратор
Сообщения
8,671
Репутация
2,481
Yashied [?]
Эта полоска в IE вообще не показывается
Мда, base64 ему не по силу, тоже мне браузер...

Ладно щас поищу по докам...

Примеры в .chm вообще без отступов (что это может быть?)
То что IE это недобраузер, под который нужно подстраиваться.

убери пожалуйста везде Title, а то неверно создается TOC (WinAPIEx UDF - _WinAPI_AboutDlg, нужно просто название функции).
Ок.
 

Garrett

Модератор
Локальный модератор
Сообщения
3,999
Репутация
967
CreatoR [?]
- Хотя есть наверное вариант заполнения градиентом, но это нужно искать в доках по css.
Присвойте этот стиль HTML элементу который должен выводить синею полоску с градиентом. Действует только в IE так как задействован фильтр ActiveX компонент!
Код:
<div style="filter:progid:DXImageTransform.Microsoft.gradient( enabled='true', startColorstr=#300089, endColorstr=#BAC7EB, gradientType='1' ); width:100%;  height:22px">WinAPIEx Libray</div>
 

CreatoR

Must AutoIt!
Команда форума
Администратор
Сообщения
8,671
Репутация
2,481
Garrett
Спасибо, я это кстати уже видел пока искал решение, если для Yashied подходит такой вариант (только для IE) то могу добавить... хъотя наверное можно сделать проверку браузерности, вопрос только в том, можно ли это сделать в css?
 
Автор
Yashied

Yashied

Модератор
Команда форума
Глобальный модератор
Сообщения
5,379
Репутация
2,724
Для меня "только для IE" подходит, т.к. CHM и работает на IE.
 

Garrett

Модератор
Локальный модератор
Сообщения
3,999
Репутация
967
CreatoR [?]
... хотя наверное можно сделать проверку браузерности, вопрос только в том, можно ли это сделать в css?

Можно оформить в JavaScript:
Код:
object.style.filter ="progid:DXImageTransform.Microsoft.Gradient(enabled='true', startColorstr=#300089, endColorstr=#BAC7EB, gradientType='1')"
Тогда, наверно, и в других браузерах может начнёт работать.
Можно в стилях непосредственно атрибутом style="", вставить. Но это только для IE.
А вот по поводу CSS сомневаюсь :scratch:



Добавлено:
Сообщение автоматически объединено:

Есть идея, сейчас покумекаю как через CSS оформить! :smile:
 

CreatoR

Must AutoIt!
Команда форума
Администратор
Сообщения
8,671
Репутация
2,481
Я пока добавил через картинку.

Yashied
Принимай, вроде все пожелания/баги учёл.
 
Верх