The Lazarus package FCL seems to hide the FPC/FCL, at least I cannot get any context sensitive help on FCL units or identifiers (using CHM) :-(

FPDoc Editor doesn't show anything as well, even if I added the RTL/FCL help directories to its search path.

Can somebody explain how the RTL and FCL docs are found at all, when RTL the RTL is not (and FCL a different) Lazarus package?

As already mentioned, we should rethink the packaging for Help. IMO the LCL docs should include LazUtils, and the RTL and FCL docs must be made available, somehow. My previous attempt to add RTL and FCL directories to the Lazarus/docs/xml was dropped, because it cannot be synced with reasonable efforts with the FPC docs. But now we have accessible FCL documentation any more, what certainly is intolerable.

DoDi

Hello,

I uninstalled Lazarus, cleaned the registry and suppressed the appdata\local\lazarus directory.

After a new install of lazarus-0.9.30.2-fpc-2.4.4-win64.exe, I get this message:

C:\lazarus\lcl\interfaces\win32\interfaces.pp(32,3) Fatal: Can't find unit
InterfaceBase used by Interfaces.

Classical "Hello word" application compiles correctly.

In which direction may I search an issue ?

Thanks in advance.

Hans-Peter Diettrich wrote

As already mentioned, we should rethink the packaging for Help. IMO the LCL docs should include LazUtils, and the RTL and FCL docs must be made available, somehow.

Use the right tool for the job. ;-) I have the RTL, FCL, LCL, fpGUI and FPC Language Ref available via context sensitive help (working for stable and trunk versions of Lazarus, and also for the latest MSEide). All setup via one simple External Tools entry - no need to fiddle with IDE internals, packages or FPC paths.

Create a new project, save it, compile it. Does that work?

Mattias

The Lazarus package FCL seems to hide the FPC/FCL, at least I cannot get any context sensitive help on FCL units or identifiers (using CHM) :-(

Have you installed the rtl.chm and fcl.chm?

FPDoc Editor doesn't show anything as well, even if I added the RTL/FCL help directories to its search path.

I enabled fpdoc for the FCL package.

Can somebody explain how the RTL and FCL docs are found at all, when RTL the RTL is not (and FCL a different) Lazarus package?

Every designtime package can register help for source directories. That means when the IDE needs help for TComponent in
$(FPCSrcDir)/objpas/classes/classes.pp it asks the registered help databases.
The chmhelppkg package registers such help.

As already mentioned, we should rethink the packaging for Help. IMO the LCL docs should include LazUtils

Means?

What is the problem?

Mattias

Somehow I have the feeling that this isn't what DoDi wants...

Regards,
Sven

I'm a bit confused now. When I wrote this message, I really couldn't access the fcl.chm by F1, or the related docs via FPDoc Editor. Today it seems to work, at least for F1.

> FPDoc Editor doesn't show anything as well, even if I added the RTL/FCL > help directories to its search path. I enabled fpdoc for the FCL package.

FPDoc Editor still seems not to recognize the FCL units correctly. When I want to add documentation on e.g. fcl-xml/src/dom.pp, it complains that this unit is not owned by any package or project. What should I do to add this and other FCL units to the FCL package, so that I can extend the FCL documentation?

> Can somebody explain how the RTL and FCL docs are found at all, when RTL > the RTL is not (and FCL a different) Lazarus package? Every designtime package can register help for source directories.

The RTL at least is not a registered Lazarus designtime package, and the FCL package obviously doesn't cover the full FCL :-(

> As already mentioned, we should rethink the packaging for Help. IMO the > LCL docs should include LazUtils Means?

Please explain how the LCL documentation is organized. The Lazarus 0.9.30 LCL was one synthetic package, covered by a corresponding lcl.chm file. But now (trunk) the package LCL contains the widgetsets, while the common code resides in packages LCLBase and LazUtils. I would like to have a single document (chm) for these 3 packages as well.

I wonder how FPDoc Editor finds the documentation on e.g. unit barchart.pp, which is part of the LCLBase package, but barchart.xml mentions this module as part of the lcl package?

Should the LazUtils units documentation use the same hack?

Lazarus seems to create its own package structure, different from the FPC structure. This becomes obvious with the LazUtils package, containing modified copies(?) of the corresponding FCL units. The documentation again introduces a different package structure, with the units of the LCLBase package merged into the lcl package.

When I'm working with FPDoc code (FPC/utils/fpdoc), the units refer to the FCL XML modules (e.g. FPC/packages/fcl-xml/src/dom.pp), while LazUtils contains an different set of units, e.g. lazutils/laz_dom.pas, which redefine the FCL classes and identifiers. This means duplicate documentation efforts, for the FCL and LazUtils units. That's a maintenance nightmare :-(

WRT LCL documentation see above: should the LazUtils units be made part of the LCL documentation package, and will that really work?

DoDi

Hans-Peter Diettrich hat am 19. Januar 2012 um 16:55 geschrieben:

[...] >> FPDoc Editor doesn't show anything as well, even if I added the

RTL/FCL

Good question.
The fcl.lpk is only a representative package, e.g. registering FCL components and containing the IDE registration code. It is not meant to handle the whole FCL.
Technically the fcl.lpk only contains the units in the packager/registration folder.
Maybe the fpdoc editor can be extended to ask the user where to put the xml file.

>> Can somebody explain how the RTL and FCL docs are found at all, when

RTL

Yes.

>> As already mentioned, we should rethink the packaging for Help. IMO

the

Why?

I wonder how FPDoc Editor finds the documentation on e.g. unit barchart.pp, which is part of the LCLBase package, but barchart.xml mentions this module as part of the lcl package?

The fpdoc editor has to find the xml file for a package, not the other way round. So for the fpdoc editor it does not matter what module is in the xml file.
But for fpdoc the module should be the Lazarus package name. The xml files needs to be updated.

Should the LazUtils units documentation use the same hack?

What hack?

For example?

The documentation again introduces a different package structure, with

the

units of the LCLBase package merged into the lcl package.

The code is logically divided into separate package. Therefore I think the fpdoc xml files should be in separate directories too. The chm help format has the ability to combine multiple fpdoc files into one. It is useful to combine all xml files of a package into one chm. But of course it is also possible to combine multiple packages into a single chm file. I leave this decision to the chm packagers.

The laz_dom unit is pretty old and the dom unit has gained many updates and changes. So it makes sense to have different docs. The laz2_dom is the UTF-8 port of the dom unit with a few additions. Because the IDE uses it for its config files it is important that these units do not change like the FCL units. Therefore they are in the Lazarus sources.
That is not optimal, but better than data corruption.

WRT LCL documentation see above: should the LazUtils units be made part of the LCL documentation package, and will that really work?

Mattias
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120119/0356061e/attachment-0001.html>

The fcl.lpk is only a representative package, e.g. registering FCL components and containing the IDE registration code. It is not meant to handle the whole FCL.

Then it should be possible to rename the package, so that it does not conflict with the FPC FCL. E.g. LazFCL

A package name is required as well, so that a package name has to be requested. Then the unit must be added to the package, so that the document file can be created in the package doc directory.

But you can't tell why it is as it is, and how documentation is supposed to work?

Why what? In the last release a single CHM contains the LCL documentation. Breaking it up into multiple packages requires to provide different help files for every Lazarus version :-(

IMO we should virtualize the direct relationship between Lazarus and documentation packages. When every Lazarus package is assigned an FPDoc package name, too, the LCL documentation could e.g. span the packages LazUtils, LCLBase, LCL and (Lazarus) FCL, not hiding the FPC FCL any more.

A documentation package name *different* from the Lazarus package name.

Please find your question answered in my preceding message.

This may be a reasonable decision for third party or other optional packages, but not for the RTL, FCL and LCL.

The chm help format has the ability to combine multiple fpdoc files into one.

But only when these files are part of the same documentation package.

It is useful to combine all xml files of a package into one chm. But of course it is also possible to combine multiple packages into a single chm file.

How that???

I leave this decision to the chm packagers.

What makes you think that it's easier to modify fpdoc, instead of adopting Lazarus help to the established fpdoc conventions and implementation?

IMO you should understand how fpdoc works, before you try to convince the developers to modify the current model.

So we have to document a total of 3 DOM packages???

Because the IDE uses it for its config files it is important that these units do not change like the FCL units. Therefore they are in the Lazarus sources.

Then these legacy units are of no use for developers, and the entire LazFCL package can stay undocumented?

That is not optimal, but better than data corruption.

Well, currently I see help corruption all over the place :-(

DoDi

It should not conflict it should extend. There is no code in the fcl.lpk that needs fpdoc help.
I removed the test xml. The fpdoc entry for RegisterUnit was not helpful.

yes

Then the unit must be added to the package, so that the document file can be created in the package doc directory.

The fcl files must not be added to the fcl.lpk, because they can be moved/renamed by the FPC team between versions.

The IDE registers fpdoc help for some FPC directories (rtl, fcl-base/src;fcl-db/src;fcl-extra/src;fcl-process/src;fcl-web/src;paszlib/src) and simply opens the URL
http://lazarus-ccr.sourceforge.net/docs/<fpdoc
path>.

The chmhelppkg package extends/overrides some of these settings. Maybe the chm authors can give some clues about the chm parts.

Well, the binaries do that anyway. But I see your point that you want to use thew newest docs for an older version too.
This is a general problem for any long living package. Maybe we can add now some features that make it possible that the current version can use the next version. Ideas?

I think it would be confusing if the fpdoc page says package 'LCL', but the unit is in the package 'LazUtils'.

Hack (computer science): "an inelegant but effective solution to a computing problem"

I think that is not the right word for a forgotten entry.

Should I update the xml files or need something be updated first?

Is this a limitation of the fpdoc chm writer?

If you really want a single chm file then you can for example use a simple search and replace to change all package names and links and feed the new xml files into the chm creator.

The old laz_dom should not be used for new projects. The documentation can be short.
The laz2_dom docs can refer to the FCL one.

laz2_dom is part of lazutils.
laz2_dom/read/write are of good use for developers. They are fast UTF-8 xml units. I use them in some of my projects. The fcl.lpk package does not need fpdoc help.

> That is not optimal, but better than data corruption. Well, currently I see help corruption all over the place :-(

As far as I remember: you always did. ;)

Mattias

Would it help to add a dummy package (or project?) with all (relevant) FCL units?
Then an help author can add more units to that package, when adding docs on further FCL units?

The chmhelppkg package extends/overrides some of these settings. Maybe the chm authors can give some clues about the chm parts.

Existing chm files seem to work off-the-shelf, I see no need for special updates there. The critical points are how F1 finds the (CHM/HTML) file for a unit, and how FPDoc Editor finds the XML file.

The problems started when I wanted to add documentation for FCL units, which are not recognized by the FPDoc Editor. Even if these docs will be added to FPC, Lazarus must be able to find the related docs. This is not related to Lazarus versions.

Lazarus adds further problems with the new package structure, which become obvious only when somebody tries to build the docs for Lazarus trunk.

This is a general problem for any long living package. Maybe we can add now some features that make it possible that the current version can use the next version. Ideas?

As already suggested: add synthetic packages or projects, to which the contained units can be added freely. Then make the help system use these projects to find the applicable doc and XML file for these units.

Or make the help system use FPDoc project files, instead of Lazarus package files, which contain lists of all contained (documented) units (<inputs>) and related docs (<descriptions>). The <descriptions> deserve no special handling, as long as every $unit.pas is documented in $unit.xml, and the xml files reside in the same directory - as is.

The project files have been introduced in fpdoc 2.7, to simplify building the docs. Using them will also eliminate the need for build_lcl_docs or similar scripts, when only the equivalent fpdoc project is supplied. The FPDocManager (in examples) can create fpdoc projects from/for existing Lazarus packages or projects.

Slowly you seem to get it ;-)

It *is* already confusing, when the fpdoc page says package 'LCL', but the unit is in the package 'LCLBase' :-(

A user will *not* be confused much, when all Lazarus supplied units are documented in 'LCL' (e.g. lcl.chm), regardless of Lazarus-added arbitrary subdivisions. He also will not be confused when FPDoc Editor simply can put a description into wherever it is expected by the help system.

You forgot to add: a *fragile* solution, which may be broken by changes somewhere else in the code or compiler.

I think that is not the right word for a forgotten entry. Should I update the xml files or need something be updated first?

We have to find a working solution, before any attempt to make descriptions (in)accessible in the new docs :-]

It's a limitation of fpdoc in general. It can generate documentation only for single *packages* (--package=xyz). This does not matter much when building HTML help, residing in a bunch of related HTML files, but it matters with every linear (monolithic) document, be CHM, PDF etc.

That's why I suggest a single (fpdoc) package 'LCL', instead of cluttering the docs and indices(!) into LCL, LCLBase, LazUtils etc. IMO a user will be confused when he *thinks* that he is using the LCL, but has to search for help on it in LCLBase.chm, where up to the last release *everything* LCL-related was documented in LCL.chm.

Please check such a "solution" yourself, and find out how it breaks FPDoc Editor and Hints :-(

All I wanted to point out are *Lazarus generated* problems, not problems of fpdoc.

The fcl.lpk package does not need fpdoc help.

That's why I wonder why it is *named* 'fcl', when this name already is in use for the FPC FCL. Rename it into LazFCL, and everything is fine again.

DoDi

You mean in the fpc sources?
Yes, such dummy packages would help the IDE to find out which unit belongs to the FCL, which one to RTL, etc.
It could also setup the unit and include paths. Although I'm not sure if the include file names are unique enough to use only one lpk for the whole FCL.
Of course it can not be used for compiling, because for that you need one lpk per output directory.

The alternative would be to store such dummy packages in the Lazarus sources, but then it needs conditionals for every FPC version.

Then an help author can add more units to that package, when adding docs on further FCL units?

Yes.

The IDE passes the information of the unit file name, the fpdoc element path and the Lazarus package name of the unit to the chm help database. I don't know what the chm db does with that. The fpdoc editor has the same information, additionally searches all ancestors and uses all this to search in the fpdoc paths of the package(s) and the IDE.

Mattias

This is not a limitation; It is a feature: your documentation package name can be anything you want. If you equal "fpdoc package" to "lazarus package", then this is a restriction that you personally enforce, not something that fpdoc enforces.

A fpdoc package creates documentation for a single logical fpdoc package. What you put in this package is your business.

The FCL consists of many "fpmake packages" : fcl-base, fcl-db, fcl-xml. The documentation package is called FCL, and hence the documentation for these various "fpmake packages" can be produced in a single .chm file.

So if you were to call your documentation package lazarus-lcl, you can put in it anything you want, and still have a single CHM file.

What you may need to do, IMHO, is associate a fpdoc package name to a lazarus package. This way, several logical lazarus packages can be combined in a single logical fpdoc package. When showing documentation, the help system should use the fpdoc package name instead of the lazarus package name to determine the name of the CHM file.

This is still only 1-on-N, but that's still better than the 1-on-1 if you equal "fpdoc package" to "lazarus package".

Michael.

The fpdoc projects include the commandline arguments needed to parse the units.

Of course it can not be used for compiling, because for that you need one lpk per output directory.

This must be handled inside the help system. When (application) projects are created, e.g. RTL.lpi and FCL.lpi, there shouldn't exist a need to compile and load according packages into the IDE.

The alternative would be to store such dummy packages in the Lazarus sources, but then it needs conditionals for every FPC version.

Version problems may arise, but I don't think that RTL/FCL units are moved around in future versions, so that the projects will stay valid across FPC versions.

Hmm, I'd assume that the supplied package name selects the chm file to load. This requires that the name matches the *fpdoc* package name, regardless of Lazarus package names.

The fpdoc editor has the same information, additionally searches all ancestors and uses all this to search in the fpdoc paths of the package(s) and the IDE.

FPDoc Editor searches for the XML docs, which must reside in the fpdoc path of the package or project. Most proably it's also assumed that the xml file name matches the unit name. That's the only information that the FE can use to create new xml files.

DoDi

Thanks for the confirmation :-)

Right, but this leaves open how the IDE can find the right documentation package for a given unit. This is where Lazarus must find a useful mapping model.

+1

DoDi

What characters are valid for the fpdoc package name?

A fpdoc package creates documentation for a single logical fpdoc package. What you put in this package is your business.

:)

The FCL consists of many "fpmake packages" : fcl-base, fcl-db, fcl-xml. The documentation package is called FCL,

The package name in the fpcdocs xml files is lower case "fcl". Is the name case insensitive?

I added an option to Lazarus packages/projects to define the fpdoc package name. This is currently only used for newly created fpdoc files. Eventually a renaming tool should be written.

This is still only 1-on-N, but that's still better than the 1-on-1 if you equal "fpdoc package" to "lazarus package".

The package name can be used in links (e.g. link
id="#fcl.zstream.Tgzfilestream"). Is this the package name in the xml file or the option passed to fpdoc? Or in other words: What is the --package option? filter or rename?

Mattias

The fpdoc editor can now create new fpdoc files for the fpc sources. I recommend to add the path to the fpcdocs in the options.

Mattias

Can you give an example file?

At the moment the IDE can load only one lpi. A lpk can be loaded additionally.

They were moved in the past. They will probably move again.

AFAIK the chm viewer loads all chm files. And yes, when the package name is 'rtl' it shows something from the rtl.chm. I don't know how the chm viewer handles the combined rtl+fcl+lcl.chm file.

Yes.
Well, it uses a bit more.

Mattias

I will take a look. It needs dGlobals.
Please add an error directive when compiling with less than 2.7.1.

It seems I don't get it.
I think it is confusing if the docs shows the wrong package. The unit fileutil is in LazUtils, so the docs should show LazUtils, not LCL.

Hacks don't need to be fragile. I know some pretty stable hacks.

The scripts says something about a combined chm for rtl+fcl+lcl. So apparently it is possible to combine multiple fpdoc packages into one chm.

Ehm, the LCL is only one part of Lazarus. There are more packages with fpdoc files in the Lazarus sources. The help will eventually contain all of them.

FPDoc Editor and hints do not use the chm files. They work directly on the xml files.

It was named FCL, because the FCL needed a package to register its components in the IDE.
Renaming would break many projects and packages.

Mattias

Any valid pascal identifier should do.
It definitely cannot contain . and #

No.

Well, you could make it default to the package/project name. This way you don't need to do anything ?

Filter.

Michael.

What about spaces, <, >, ", ', &, -, +, /?

Of course it is the default. :)

Great!

Mattias

> The fpdoc projects include the commandline arguments needed to parse the > units. Can you give an example file?

You can create such files yourself, using FPC trunk. Start with an fpdoc commandline, e.g. from FPC docs:
make rtl.chk > myrtl.bat
and append to the fpdoc command
--write-project=myrtl.xml
then run the updated script to create myrtl.xml.

Must the lpi be loaded to create documentation, using FPDoc Editor?

Then beforementioned fpdoc projects would be the better approach, instead of Lazarus packages.

Why (and how) would you produce such an combined file?

Actually I run into a number of problems with the CHM files. Only one directory is accepted, and this entry also is updated when the Options dialog is left with Cancel. When I copy my additional files (e.g. lazutils.chm) into the chm help directory, these files are not recognized by F1. When I open such an file manually, the other files (e.g. lcl.chm) are no more recognized by the help viewer :-(

I've to wait now until Lazarus again works with FPC 2.7, and I can continue with my experiments with the FPDocManager...

DoDi

The package name in the fpcdocs xml files is lower case "fcl". Is the name case insensitive?

AFAIR not, the LCL docs use both "LCL" and "lcl".

I added an option to Lazarus packages/projects to define the fpdoc package name. This is currently only used for newly created fpdoc files.

Great :-)

Eventually a renaming tool should be written.

Such an option could be added to the FPDocManager. But I see no need so far, the LCLBase docs already (still!) refer to package lcl, and no docs exist yet for LazUtils.

It's a filter, with no special advantage, but prohibiting e.g. RTL, FCL and LCL documentation merged into an single CHM file. Only matching <package name=xyz> sections are added from the xml files. The fpdoc inventors assumed that a single xml file could span multiple packages, what IMO is not very realistic. In addition only those descriptions become part of the output, which have corresponding input (source module) files. Lazarus help and FPDoc Editor already assume that the source and description files have the same (unit) name, but this is not a requirement.

DoDi

The fpdoc editor can now create new fpdoc files for the fpc sources. I recommend to add the path to the fpcdocs in the options.

How can these files be used in future documentation?

Currently they are ignored by fpdoc, unless the corresponding source files (--input) are given to fpdoc at the same time. This (currently) requires to update the Makefile, unless easier editable fpdoc projects are used to create the RTL and FCL documentation. I'd suggest that FPC provides such projects, instead of or in addition to the Makefile.

DoDi

I don't remember how to check the FPC version - can you give me a source snippet?

Why should a user care about the Lazarus package name? When Controls.pp is in LCLBase, should it show up only in LCLBase.chm, instead of lcl.chm (as is)?

> You forgot to add: a *fragile* solution, which may be broken by changes > somewhere else in the code or compiler. Hacks don't need to be fragile. I know some pretty stable hacks.

Ausnahmen best?tigen die Regel ;-)

I dare to doubt that, but I'm not an CHM expert.

One more reason to use an single documentation package name throughout all LCL supplied packages.

Right, and that's why they have to find the xml files first. These files can reside in any directory, as specified in the fpdoc path of the related package or project.

Some foresight had prevented the current mess :-(

DoDi

Maybe Michael or Marco will add them to the fpcdocs.

Mattias

This is the plan.

The projects will be added to FPC as soon as the recent fpdoc changes have been merged to the fixes branch and the Makefile can be adapted to use the project file.

Rationale for this wait:

The docs are not in branches, this means that the Makefile must be suitable for FPC version 2.6.x as well. So as long as the recent fpdoc changes are not in 2.6, the project files will not be committed.

Michael.

{$IF FPC_FULLVERSION<20701}{$ERROR ...}{$ENDIF}

Where? In lhelp?

?

What mess?
There is no other fcl.lpk, so there is no name clash.

Mattias

Afair the URL is changed to
ms-its://lcl.chm/lcl/ for lcl
ms-its://fcl.chm/fcl/ for fcl
ms-its://rtl.chm/rtl/ for rtl

it's possible to share one chm file for all three by using a .chm file that has all three folders with contents (lcl/, rtl/, fcl/)

I had an alldocs.chm (rtl,fcl,lcl) file a while back but it was made with two steps: creating html docs with fpdoc for all projects then using chmcmd to combine them into one chm file.

Then the URL's are
ms-its://alldocs.chm/lcl/ for lcl
ms-its://alldocs.chm/fcl/ for fcl
ms-its://alldocs.chm/rtl/ for rtl

This two step method has the disadvantage of not having a table of contents and index created by fpdoc especially for the chm format. It would probably be easier to create a program that combined chm's after they are created, unless fpdoc becomes able to process multiple packages at once.

It's been a while since I wrote chmhelppkg so things are a bit fuzzy.

Regards,

Andrew Haines

See my other mail.

Actually I run into a number of problems with the CHM files. Only one directory is accepted,

You mean only one directory can have chm files in it?

and this entry also is updated when the Options dialog is left with Cancel.

...

When I copy my additional files (e.g. lazutils.chm) into the chm help directory, these files are not recognized by F1.

...

When I open such an file manually, the other files (e.g. lcl.chm) are no more recognized by the help viewer :-(

Manually = lhelp File -> Open?

At one point I tried to see if installing packages could make available context help files (F1) but was not able to fully understand how to add help databases. (Installing package "x.lpk" makes x.chm available.) And there are different types of help formats (local html files/ http / chm. i.e. there was/is? no straightforward (that I found) way to add that.

Regards,

Andrew Haines

What do you need?

And there are different types of help formats (local html files/ http / chm. i.e. there was/is? no straightforward (that I found) way to add that.

Can you give an example?

Mattias

Honestly at this point I don't remember.

It's been probably a year since I I guess my problem was how do we add a flexible "helpfile" setting to x.lpk?

I need to look at the helpsystem again to be able to answer this properly.

Does laz_xmlconf remember settings that are unknown to the current lazarus? I want to know if setting for instance
'help/chm/api/filename/value'
'help/chm/ref/filename/value'
'help/chm/xxx/filename/value'
in a lpk would be erased by being modified with a version of lazarus that was unaware of help/chm help.

I think my main problem was that I couldn't find where the codetools figured out that the identifier it was looking up was not in the lcl/fcl/rtl and had no help available for it. That is the point where I needed to get it to see if the current project or the package the unit belonged to has help associated with it.

I am still interested in implementing this but in the past I was unable to follow the logic of connecting an identifier with it's help.

Regards,

Andrew

Yes, the IDE cleans up lpk files.
Each package and project has custom options - simple name, value pairs.

I think my main problem was that I couldn't find where the codetools figured out that the identifier it was looking up was not in the lcl/fcl/rtl and had no help available for it.

The codetools don't know about packages. The IDE knows.

That is the point where I needed to get it to see if the current project or the package the unit belonged to has help associated with it.

The IDEIntf has a function to get the owner(s) of a unit. See here:

http://wiki.lazarus.freepascal.org/Extending_the_IDE#Find_the_package.28s.29_of_a_unit

I am still interested in implementing this but in the past I was unable to follow the logic of connecting an identifier with it's help.

Mattias

> Actually I run into a number of problems with the CHM files. Only one > directory is accepted, You mean only one directory can have chm files in it?

The Options dialog only accepts one directory. It may be a restriction of this dialog, or of the Lazarus chm viewer. Windows chm help has no such restriction by design.

Double click in Windows Explorer ;-)

Here fpdoc packages can simplify your life. Then building documentation on the target machine only requires a line in the Makefile, like fpdoc --project=mypkg.xml --format=$whatever --output=$wherever

For the target directory of chm files the fpdoc path in the IDE Options can be used.

DoDi

Hans-Peter Diettrich wrote

When I copy my additional files (e.g. lazutils.chm) into the chm help directory, these files are not recognized by F1.

This is why I (rather unsuccessfully) tried to switch to DocView.

-Michael

I stopped merging them because I assumed you wanted to wait till your current project was done.

The fcl-passrc, fpdoc fixes are listed here:

http://www.stack.nl/~marcov/mergelogs26/fpdoc.txt

Just say what can be merged, and I'll do it. (or what can't)

This is still correct. I didn't say these changes must be merged ASAP :) First finish all the bugfixes/new features, then merge. So for the moment, you should not merge anything.

Michael.

Michael Schnell wrote

This is why I (rather unsuccessfully) tried to switch to DocView.

I'm not sure if you can follow instructions or not, but I give up trying to help you with that!

Graeme Geldenhuys wrote

On 23 January 2012 11:31, Michael Schnell wrote:>> This is why I (rather unsuccessfully) tried to switch to DocView. I'm not sure if you can follow instructions or not, but I give uptrying to help you with that!

Graeme, I wonder if I could ask one thing which is tangential to this since I think you were involved. At
http://wiki.lazarus.freepascal.org/Adding_Kylix_Help there is a description of adding helpfiles from Kylix to Lazarus, using HyperHelp.

If I understand things correctly, HyperHelp is closed-source, unmaintained, and available for x86 Linux only. Is there an alternative for other platforms such as Solaris or non-x86?

If I understand things correctly, HyperHelp is closed-source, unmaintained, and available for x86 Linux only. Is there an alternative for other platforms such as Solaris or non-x86?

At the time of Win3.0 I wrote an decompiler and viewer for WinHelp files, most probably using BC3. I could publish the source, provided that I find it <BG>, but I'm not sure whether it would help in making the viewer more portable.

DoDi

Graeme Geldenhuys wrote

I'm not sure if you can follow instructions or not, but I give up trying to help you with that!

Graeme,

I'm thankful for your effort to help me on that issue. And the recent message was (and the current one is) not meant to push you in any way.

IIRC the latest note I got from you on that behalf was (interpreted by myself) that you intended to do/update a script or program of some kind that is able (or configurable) to compile to *.inf files s all available help sources (i.e. fpc, rtl, lcl, ...) and publish same in somewhere in one of the the svns.

Thus (because I am not in a hurry) instead of trying to follow a complicated and error prone procedure (supposedly needing to ask you for help several times again), after my latest unsuccessful try to create lcl.inf, I waited for your ready message.

Thanks again,
-Michael

I certainly think it would be useful for the record.

Would it be possible to merge the most important fpdoc patches into 2.6?

Currently I cannot continue working on the FPDocManager, because the FPC 2.7 parser has been broken recently, and the FPC 2.6 tools have no DoLog capabilities. I can live without fpdoc projects, but not with tools that insists in outputting messages to stdout and stderr.

DoDi

fpGUI's Docview? ;-)
Docview (and the whole of fpGUI) is supported and tested on Linux, Windows, FreeBSD, DesktopBSD, OpenSolaris, WindowsCE and ARM/Linux. Unofficially it works on Mac OS X (via X11) and ReactOS (a Windows clone OS) too.

HyperHelp is a help viewer licensed by Borland to ship with Kylix. The original creators of HyperHelp has long gone out of business. The help format is proprietary too (it is not the same as WinHelp), but you can get a copy of the Kylix 3 help (which is on par with Delphi 7 help) and a copy of HyperHelp, by downloading the free version of Kylix 3 Open Edition and using my license key (for the open edition only of course, seeing that neither Borland nor Embarcadero can unlock Kylix 3 any more - the joys of closed source software).

http://opensoft.homeip.net:8080/wiki/wiki.cgi?p=kylix-3-open-edition

HyperHelp runs fine under 64-bit linux too (that is what I currently use).

Yes, but the point I'm trying to make is that those files are effectively locked out now for anybody unable to run HyperHelp, e.g. because they're not running on x86.

The nice thing about ReactOS is that your application does not need to support ReactOS, but the ReactOS devs want to support your app (in terms that it runs on Windows without problems of course).

Regards,
Sven

Mark Morgan Lloyd wrote

Yes, but the point I'm trying to make is that those files are effectively locked out now for anybody unable to run HyperHelp, e.g. because they're not running on x86.

True, it is x86 and x86-64 only. But to be fair, Kylix was only released for Linux and Intel based processors.

Indeed. But what that means is that anybody wanting to refer to the Kylix helpfiles on a non-x86 system will have problems. The only practical significance is that it's probably unwise for any of the FPC/Lazarus docs to simply say "works the same as Delphi/Kylix, qv": anything significant will have to be summarised.

Obviously this is a minor detail- nitpicking almost- since it assumes that people will still be running systems other than x86 in the future.

Why not simply use the CHM help?

Marco van de Voort wrote

Why not simply use the CHM help?

I think what he meant was, having the ability of reusing the Kylix help files, while Lazarus seriously lacks good / any documentation for the LCL. In the mean time, Lazarus developers could "piggy back" on the help content supplied by Kylix 3 (if they use Linux) or Delphi 7 (if they use Windows) [obviously only if they have a legal copy of each of those products]. At least the Kylix 3 help is easily obtained in a legal manner. And seeing that Lazarus's goal is to be a clone of Delphi VCL, this could work in a pinch.

In the case of Delphi 7 help, there is no "Open Edition" of Delphi, and the Delphi help was in WinHelp format, not CHM. And as far as I know, Lazarus doesn't support WinHelp format, but maybe a similar trick can be applied as was done for HyperHelp.

But to be honest, there are so many incompatibilities and differing behaviours between Delphi and Lazarus, that I don't really know how useful the VCL or CLX help will be. Reading the recent message threads, it seems they can't even agree how to compile and package the little LCL help content that is there.

Mark Morgan Lloyd wrote

But what that means is that anybody wanting to refer to the Kylix helpfiles on a non-x86 system will have problems.

And as I mentioned in another post, I don't know how much help CLX or VCL help files would really be to a LCL developer. LCL differs a lot from those frameworks. The best solution would be to get some serious LCL documenting done, and quality is a much harder task than one would imagine, but it should be done at some point.

Graeme Geldenhuys wrote

I don't know how much help CLX or VCL help files would really be to a LCL developer.

The Delphi help offers with nice hints for the language itself including context sensitive "F1" on language keywords like "array" or "class" or "override" and such.

I feel it would be nice to see this in the (fpDoc or other) help system (i.e. be able to "borrow" it).

-Michael

That was added some months ago for the chm help.

I feel it would be nice to see this in the (fpDoc or other) help system (i.e. be able to "borrow" it).

Mattias

Your information is seriously outdated, the LCL documentation is not nearly as incomplete as you say it is.

Nice !

What exactly is "That" ? How did it happen ? Did anybody write the help source code for the complete Language documentation ?

(Concentrating (with low priority) on trying to compile the fpDOC help from the latest sources, I never tried to do this for the CHM help, assuming the result would be very similar, while fpDOC offers better search features. In fact there seem to be no chm files in the svn distribution.)

-Michael

Graeme Geldenhuys wrote

In the case of Delphi 7 help, there is no "Open Edition" of Delphi,

In fact there was "Turbo Delphi" that came for free with a 100 Year license, but AFAIK, the download has been removed from the official website.

-Michael

Michael Schnell wrote

The Delphi help offers with nice hints for the language itself including context sensitive "F1" on language keywords like "array" or "class" or "override" and such.

I have already had this ability for years with DocView and INF help files. I simply told DocView which directory or help files to look at (eg FPC compiler guide, language ref, FCL etc, and LCL or fpGUI class docs). It takes 30 seconds to setup in Lazarus, MSEide, or even Delphi IDE itself.

See the following web page for details.

http://fpgui.sourceforge.net/docview_ide_integration.shtml

Felipe Monteiro de Carvalho wrote

Your information is seriously outdated, the LCL documentation is not nearly as incomplete as you say it is.

So how much has changed since 1-2 months ago, when I last looked at it? Then most units, class and methods still missed a crap load of docs.

But, I'll pull another update and regenerate the docs to compare. Thanks for the note.

Michael Schnell wrote

(Concentrating (with low priority) on trying to compile the fpDOC help from the latest sources, I never tried to do this for the CHM help, assuming the result would be very similar, while fpDOC offers better search features. In fact there seem to be no chm files in the svn distribution.)

I assume by you referring to "fpDOC" you actually mean DocView? "fpdoc" is a program included with FPC that generates class documentation from source code and XML description files.

If my assumption was correct, please try and get the product names correct in future to prevent confusion.

Sorry :(
Thanks,
-Michael

Graeme Geldenhuys wrote

http://fpgui.sourceforge.net/docview_ide_integration.shtml

Of course I do know how to integrate DocView in the IDE. and already did this for the Lazarus IDE. It works just fine.

The question was if/how it (or another help viewer) can display Language Help that - if not available in help source files - might be "imported" from Kylix or Delphi 7.

-Michael

That is obviously a valid point, but when I started this subthread I was simply trying to point out that one of the courses of action in the wiki (Graeme's suggestion to assimilate the Kylix files) might not be useful due to platform constraints.

Noted. However since I usually build Lazarus from source (no binary distro for some of the systems I run, or I need a specific compiler version from SVN) is there an idiot's guide somewhere for how to get and integrate the latest docs? And what can be done to get as many users as possible aware of this?

Maybe. But this should not be recommended. It is escapism (and of legal uncertainty).

And certainly it is crazy to start developing to support that heavily aging mess.

At least the Kylix 3 help is easily obtained in a legal manner.

How so? Is it licensed for use without Kylix at all then?

Moreover, IMHO 3rd party devels doing this is their business, but IMHO FPC/Lazarus shouldn't be recommending this kind of stuff (and IMHO the wiki article should disappear)

And seeing that Lazarus's goal is to be a clone of Delphi VCL, this could work in a pinch.

IMHO it is a step backwards.

In the case of Delphi 7 help, there is no "Open Edition" of Delphi, and the Delphi help was in WinHelp format, not CHM.

Afaik CHMs for all recent versions are on the FTP server, the question, as with Kylix is their doubtful legal status.

Same problem, individual people doing it is probably not a problem, but IMHO the Lazarus/FPC projects should not be advocating this. Specially not when they formally have cleanroom policies in place.

And as far as I know, Lazarus doesn't support WinHelp format, but maybe a similar trick can be applied as was done for HyperHelp.

Winhelp is RTF based.

It still gets the primary gist. But I prefer to get such info from public sources on the internet, and not directly from Embarcadero sources.

Graeme Geldenhuys wrote

So how much has changed since 1-2 months ago, when I last looked at it? Then most units, class and methods still missed a crap load of docs.

It is easy to drop generic comments. Where are the concrete examples of concrete classes / units?

I certainly agree that it is escapism. But back in the day (3 to 5+ years back) LCL had zero documentation, FPC CHM files did not exist, and neither did DocView or the FPC INF help files. Then, using the Kylix 3 help files was immensely useful.

Oh, and I am a legal and registered owner of Kylix 3 Open Edition, Kylix 3 Professional and Kylix 3 Enterprise. So what I do with Kylix in my personal capacity is my right.

As for me giving out my Kylix 3 Open Edition license key... I emailed Borland and Embarcadero regarding the registration problem with Kylix 3 OE, and made my intent clear. There official answer was they have no way of registering new Kylix 3 OE users, even though Kylix 3 OE is freely available for download from various location on the internet, and even though there are Kylix 3 OE based projects on SourceForge (thus now stuck because no new Kylix users can register and use Kylix). I did publish their reply to some Kylix newsgroups - Google should be able to find that. I welcome Borland or Embarcadero to send me a letter regarding my K3 OE license key. I'll give them another mouth full about how bad this "must register your product online to use it - even though the product is free for all" idea is.

And certainly it is crazy to start developing to support that heavily aging mess.

By no means did I imply that Lazarus must now support HyperHelp file formats.

> At least the Kylix 3 help is easily obtained in a legal manner. How so? Is it licensed for use without Kylix at all then?

See above. Anybody is allowed to download and use Kylix 3 Open Edition
- it was released for the open source community. When you download that, you get a copy of the K3 help too.

Moreover, IMHO 3rd party devels doing this is their business, but IMHO FPC/Lazarus shouldn't be recommending this kind of stuff

I'm not a FPC or Lazarus core developer. ;-)

> seeing that Lazarus's goal is to be a clone of Delphi VCL, this could work > in a pinch. IMHO it is a step backwards.

Maybe that is true now, now that we have INF help files, CHM help files, and that work is actually being done to document LCL. But 5+ years ago, Kylix 3's HyperHelp was the only way to get context sensitive help in Lazarus IDE.

the Lazarus/FPC projects should not be advocating this. Specially not when they formally have cleanroom policies in place.

Just to make it clear, I am also not implying that the Kylix 3 Help content must be copied into the Lazarus LCL help.

> know, Lazarus doesn't support WinHelp format, but maybe a similar > trick can be applied as was done for HyperHelp. Winhelp is RTF based.

See above. I did not imply copying Kylix's help text.

Felipe Monteiro de Carvalho wrote

Where are the concrete examples of concrete classes / units?

View http://lazarus-ccr.sourceforge.net/docs/lcl/index.html

There are still quite a few units even without descriptions.

Then view something like
http://lazarus-ccr.sourceforge.net/docs/lcl/spin/tspinedit.html The unit might have a description, but the TSpinEdit class has only one property with a description. The other 35 properties have nothing.

But I must admit, randomly clicking through some units, it does seem like LCL help has improved a lot in recent times.

Graeme Geldenhuys hat am 26. Januar 2012 um 15:26 geschrieben:

That's because fpdoc does not automatically use/link the documentation of the inherited/ancestor identifier.
For example the fpdoc editor shows that TControl.Align is documented and the IDE hint shows that hint.

@Michael: Is that feature planned or should links be set manually in all elements?

But I must admit, randomly clicking through some units, it does seem like LCL help has improved a lot in recent times.

:)

Mattias

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120126/17e1a594/attachment.html>

What do you have against FPC's language help? It's rather complete and if something is wrong or missing Michael is usually fast in fixing it if you tell him.

Regards,
Sven

I was not aware that it does exist, as I was not yet able to see it and not knowing about it's existence did not try hard enough to find/install it.

Thanks,
-Michael

Graeme Geldenhuys wrote

But, I'll pull another update and regenerate the docs to compare.

It would be great if we were able to regenerate all the the (Docview-) help files ourselves using a procedure for dummies. Thanks,

-Michael

While I suppose this is the right answer to the question, previously discussed was _language_ help rather than LCL herl (such as "for", "in", "array", "class", ...)

-Michael

Have you ever been on the FPC website ??

The 'Documentation' button is rather prominent, I hope :-)

Michael.

hat am 26. Januar 2012 um 17:17 geschrieben:

if

>> something is wrong or missing Michael is usually fast in fixing it if

you

>> tell him. >> > I was not aware that it does exist, as I was not yet able to see it and

not

> knowing about it's existence did not try hard enough to find/install

it.

Have you ever been on the FPC website ?? The 'Documentation' button is rather prominent, I hope :-)

Indeed.
With this document I started programming in FPC.

Mattias
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120126/888b724d/attachment.html>

Graeme Geldenhuys wrote

Then view something like http://lazarus-ccr.sourceforge.net/docs/lcl/spin/tspinedit.html The unit might have a description, but the TSpinEdit class has only one property with a description. The other 35 properties have nothing.

This page is not up to date. And sometimes a property has no top-level short description because it is only a link as it was described elsewhere already. Unfortunately fpdoc is not clever enough to copy the top-level short description when linking too, so we have to manually copy it everywhere.

Mattias Gaertner wrote

That's because fpdoc does not automatically use/link the documentation of the inherited/ancestor identifier.

Ah, ok.

@Michael: Is that feature planned or should links be set manually in all elements?

I actually implemented that some time ago for fpdoc IPF output (the help source for binary INF files). It is controllable via an extra parameter (--duplinkeddoc), but off by default. There was a reason why it was not enabled by default or for all (or most) fpdoc output formats, but I can't remember what that reason was. I'll have to search my email conversations with Michael to find out. Michael, can you remember?

Sven Barth wrote

What do you have against FPC's language help? It's rather complete and if something is wrong or missing Michael is usually fast in fixing it if you tell him.

I agree, the FPC documentation is very good. There are some topics that could still be extended (Interfaces, Assembly, Generics etc), but overall the FPC docs are great.

How did you know know about it? It's been available since forever...

PDF & HTML versions (PDF is the only official docs) http://www.freepascal.org/docs.var

CHM versions
Macro posts a link every now and again in the mailing lists

INF versions
http://sourceforge.net/projects/fpgui/files/fpGUI/Documentation/

Nearly completed Language Ref - that's if I ever get the time to work on it. I'm doing a manual conversion from PDF (Latex) to INF, because any auto-conversions looked crap (like the ref.chm - sorry Macro but it's true)

[oops, the reply went directly to Michael Schnell for some reason]

---------- Forwarded message ----------

That is the official online LCL help url is it not?

PS:
It would also be very helpful if whoever generates the help for that URL, includes the fpdoc --footer-date=yyyy-mm-dd option, so then we all would know how recent that online documentation is. As the fpdoc parameter name says: it will add the "docs generate on <date>" in the HTML footer output.

Michael Schnell wrote

discussed was _language_ help rather than LCL herl (such as "for", "in", "array", "class", ...)

That's exactly what the "Free Pascal Language Reference" document describes.

You really should visit the Free Pascal website. :)

I'd suggest that having online documentation, while essential, is hardly a substitute for being able to access it from the IDE when offline or blessed with variable network latency. And it's absolutely no substitute for the context-sensitive help offered by most IDEs.

Lazarus and the textmode IDE both provide context sensitive help. (CHM based)

Graeme Geldenhuys wrote

http://www.freepascal.org/docs.var CHM versions Macro posts a link every now and again in the mailing lists

That's the snapshot. I usually post it to lazarus lists since it also contains LCL docs.

The formal release archive is on the Docs download page:

http://www.freepascal.org/down/docs/docs-netherlands.var

Nearly completed Language Ref - that's if I ever get the time to work on it. I'm doing a manual conversion from PDF (Latex) to INF, because any auto-conversions looked crap (like the ref.chm - sorry Macro but it's true)

Probably a matter of taste. For me the docview interface is also limited and confusing.

Am 26.01.2012 19:21 schrieb "Mark Morgan Lloyd" <

if something is wrong or missing Michael is usually fast in fixing it if you tell him.

>>> >> I was not aware that it does exist, as I was not yet able to see it and

not knowing about it's existence did not try hard enough to find/install it.

a substitute for being able to access it from the IDE when offline or blessed with variable network latency. And it's absolutely no substitute for the context-sensitive help offered by most IDEs.

You are aware that Lazarus also supports offline help? It just needs to be configured as it's not enabled by default... (which indeed might not be good, at least on "zero configuration" targets like Windows, but there is a bug report about this already)

Regards,
Sven
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120126/f9eb0ce5/attachment.html>

Right. So as I said earlier: where's the idiot's guide to getting the up-to-date files and putting them where they'll do most good, and what can be done to make sure that people hitting Google or the wiki sees those instructions?

That should not be a problem, IMO nowadays HTML with CSS offers the same support - except for platform specific items like calling DLL functions.

Microsoft had more problems with Word, where every new version created differently buggy RTF, so that a new help compiler was required for every new version of Word :-]

IMO D7 help still is the most complete and reliable Delphi documentation, it's only slightly outdated after introduction of Unicode strings, generics etc. Embarcadero missed to import these contents into the new HTML (HH2) help system, which had to be choosen for including help on/from .NET.

DoDi

You mean to say that there actually are idiots using Lazarus ? ;-)

Michael.

> Right. So as I said earlier: where's the idiot's guide to getting the > up-to-date files and putting them where they'll do most good, You mean to say that there actually are idiots using Lazarus ? ;-)

Most users must feel like idiots, when they are unable to figure out how to obtain context sensitive help at all, or using local files. The same for the configuration of the FPDoc Editor. Creating own helpfiles is a secret, too :-(

IMO it's not sufficient to supply mystic scripts without documenting their use, like for the FPC documentation Makefile, or the LCL build thingies.

DoDi

Michael Van Canneyt schrieb: [...] Most users must feel like idiots, when they are unable to figure out [...] for the configuration of the FPDoc Editor.

What do you mean?
There are only search paths. And the "Create" button even create those for you.

Mattias

Which "Create" button?

DoDi

Mark Morgan Lloyd wrote

where's the idiot's guide to getting the up-to-date files and putting them where...

Regarding that it's me who is the said idiot (or the advocate for the idiotic users), I'd like to add, that the end result should be to allow the idiots to push F1 (or shift F1 for an external tool like DocView) in the IDE to get context help for the word under cursor, might same be be a language keyword (e.g. "array"), an RTL generated keyword (e.g. TThread), or an LCL generated keyword (e.g. TForm). Of course additionally when not in a Source code window, help on the IDE itself should appear.

I understand that on top of generating the dedicated help files from the current sources, for this it is necessary to generate combined CHM files or multiple inf-Files for DocView. This needs to be included in the "idiot's guide".

-Michael (provided this done I promise to improve the help sources on "TApplication.QueueAsyncCall", as intended since many months)

Hans-Peter Diettrich wrote

Creating own helpfiles is a secret, too :-(

Good point. The script provided by the "idiot's guide" should be extendable for additional sources. Of course for this it the guide needs to provide documentation on the format of the help sources.

-Michael

Sven Barth wrote

You are aware that Lazarus also supports offline help?

Yep. The discussion is on how to generate the offline help from the current svn sources and on the features of the help viewer (IDE or external tool).

-Michael

On the FPDoc Editor, first page, below the short description, hard to miss.

Mattias

Graeme Geldenhuys wrote

INF versions http://sourceforge.net/projects/fpgui/files/fpGUI/Documentation/

OK. I downloaded the zip files, located the newest versions (in docs_2011.zip) and created symlinks to have DocView find them.

Nearly completed Language Ref - that's if I ever get the time to work on it. I'm doing a manual conversion from PDF (Latex) to INF, because any auto-conversions looked crap (like the ref.chm - sorry Macro but it's true)

Still a lot of unusable paragraphs, but still a lot better than nothing. Nonetheless if it would be possible top convert the Kylix (or Turbo Delphi) files, this might be useful, to.

-Michael

The readme in the relevant docs-chm archive?

and what can be done to make sure that people hitting Google or the wiki sees those instructions?

The current situation is a result of competing help formats. This made developers wary of choosing one over the other as "default" format.

Michael Schnell wrote

Nonetheless if it would be possible top convert the Kylix (or Turbo Delphi) files, this might be useful, to.

Not by me, because they are probably all copyright by Borland / Embarcadero. And as I said before, the FPC docs are great already - so use them instead.

.... and so did latex 15 years ago, but we still struggle today to convert them into eachother :-)

Two languages having capabilities and automatic convertability into eachother are totally different problems.. (another example: C headers and Pascal)

If you still use D7, then probably yes :-). If you don't ( and I haven't for a long time), it is outdated. So say for instance you are doing simple stuff like splitting a string into pieces and you run into the "space is always separator problem". The D7 help won't tell you that got finally fixed in D2006 with a strictdelimiter property :-)

Graeme Geldenhuys wrote

Michael, can you remember?

Do you mean this ?

http://mantis.freepascal.org/view.php?id=20318

-Michael

Michael Schnell wrote

Do you mean this ? http://mantis.freepascal.org/view.php?id=20318

No, it was long before that.

Maybe the chmhelppkg.lpk can add some hints to the IDE? Or maybe even a small dialog to run the scripts and create the chm files?

> and what can be done to make sure that people hitting Google or the wiki > sees those instructions?

Google for "lazarus chm" already gives as top hits all the wiki pages. And they contain links to each other.

The current situation is a result of competing help formats. This made developers wary of choosing one over the other as "default" format.

Evidently the competition has pushed the help formats.

Mattias

Yep and with your manual conversion "array" does provide a DocView context help. but... (see attached picture)

...

Maybe the mail with the picture does not come through. In fact all you see is unreadable text maybe due to UTF conversion or similar.

-Michael

Look, I'm not trying to be a pain in the butt here but in front of me I've got Lazarus 0.9.31. I go to the menu and hit "Help": it fires up a browser and takes me to online help. Nowhere there does it say anything about docs-chm.

I hit F1 over a reserved word, it brings up a dialogue complaining about a missing file. Nowhere there does it say anything about docs-chm.

I usually build Lazarus from source, downloading from svn. Nowhere there does it say anything about docs-chm, or it certainly said nothing when I started working like that four or five years ago.

So I go to http://www.freepascal.org/ and there's online documentation, or PDFs etc. Nothing to integrate with Lazarus.

So I go to http://lazarus.freepascal.org/. There's no online documentation. So I go to the bottom of the downloads page... and so on.

Now it's pretty clear that people /are/ working on documentation etc., but it's also pretty clear that Lazarus is perceived as not being well-documented- and that's to its detriment. Noting Marco's

The current situation is a result of competing help formats. This made developers wary of choosing one over the other as "default" format.

but with respect to everybody I think that the project is being harmed by its perceived lack of documentation, and getting /something/ useful to appear when a naive user expects it is going to be far more useful than having every last detail of layout and hypertextual linkage sorted to perfection.

Michael Schnell wrote

Yep and with your manual conversion "array" does provide a DocView context help. but... (see attached picture)

A known problem, and you would have know about this too if you opened the ref.inf file on it's own - the first help topic explains this (the text in RED on the cover page).

The fix:
-------
In the top right of DocView, change the Text Encoding combobox from CP850 to UTF-8. Your text will now look fine.

The longer explanation:
----------------------------------
The original IBM ipf compiler used code pages - Unicode was non-existent, or in its infancy. The OpenWatcom IPF compiler is more lenient regarding the ipf text it processes. So creating ipf text using UTF-8 is allowed. Unfortunately the OpenWatcom IPF Compiler doesn't yet set the INF header info to say the text is UTF-8 encoded, thus it defaults to CP850. I did file a bug report / feature request but don't know how long it will take before it is implemented. DocView doesn't try any text magic, it simply reads the text encoding setting inside the INF file and uses that (which is the correct thing to do).

I am busy writing my own IPF Compiler in Object Pascal, which will definitely have this fixed, plus a few other features. DocView will then automatically detect the correct encoding for each INF file.

Yes, I could have written the FPC Language Ref doc in CP850, but Unicode has much nicer glyphs for text drawings. The Language Ref doc has lots of text syntax diagrams (unlike the PDF docs - I didn't opt to use image for those syntax diagrams).

Graeme Geldenhuys wrote

A known problem, and you would have know about this too if you opened the ref.inf file on it's own - the first help topic explains this (the text in RED on the cover page).

Wow !
UTF sucks whenever you come across it :( .

The fix: ------- In the top right of DocView, change the Text Encoding combobox from CP850 to UTF-8. Your text will now look fine.

This is obvious for the non-blind, but silly me did not see.

I am busy writing my own IPF Compiler in Object Pascal, which will definitely have this fixed, plus a few other features. DocView will then automatically detect the correct encoding for each INF file.

GREAT (as already said :) )

Yes, I could have written the FPC Language Ref doc in CP850, but Unicode has much nicer glyphs for text drawings. The Language Ref doc has lots of text syntax diagrams (unlike the PDF docs - I didn't opt to use image for those syntax diagrams).

Regarding the upcoming IPF compiler: Don't bother !

Of course (given that this is "help" and help is only necessary for dummies and the idiots that keep forgetting stuff) it would be great if this step could somehow be automated.

Thanks,
-Michael

Michael Schnell wrote

> A known problem, and you would have know about this too if you opened > the ref.inf file on it's own - the first help topic explains this (the > text in RED on the cover page).

Please note I did not mean this rude. You did use DocView via IDE integration, so DocView opens multiple files, and nobody would have seen that UTF-8 notice.

Of course (given that this is "help" and help is only necessary for dummies and the idiots that keep forgetting stuff) it would be great if this step could somehow be automated.

I tried various possible solutions - none to my satisfaction. I guess I could hard-code DocView to use UTF-8 when a 'ref.inf' file is loaded, but that will just be a ugly hack. You also can't force DocView to always use UTF-8, because then other INF files which use CPxxx encodings will display incorrectly. So I opted to put a RED notice on the cover page of the ref.inf file. :)

I'll add a note about this problem to the IDE Integration [fpGUI] web page. Hopefully that will help others. Thanks for bringing this to my attention - I'm so used to flipping the text encoding combobox, I don't even notice I'm doing it any more.

You missed the point :-(

Look at the Options > FPDoc Editor page, where the user has to add the search paths, and tell us what a user has to enter there.

DoDi

I understand that on top of generating the dedicated help files from the current sources, for this it is necessary to generate combined CHM files or multiple inf-Files for DocView. This needs to be included in the "idiot's guide".

Did you have a look at examples/FPDocManager?

DoDi

I added a note about offline help with chmhelp and docview. Maybe the mainainers can give me a short sentence or link for each help viewer. So people know where to start.

I hit F1 over a reserved word, it brings up a dialogue complaining about a missing file. Nowhere there does it say anything about docs-chm.

I could add some hints. Here I need a sentence from the help viewer maintainers too.

True. "Integration" is not the goal of this kind of documentation.

So I go to http://lazarus.freepascal.org/. There's no online documentation.

It's called "Wiki".

[...]

Mattias

Hans-Peter Diettrich wrote

Did you have a look at examples/FPDocManager?

This does not seem to make sense for me until I know a proven method to generate the data for some help viewer, integrated in the IDE, that works on the combined information of current stuff and new additions.

-Michael

Normally: nothing.
If you like: you can add the path to the fpcdocs.

Mattias

Graeme Geldenhuys wrote

(the text in RED on the cover page).

FYI: This page is selected when starting DPDOC, but the content is not displayed. It is only shown when clicking another chapter and then re-cklicking the chapter.

Maybe easy to be improved...

-Michael

Graeme Geldenhuys wrote

So I opted to put a RED notice on the cover page of the ref.inf file.

I see. No problem regarding we certainly will see improvements when your IPF compiler is ready.

Regarding visibility of the red text see my other mail.

-Michael

But I'm tempted to say that it should be the goal of the IDE. In fact now that I think about it...

> So I go to http://lazarus.freepascal.org/. There's no online > documentation. It's called "Wiki".

One suggestion if I may. The target URL of the IDE's "Help -> Online Help" menu entry doesn't have to be the same as that put up on the website. It might be useful if the target page were to display a choice:

* Stable online documentation for the version of FPC/Lazarus detected.

* Suggestions as to how one of the available viewers can be set up to use these files locally.

* A pointer to somewhere- a (not necessarily the) wiki- where documentation is currently being edited so that a user can see if there has been recent clarification of something that's giving him problems.

Mattias Gaertner wrote

I added a note about offline help with chmhelp and docview.

Where?

Maybe the mainainers can give me a short sentence or link for each help viewer. So people know where to start.

Like this page for DocView...
http://fpgui.sourceforge.net/docview_ide_integration.shtml

I would suggest mentioning some wiki page with a hyperlink. Then that wiki page could elaborate further and point them to all the available choices.

Michael Schnell wrote

FYI: This page is selected when starting DPDOC, but the content is not

What is DPDOC?

displayed. It is only shown when clicking another chapter and then re-cklicking the chapter.

Sorry I can't reproduce it here. Would you mind sending me a private message elaborating on the exact steps I need to take to reproduce this problem.

It's hard to integrate something that is not part of the Lazarus sources, contains several different structures (keywords, identifiers, messages, directives, topics and chapters, tools) and comes in various versions. Each structure needs an index, then an offline format, then a viewer and a solution to the various versions.
As long as creating the offline format costs so much time, you can not do that on the fly. IMO that problem must be solved. Otherwise only binary packages and indexed online pages can provide instant help. Hopefully the chm and docview developers will eventually provide a solution to create the content on the fly or at least on demand.

What is a "Stable online documentation"?

* Suggestions as to how one of the available viewers can be set up to use these files locally.

Yes. I'm waiting for some notes.

* A pointer to somewhere- a (not necessarily the) wiki- where documentation is currently being edited so that a user can see if there has been recent clarification of something that's giving him problems.

That heavily depends on the type and area of docs. A list of pointers is needed.

Mattias

The default help page of the IDE.
It is shown for example when you click on Help / Online Help. It simply shows docs/index.html.

Yes, I used that.
But it does not mention where to get the inf files.

Do you have one?

Mattias

Mattias Gaertner wrote

It simply shows docs/index.html.

OK, thanks.

But it does not mention where to get the inf files.

3rd paragraph in that page.

"If you don't have DocView yet, you can compile DocView yourself from the fpGUI source code, or opt to download pre-built binaries of DocView and various INF documentation, by visiting this [link]."

Do you have one?

No, I didn't create such a wiki page.

I already had to add several paths, to e.g. the widgetset(s) and IdeIntf. Is this a missing fpdoc directory in the packages, or what else requires to add these directories manually?

Or the other way round: what makes the FPDoc Editor look into the right directory, when no explicit path is given?

DoDi

My installation shows a local copy of that page, which obviously is outdated. How that? What's required to get the online version?

DoDi

The package IDEIntf has its own fpdoc path. It is 'docs', which is relative to the ideintf.lpk, so the fpdoc files are in /path/to/lazarus/ideintf/docs.
It works here. I can see and edit help for formeditingintf.pas ComponentPaletteImageWidth.

Analog for the LCL which contains the widgetsets.

Or the other way round: what makes the FPDoc Editor look into the right directory, when no explicit path is given?

The search works as following:
First it searches for the declaration of the identifier. Then it searches for the owner of the unit (e.g. a package) If the package has a fpdoc path, an unitname.xml is searched. Finally if the global fpdoc path is set, an unitname.xml is searched there.
The hint and fpdoc editor searches for the ancestors of the identifier too.

Hint: Update to 34980 and you can now see which fpdoc file is used in the source editor / popup menu / open file. If there is no xml file, then no fpdoc file was found.

ToDo: implement something to use the docs of a newer Lazarus Version and newer package versions, where the units may have different owners and paths. Maybe a file with a list of some information like: for the ideintf.lpk version 1.0.0 to 1.0.2, use fpdoc search path xyz, and a list of unit aliases.
The IDE should be able to load several of these files, so that third party packages can use that feature too.

Mattias

Obviously?

How that? What's required to get the online version?

docs/index.html is local.
It gives some hints where to find help online.

Matias

What's the "global fpdoc path"?

A good idea for help writers :-)

For units inside the Lazarus directory all package documentation could reside in subdirectories of docs/, by default. Projects and third-party packages could use a docs/ subdirectory of the directory containing the package/project file. IMO users would be happy with such a default search path, before they start to invent their own locations.

What about translations? I've asked this question already, some time ago, with no response. There seem to exist no activities to translate the Lazarus docs?

DoDi

It doesn't contain above note :-(

> How that? What's required to get the online version? docs/index.html is local. It gives some hints where to find help online.

Thanks, that explains a lot :-)

Could we add links to local documentation, when installed on a machine?

DoDi

I meant the IDE options.

You lost me here.
How does that solve the renamed/moved unit problem?

What about translations? I've asked this question already, some time ago, with no response. There seem to exist no activities to translate the Lazarus docs?

The wiki has some busy translators.
For the fpdoc files: AFAIK none.

Mattias

[...] Could we add links to local documentation, when installed on a machine?

For example?

Mattias

Where do I select the version? So that I get the right help for my (slightly outdated) version?

You mean the explicitly given fpdoc editor paths?

I don't see the problem yet :-(

When the Lazarus LCL and LCLBase packages already are documented together, in the fpdoc "lcl" package, moving units should not be a problem? Renamed units deserve special actions, both in the repository and XML files, of course; this is up to the person which does the rename, isn't it?

When the XML files are under version control, every Lazarus version (release branch), package or project version will include the appropriate docs and paths. Only the server for the online docs should know about the package/product version, for which help is requested.

Here I can see a version problem, since the wiki isn't aware of versions, by himself - the contributors must be aware of! One of the reasons why I don't like the wiki :-(

For the fpdoc files: AFAIK none.

One problem less ;-)

DoDi

For when the user is e.g. offline, or has locally modified/updated the documentation.

I understand that CHM help will always(?) use the local files, but even then differences may exist between the downloaded and locally generated docs.

DoDi

You don't have to select. The wiki pages tell when something was added or changed.

Mattias

I meant: What should be written in docs/index.html?

Mattias

>>> Could we add links to local documentation, when installed on a machine?

[...]

I meant: What should be written in docs/index.html?

A link to the local docs directory could be added.

HTML files are read/write <g>, and a unique marker in it allows to insert the link without parsing the file.

Perhaps easier: Add an "Offline Help" menu item to the IDE, leading to the local (CHM) directory.

DoDi

Do you mean the IDE should alter the page on the fly? The IDE starts a browser and points it to docs/index.html.

Perhaps easier: Add an "Offline Help" menu item to the IDE, leading to the local (CHM) directory.

Mattias

It's sufficient to update the file on every change to the document path in the IDE Options form.

DoDi

The file is in svn and installed read only.

Mattias

> It's sufficient to update the file on every change to the document path > in the IDE Options form. The file is in svn and installed read only.

Nothing that could not be changed?

But my second solution looks easier to implement anyway.

DoDi

Dear friends:

i have an unusual problem: i have prepared a simple application to edit a TDbf table.

now i have two forms only and when i execute the exe file the first works well, but when i try to continue, then the second one appear and the application terminate in miliseconds.

really, it is the first time i have this anormal behavior. I will appreciate any suggestion to solve this.

thanks in advance,

Ing. H?ctor F. Fiandor Rosario

On Sun, Feb 12, 2012 at 18:01, Ing. H?ctor F. Fiandor Rosario <

There might be two or three reasons for this that you can check very fast. First try to open the project file and see how the Application.CreateForm used. It might be the only answer you require.

If that is not the case, more details how you work can help us help you.

Ido

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120212/df2c5943/attachment.html>

dear friends:

i have resolved the problems: the name of the folder where the programs were saved have "spaces between".

i name it with an only word and then fine compile.

thanks very much.

Ing. H?ctor F. Fiandor Rosario

If you're using Lazarus, then you're asking in the right place. But if you step back from your problem for a moment then you'll see that you've given us absolutely no useful information to try to diagnose what's happening. Link below might help.

http://catb.org/esr/faqs/smart-questions.html