Отправлено: 19.10.07 10:26. Заголовок: Косяки документации

Предлагаю сделать такую ветку постоянно действующей т.к. топичная информация никогда не переведется
Со временем затирать исправленные замечания.

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

Примеры

Все описания Draw , например
DRAW LINE IN WINDOW <WindowName> AT <nRow>,<nCol>
TO <nRow>,<nCol>
[PENCOLOR <anPenColor>]
[PENWIDTH <nPenWidth>]

А должно быть либо в одну строчку, либо каждый перенос строки должен заканчиваться ;

Аналогично - TAB, DEFINE TIMER, DEFINE TREE и т.д.
Эти косяки сильно маскируются (практически нивелируются) при использовании
визуального форм-дизайнера, автор которого в этих тонкостях разбирался.


Команда
ON KEY ALT <Key> [ OF <ParentWindow>] ACTION <ActionProcedureName> | <bBlock>
В списке доступных Key я не нашел нужный мне простой ESC.
А, оказывается, нужно как в примере
ON KEY ESCAPE ACTION Form_2.Button_2.OnClick
безо всяких ALT.
И еще там есть модификатор WIN

Команды PUSH KEY вообще не нашел

А функция SetProperty( <cWindowName>[,<cControlName>], <cPropertyName> , <PropertyValue> )
может иметь до 7 (семи) аргементов!!!

И откуда это узнать? Я случайно наткнулся в текстах.
Не проверять же каждое описание в документации по исходникам.
А вот кстати проверим GetProperty ...
Ну вот - оказывается не до 3, а до 6 (шести) аргументов.
Так-так... Ну а еще проверим...
DoMethod(<WindowName>,[<ControlName>],<MethodName>)
- до 9 (девяти) аргументов!!!

Товарищи!!! От нас скрывают всю правду!!! Всю мощь и гибкость MiniGUI!!!

Есть лишние пробелы в написании имен и в др.важных местах,
т.ч. просто скопировать и вставить не получится.
Например
Get Property (<cWindowName>[,<cControlName>] ,<cPropertyName>)--> PropertyValue

Перечень команд без каких-либо объяснений
Например - Image List.
Наверное предполагается, что пользователи МиниГУИ знают WinAPI,
и поэтому им не трудно догадаться - о чем идет речь.
Аналогично - некоторые непонятные свойства некоторых контролов.
...

Да... Перечитав ранее написанное я подумал, что косяков столько, что сначала нужно документацию
тщательно переработать и только потом устранять редкие мелкие неточности.

А как народ считает? Или никто документацией не пользуется? Всем хватает исходников?
И только я, как начинающий минигуист-харборист (т.е. как лох), пользуюсь документацией.

P.S.
Сейчас проверил "What's New" - нашел последнее упоминание о SetProperty( )
2006/12/05: Build 28 (HMG 1.2 Extended) Published.
· Enhanced: The Tab control supports a new Image property:
· function syntax
SetProperty ( ParentForm, ControlName, 'IMAGE', Column, cImage )
GetProperty ( ParentForm, ControlName, 'IMAGE', Column )

 Отправлено: 19.10.07 10:59. Заголовок: Re:

SADSTAR2 пишет:

цитата:

я нашел много серьезных несоответствий

Согласен, поскольку это беда многих развивающихся open source проектов

SADSTAR2 пишет:

цитата:

Перечень команд без каких-либо объяснений

Подтверждаю
Объяснение этому простое: плохое владение английским языком не позволяет внятно объяснить чтo к чему и со временем эти пробелы в доке забываются

SADSTAR2 пишет:

цитата:

Команды PUSH KEY вообще не нашел

Это недокументированная команда

SADSTAR2 пишет:

цитата:

сначала нужно документацию тщательно переработать

Это несколько раз предлагалось на английском форуме, но желающих пока не нашлось..

SADSTAR2 пишет:

цитата:

От нас скрывают всю правду

Ну зачем же так
Ведь пишите, что в примерах это можно найти
А если серьезно, то знание этих дополнительных параметров необязательно при использовании псевдо-ООП синтаксиса, который действительно скрывает эти подробности

SADSTAR2 пишет:

цитата:

Или никто документацией не пользуется?

Думаю, что среди русскоязычных пользователей Вы - в меньшинстве
Документация-то - на английском

 Отправлено: 22.10.07 01:09. Заголовок: Re:

gfilatov пишет:

цитата:

SADSTAR2 пишет: цитата: Или никто документацией не пользуется? Думаю, что среди русскоязычных пользователей Вы - в меньшинстве Документация-то - на английском

Не понял. Есть русская документация, которую читают русскоязычные пользователи ?
А я, идиот, читаю английскую.
А-а-а... Понял!!! Все читают испанскую документацию!!!

gfilatov пишет:

цитата:

А если серьезно, то знание этих дополнительных параметров необязательно при использовании псевдо-ООП синтаксиса, который действительно скрывает эти подробности

Наверное я недостаточно глубоко знаю Харбор.
Как написать Form1.Tab1.Caption(nP):=cPageName
если "Form1" хранится в cFormName, "Tab1" в cTabName.
Я придумал только DoMethod(cFormName, cTabName, 'Caption', nP, cPageName).
А это не 3(три) аргумента как в документации, а ажно 5 (пять)

-----------------------
Хотите еще серьезных косяков? Их есть у меня. В выходные наткнулся.
1.---
в определении
DEFINE CHECKBOX <ControlName>
[ ID <nId> ]
[ PARENT <ParentWindowName> ]
COL <nCol>
ROW <nRow>
WIDTH <nWidth>
HEIGHT <nHeight>
[ VALUE <lValue>]
[ FONTNAME <cFontname>
[ FONTSIZE <nFontsize> ]
[ FONTBOLD < .T. | .F.> ]
[ FONTITALIC < .T. | .F.> ]
[ FONTUNDERLINE < .T. | .F.> ]
[ FONTSTRIKEOUT < .T. | .F.> ]
[ TOOLTIP <cToolTipText> ]
[ BACKCOLOR <aBackColor> ]
[ FONTCOLOR <aFontcolorRGBArray> ]
[ ONGOTFOCUS <OnGotFocusProcedur> | <bBlock> ]
[ ONCHANGE <OnChangeProcedure> | <bBlock> ]
[ ONLOSTFOCUS <OnLostFocusProcedure> | <bBlock> ]
[ HELPID <nHelpId> ]
[ NOTABSTOP < .T. | .F.> ]
[ TRANSPARENT < .T. | .F.> ]
END CHECKBOX

нет свойства CAPTION хотя в определении
@ <nRow> ,<nCol> CHECKBOX<ControlName>
[ ID <nId> ]
[ OF | PARENT | DIALOG <ParentWindowName> ]
CAPTION<cCaption>
[ WIDTH <nWidth>] [ HEIGHT <nHeight> ]
...
это свойство есть. Да еще и среди обязательных!!!
Аналогично - здесь есть свойства
[ INVISIBLE ]
[ LEFTJUSTIFY ]
[ THREESTATE ]
которых нет в варианте DEFINE ...

2---
В документации
DEFINE GRID
...
[ NOHEADERS < .T. | .F.> ]
...
END GRID

выпадает на ошибку при компиляции потому, что в i_altsyntax.ch свойство NOHEADERS не фигурирует.
А в i_grid.ch оно присутствует, как ему и положено. Вчера править такие системный вещи я не решился.
А сейчас думаю - нужно попробовать по аналогии. Уж очень ценное для меня свойство пропадает.

-------------
Все это в версии 43. Может в 44 что-то исправлено - не смотрел.

 Отправлено: 22.10.07 09:14. Заголовок: Для SADSTAR2 и других "анонимных" пользователей MiniGUI Ex.

Читая последние посты у меня сложилось такое мнение, что кто-то кому-то продал что-то некачественное..

Извините, но я думаю, что никто никому ничего не должен. Ни документацию писать, ни портировать в xHb, ни проверять что там не дописали.

Вы все прекрасно знаете, что автор MiniGUI Роберто Лопез. Именно он разработал архитектуру библиотеки. Ему, по большому счету, и предъявляйте свои претензии (если он вам ответит ). MiniGUI Ex - это не отдельный продукт, не ответвление (fork) от MiniGUI. Это всего лишь набор расширений (несколько controls и функций), сделанный исключительно на энтузиазме таких же пользователей, как и вы, в первую очередь это касается Григорий Филатова. Поверьте этот энтузиазм не безграничен, в конце концов у каждого своя работа, свои проблемы. Я думаю пример HWGUI довольно показателен.

 Отправлено: 22.10.07 09:39. Заголовок: Re:

Петр пишет:

цитата:

Как написать Form1.Tab1.Caption(nP):=cPageName если "Form1" хранится в cFormName, "Tab1" в cTabName. Я придумал только DoMethod(cFormName, cTabName, 'Caption', nP, cPageName).

Вы все делаете правильно

SADSTAR2 пишет:

цитата:

Хотите еще серьезных косяков? Их есть у меня

Спасибо, посмотрю

SADSTAR2 пишет:

цитата:

в i_altsyntax.ch свойство NOHEADERS не фигурирует

Вместо свойства NOHEADERS д.б. указано свойство SHOWHEADERS .f. | .t.

Петр пишет:

цитата:

Я думаю пример HWGUI довольно показателен.

Имеется в виду длительное отсутствие автора библиотеки А.Кресина в поле зрения пользовательских форумов...

Петр пишет:

цитата:

Поверьте этот энтузиазм не безграничен

Согласен

 Отправлено: 22.10.07 09:44. Заголовок: Re:

Извините, ЗДЕСЬ НЕЧЕМУ УДИВЛЯТЬСЯ И ТЕМ БОЛЕЕ ВОЗМУЩАТЬСЯ.
Проект открытый, работа по его развитию выполняется на основе сугубо НЕОПЛАЧИВАЕМОЙ и без должной координации. Это сказывается как на документации ( которую никто из нас грешных писать не любит ), так и местами на уровне разработки - но в целом проект РАБОЧИЙ и разработчики заслуживают признательности. Именно за весьма неплохой в целом проект, ПОДАРЕННЫЙ людям.
Одна из особенностей открытых проектов состоит в том, разработчики ничего особо не дают, но ничего и не прячут так что что можно самому поискать причину бага, а при необходимости ещё и усовершествовать код системы под себя.

 Отправлено: 23.10.07 01:51. Заголовок: Re:

G-Serge пишет:

цитата:

ЗДЕСЬ НЕЧЕМУ УДИВЛЯТЬСЯ И ТЕМ БОЛЕЕ ВОЗМУЩАТЬСЯ.

А где вы это видите? Здесь?

цитата:

Товарищи!!! От нас скрывают всю правду!!! Всю мощь и гибкость MiniGUI!!!

Я думал, что всем будет понятна шуточность этого высказывания.
В следующий раз буду добавлять пояснение - "Бамбарбия киргуду" [(с)"Кавказская пленница"]

А с другой стороны - почему бы и не повозмущаться?
Если выдаешь что-либо для всеобщего пользования, платно или бесплатно, - отвечай за косяки.
А то привыкли все к буржуйской отмазке "as is"

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

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

Ответьте мне и может я заткнусь невеки. (- "Бамбарбия киргуду" )

P.S.
G-Serge пишет:

цитата:

при необходимости ещё и усовершествовать код системы под себя.

Это порочная практика, т.к. приводит к тупиковой (неразвиваемой дальше) ветке.
Допустима только для своих авторских модулей.
Небольшой пример от меня.
Есть у меня два правленых "под себя" модуля - MySQL и HBprinter.
Это почти постоянная головная боль при смене версий.
Не далее как вчера трахался пол-дня когда после небольшого непринципиального исправления
старая программа стала молча вылетать при запуске.
Оказалось - с дуру перекомпилировал в 43 версии, тогда как раньше эту программу делал в 33-й.
Внесение обычных моих изменений в HBprinter нужного результата не дало - наверное авторские изменения более глубокого уровня - нужно изучать. Вернулся к версии 33 и все стало Ок.

 Отправлено: 23.10.07 10:35. Заголовок: Re:

SADSTAR2 пишет:

цитата:

Какова конечная цель этого проекта?

Эта цель была определена сразу при создании библиотеки:
получить бесплатный и простой в использовании инструмент для создания Win32-приложений

SADSTAR2 пишет:

цитата:

Может это просто полигон для проверки идей маэстро?

На начальном этапе так и было - просто почитайте minigui\History.txt

SADSTAR2 пишет:

цитата:

непротиворечивая документация необходима

Думаю, что никто с этим не спорит. Для усовершенствования документации в поставку включен ModifyChm.bat, который по идее должен позволить декомпилировать MiniGUI.chm, исправить неточности и затем собрать этот файл снова. Кстати, рекомендуется выложить на английском форуме такие исправленные файлы помощи

SADSTAR2 пишет:

цитата:

Есть у меня два правленых "под себя" модуля - MySQL и HBprinter

Так не держите эти исправления "в себе": выкладывайте в папку CONTRIB на английском форуме.
Если они представляют общий интерес, то обязательно будут включены в новый релиз

 Отправлено: 23.10.07 10:58. Заголовок: Re:

Я думаю, что такое печальное положение вещей скорее всего не изменится - я имею ввиду заброшенность документации, нескоординированность работы над кодом вообще и недостаточный уровень тестирования в частности. За серьёзный уровень работы душа просит серьёзных денег, как это не печально . А забесплатно - извольте "AS IS" со всеми родимыми пятнами впридачу.
Так что если эти вопросы настолько принципиальны, наверное, уже нужно ставить вопрос - оставаться ли дальше с этим продуктом.
Я вот для себя к этой грустному выбору уже подхожу. Сам HMG мне очень нравится ( Clipper знаю и люблю 15 лет, так что практически родная среда ) , но напрягает некоторая непредсказуемость в совместимости различных релизов.

 Отправлено: 23.10.07 13:12. Заголовок: Re:

G-Serge пишет:

цитата:

Я думаю, что такое печальное положение вещей скорее всего не изменится - я имею ввиду заброшенность документации, нескоординированность работы над кодом вообще и недостаточный уровень тестирования в частности.

Согласен. И для этого есть целый ряд причин.

G-Serge пишет:

цитата:

напрягает некоторая непредсказуемость в совместимости различных релизов.

Не знаю, что вы имеете в виду (H или MG ).
Но вспомните или пересмотрите форум заново - какая реакция на публикации Григория о выпуске новой версии библиотеки - почти никакой. И вспоминать, что в версии 1.30 что-то работало, а в 1.44 это не работает . Вот так и работаем: нужно мне что-то - вспомнил о MiniGUI, не нужно - смотреть не буду.
А как вы собираетесь проводить тесты? В FWH ( и другом коммерческом и не только ПО ) есть институт бета-тестеров, пользователи продукт перед выпуском тестируют и за это получают небольшие скидки при покупке. Удается отлавливать до 90% ошибок. В MiniGUI Ex все тестирование проходит после выпуска и ошибки (по идее) устраняются в сл.выпуске, здесь нет (почти) патчей, сервис паков и т.д.. А много времени вы тратите на тестирование ? Вот и кочуют ошибки из релиза в релиз, привносится несовместимость.
Еще несколько слов об совместимости. Совместимость в MiniGUI Ex зависит не только от MiniGUI, но и от разработчиков Harbour и xHb и изменений в этих продуктах.
Многие не представляют, насколько облегчилась бы работа разработчиков MiniGUI, будь библиотека заточена под один компилятор.

 Отправлено: 23.10.07 13:51. Заголовок: Re:

Петр пишет:

цитата:

Совместимость в MiniGUI Ex зависит не только от MiniGUI, но и от разработчиков Harbour

Вот сейчас бьюсь над последними изменениями в Харборе, которые привели к появлению либо черного ДОС-окна либо неработоспособности Win32-приложений (сообщение об этой ошибке есть на пользовательском форуме Харбора)

 Отправлено: 23.10.07 13:55. Заголовок: Re:

G-Serge пишет:

цитата:

напрягает некоторая непредсказуемость в совместимости различных релизов

Используйте всегда последний релиз, будет меньше проблем

 Отправлено: 23.10.07 21:31. Заголовок: Re:

Мои высказывания не содержат в себе каких-либо претензий ни к проекту, ни к разработчикам. Проект, на мой взгляд - однозначно хорош, хотя и реализуется на голом энтузиазме, перед разработчиками почтительно снимаю шляпу.
Но я в первую очередь присматриваюсь к H&MG как орудию повседневного труда, в котором в первую хочу быть уверен. И главное, в чем я хочу быть уверен, так это в том, что каждый кусок написаного мною кода будет отрабатывать с каждой версией библиотеки или компилятора ОДИНАКОВО.

gfilatov пишет:

цитата:

Используйте всегда последний релиз, будет меньше проблем

SADSTAR2 пишет:

цитата:

Есть у меня два правленых "под себя" модуля - MySQL и HBprinter. Это почти постоянная головная боль при смене версий. Не далее как вчера трахался пол-дня когда после небольшого непринципиального исправления старая программа стала молча вылетать при запуске. Оказалось - с дуру перекомпилировал в 43 версии, тогда как раньше эту программу делал в 33-й. Внесение обычных моих изменений в HBprinter нужного результата не дало - наверное авторские изменения более глубокого уровня - нужно изучать. Вернулся к версии 33 и все стало Ок.

А если к примеру глюканёт приработанная уже программа у работодателя ? Серьёзно глюканёт после внесения одного-двух несерьёзных изменений, просто после перекомпиляции ? Как работодатель отреагирует на заверение, что релиз был гарантированно самый последний ? А если внесенные изменения основывались на возможностях библиотеки, которые отсутствовали в более ранней версии, под которой собственно программа разрабатывалась и тестировалась ?

У H&MG у меня таких проблем пока нет, но я и занимаюсь им всего два месяца. И теперь я знаю, что такое в принципе возможно. И это душу не греет абсолютно.

 Отправлено: 23.10.07 21:46. Заголовок: Re:

gfilatov пишет:

цитата:

Вот сейчас бьюсь над последними изменениями в Харборе, которые привели к появлению либо черного ДОС-окна либо неработоспособности Win32-приложений (сообщение об этой ошибке есть на пользовательском форуме Харбора)

Я с таким сталкивался, когда у меня опции компилятора были выставлены неправильно.

 Отправлено: 23.10.07 23:57. Заголовок: Re:

G-Serge пишет:

цитата:

А если к примеру глюканёт приработанная уже программа у работодателя ? Серьёзно глюканёт после внесения одного-двух несерьёзных изменений, просто после перекомпиляции ?

Теоретически все возможно.
Но проблема совместимости - это не только проблема HMG ( более правильное название библиотеки, которую мы сейчас обсуждаем - MiniGUI Ex. ) Не буду о Pascal, Delphi - почти не использовал, но помню, что модули (UNIT) надо было перекомпилировать при переходе на новую версию - хорошо если исходники были доступны. VB6 и VB.NET - это вообще два разных мира. Многим пользователям VB6, в т.ч. мне, легче было перейти на C#, чем наново учить VB.NET. Переход от C# 1.0 к C# 2.0 - все части программ с использованием "неуправляемого" кода ( доступ к API, указатели ) надо было переписывать.
Компиляция простого C кода
MYSTRUCT mystruct;
mystruct = NULL;
пройдет в bcc32 и не пройдет с использованием pocc, lcc, dcc ( для них правильнее писать mystruct = 0;).

Но для таких случаев и предусмотрены всякие директивы #ifdef и прочие.

 Отправлено: 24.10.07 09:02. Заголовок: Re:

Петр пишет:

цитата:

Но проблема совместимости - это не только проблема HMG ( более правильное название библиотеки, которую мы сейчас обсуждаем - MiniGUI Ex. )

Спасибо за разъяснение. А под HMG я предполагал связку Harbour+MiniGUI :)

 Отправлено: 24.10.07 22:16. Заголовок: Re:

Мы немного отклонились от темы.

SADSTAR2 пишет:

цитата:

Предлагаю сделать такую ветку постоянно действующей т.к. топичная информация никогда не переведется Со временем затирать исправленные замечания.

Я - за. Осталось только уточнить как это будет выглядеть на практике, поскольку прав модератора ни у кого из пользователей MiniGUI похоже нет.

Еще одно предложение - создать в MiniGUI Ex ch файл чем-то похожий на

/*
* $Id: hbextern.ch 7792 2007-10-01 22:17:21Z vszakats $
*/

/*
* Harbour Project source code:
* The declarations for all harbour defined functions/procedures.
*

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

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

 Отправлено: 25.10.07 02:38. Заголовок: Re:

Я тут пытался для себя ситуацию прояснять
На базе файла h_controlmisc.prg начал писать памятку.
Текущий вариант (черный-черный) здесь http://dump.ru/files/n/n581598440/
Думаю расширить подробностями и примерами, а то через полгода забуду и трудно будет опять вспоминать.

 Отправлено: 25.10.07 08:38. Заголовок: Re:

Петр пишет:

цитата:

Еще одно предложение - создать в MiniGUI Ex ch файл чем-то похожий на

цитата:

rem _func_lst.bat @echo off del _mfunc.ch FOR /F "usebackq delims==" %%i IN (`find /I "%1" %2`) DO @echo %%i >> _tmp1.txt FOR /F "eol=- tokens=1,2,3 delims=() " %%i in (_tmp1.txt) DO @echo %%i %%j %%k >> _tmp2.txt del _tmp1.txt FOR /F "eol=- tokens=2 delims= " %%i in (_tmp2.txt) DO @echo EXTERNAL %%i >> _tmp1.txt sort _tmp1.txt >> _mfunc.ch del _tmp2.txt del _tmp1.txt

Необходимо поместить в папку с исходниками и запускать
_func_lst.bat HB_FUNC *.*
или
_func_lst.bat FUNCTION *.prg

P.S. При копировании необходимо удалить возможные пробелы в конце строк.

 Отправлено: 25.10.07 09:50. Заголовок: Re:

Неплохо бы отвести целиком отдельный РАЗДЕЛ этого форума под интерактивную документацию и вопросы использования MiniGUI применительно к отдельным функциям, что-то вроде FAQ. Со временем может набраться неплохой коллективный справочник с актуальными ответами по самым каверзным моментам.

 Отправлено: 25.10.07 11:03. Заголовок: Re:

Петр пишет:

цитата:

создать в MiniGUI Ex ch файл чем-то похожий на

Такой файл уже есть в 44-м релизе в папке Utils\FuncList\Data\minigui.txt
Удобный доступ (и формирование) к нему обеспечивает программа Utils\FuncList
Описание этой программы находится в файле Utils\FuncList\ReadMeRu.txt

Петр пишет:

цитата:

увеличить время между выпусками релизов

Ничего не имею против, вот только выпущу 45-й релиз в понедельник, 29 октября
и ....

Петр пишет:

цитата:

Попробовать поискать бета-тестеров

Это реально (!?) - уж больно специфический продукт для русскоязычной аудитории, привыкшей к бесплатным СИ-билдеру, Дельфи и т.п.