Sign in Join

Live chat for Free Pascal, Lazarus, Delphi and every Pascal programmer.

Mailing lists / lazarus / 2011-07

trying to enhance the lcl help file

19 messages · 7 people · –

Reply by email Subscribe to this list Your subscription

Read-only archive. Use j and k to move between messages.

Michael Schnell

Hi help experts :-)

Graeme suggested that I should enhance the lcl help on QueuAsyncCall.

So I am trying to do so.

Of course I need to see what I did and thus Greame suggested that I should install the new "DocView" online help for this from the current svns.

With Graemes helpI was able to install DocView as an external tool in Lazarus.

I was able to create the *.inf files for "rtl" and "fcl" from the source files found ion the svn.

I made an old lcl.inf file known to Docview.

Now with Docview in Lazarus I can see and search for "rtl", "fcl", and "LCL - the Lazarus Component Library".

* - (it would be nice if "rtl" and "fcl" would show a decent header, as well)*

I tried to create the lcl.inf file from the svn sources.

but I get this:
------------------------------------------------------------------------ mschnell at mschnell-Linux:~/Downloads/svn/lazarus/trunk/docs/html> ./build_lcl_docs --outfmt ipf
Warning! No corresponding xml file for unit forms/forms.pp FPDoc - Free Pascal Documentation Tool
Version 2.5.1 [2011/07/13]
(c) 2000 - 2003 Areca Systems GmbH / Sebastian Guenther,

[#lcl.Controls.TAlign] Invalid paragraph content
[#lcl.Controls.TDockManager.InsertControl] Invalid paragraph content [#lcl.Controls.TDockManager.SetReplacingControl] Invalid paragraph content [#lcl.Controls.TDragManager] Invalid paragraph content [#lcl.Controls.TDragManager.Create] Invalid paragraph content [#lcl.Controls.TDragManager.RegisterDockSite] Invalid paragraph content [#lcl.Grids.HowToUseGrids] Invalid table content
[#lcl.Grids.HowToUseGrids] Invalid description (illegal XML element: "#text")
[#lcl.Grids.HowToUseGrids] Invalid description (illegal XML element: "var") [#lcl.Grids.HowToUseGrids] Invalid description (illegal XML element: "#text")
[#lcl.Grids.HowToUseGrids] Invalid description (illegal XML element: "var") [#lcl.Grids.HowToUseGrids] Invalid description (illegal XML element: "#text")
[#lcl.Grids.HowToUseGrids] Invalid description (illegal XML element: "var") [#lcl.Grids.HowToUseGrids] Invalid description (illegal XML element: "#text")
[#lcl.Grids.HowToUseGrids] Invalid description (illegal XML element: "link") [#lcl.Grids.HowToUseGrids] Invalid description (illegal XML element: "#text")
[#lcl.Grids.HowToUseGrids] Invalid description (illegal XML element: "b") [#lcl.Grids.HowToUseGrids] Invalid description (illegal XML element: "#text")
[#lcl.Grids.HowToUseGrids] Invalid description (illegal XML element: "b") [#lcl.Grids.HowToUseGrids] Invalid description (illegal XML element: "#text")
exception at 06C9C011:
Access violation.
------------------------------------------------------------------------ This obviously is due to a bug in grids.xml.

So I renamed grids.xml and I can do build_lcl_docs: ------------------------------------------------------------------------ mschnell at mschnell-Linux:~/Downloads/svn/lazarus/trunk/docs/html> mv ../xml/lcl/grids.xml ../xml/lcl/grids.xml_original mschnell at mschnell-Linux:~/Downloads/svn/lazarus/trunk/docs/html> ./build_lcl_docs --outfmt ipf
Warning! No corresponding xml file for unit /grids.pas Warning! No corresponding xml file for unit forms/forms.pp FPDoc - Free Pascal Documentation Tool
Version 2.5.1 [2011/07/13]
(c) 2000 - 2003 Areca Systems GmbH / Sebastian Guenther,

[#lcl.Controls.TAlign] Invalid paragraph content
[#lcl.Controls.TDockManager.InsertControl] Invalid paragraph content [#lcl.Controls.TDockManager.SetReplacingControl] Invalid paragraph content [#lcl.Controls.TDragManager] Invalid paragraph content [#lcl.Controls.TDragManager.Create] Invalid paragraph content [#lcl.Controls.TDragManager.RegisterDockSite] Invalid paragraph content Done.
------------------------------------------------------------------------ After a new checkout, something similar happens with lclintf.xml*

- I suggest that someone more knowlageable take s
and lclintf.xml*

This generates an lcl/lcl.ipf file (6.8 MB).

Now, trying to create the lcl.inf file, I get:
------------------------------------------------------------------------ mschnell at mschnell-Linux:~/Downloads/svn/lazarus/trunk/docs/html> export WIPFC=/home/mschnell/Downloads/svn/fpGUI/tools/wipfc/ mschnell at mschnell-Linux:~/Downloads/svn/lazarus/trunk/docs/html> cd lcl mschnell at mschnell-Linux:~/Downloads/svn/lazarus/trunk/docs/html/lcl> wipfc -i lcl.ipf
Open Watcom OS/2 Help Compiler Version 2.0beta1 Limited Availability Copyright (c) 2010 Open Watcom Contributors. All Rights Reserved. Source code is available under the Sybase Open Watcom Public License. See http://www.openwatcom.org/ for details.
<lcl.:290250:20> Warning 53: Invalid tag nesting
<lcl.:290250:20> Warning 23: The tag, word, or command is not allowed in this context
<lcl.:290256:20> Warning 53: Invalid tag nesting
<lcl.:290256:20> Warning 23: The tag, word, or command is not allowed in this context
<lcl.:290328:1> Warning 53: Invalid tag nesting
Segmentation fault
------------------------------------------------------------------------

* - What can I do to create an lcl.inf file, so that I can verify that my future patches to an lcl help xml file do work ? *

Thanks,
-Michael

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

Reply by email

Graeme Geldenhuys
to Michael Schnell
Michael Schnell wrote 7 lines
[#lcl.Controls.TDragManager.RegisterDockSite] Invalid paragraph content [#lcl.Grids.HowToUseGrids] Invalid table content [#lcl.Grids.HowToUseGrids] Invalid description (illegal XML element: "#text") [#lcl.Grids.HowToUseGrids] Invalid description (illegal XML element: "var") [#lcl.Grids.HowToUseGrids] Invalid description (illegal XML element: "#text")

Note:
These are are not specific to IPF output. Generating LCL help for HTML, CHM, TXT etc all give these "invalid description" errors in grid.xml. On my system, fpdoc steams ahead and generates the help output - no matter the output format. But as suggested to Michael Schnell, there seems to be something wrong in the XML file, or maybe fpdoc parsing of the description element.

Show quoted text 7 lines
<lcl.:290250:20> Warning 53: Invalid tag nesting <lcl.:290250:20> Warning 23: The tag, word, or command is not allowed in this context <lcl.:290256:20> Warning 53: Invalid tag nesting <lcl.:290256:20> Warning 23: The tag, word, or command is not allowed in this context <lcl.:290328:1> Warning 53: Invalid tag nesting

Michael, as I mentioned, this is due to a bug in fpdoc's IPF writer. I'll attend to this shortly. In the mean time you have to manually fix lines 290250, 290256 and 290328 by placing the tag ":h3." (if I remember correctly) on a new line. WIPFC should then be able to compile lcl.ipf without errors.

Alternatively, generate HTML output and view the help with your web browser.

Regards,
- Graeme -

fpGUI Toolkit - a cross-platform GUI toolkit using Free Pascal http://fpgui.sourceforge.net/

Reply by email

Mattias Gaertner
to Michael Schnell: Hi help experts :-) Graeme suggested that I should enhance the lcl help on QueuAsyncCall.…

?
?

Michael Schnell hat am 20. Juli 2011 um 11:24 geschrieben:

Show quoted text 5 lines
Hi help experts :-) Graeme suggested that I should enhance the lcl help on QueuAsyncCall. So I am trying to do so.

?
Have you tried the View / FPDoc editor?
?

Mattias
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20110720/631c9f88/attachment.html>

Reply by email

Graeme Geldenhuys
to Michael Schnell: Hi help experts :-) Graeme suggested that I should enhance the lcl help on QueuAsyncCall.…
Michael Schnell wrote
See http://www.openwatcom.org/ for details. <lcl.:290250:20> Warning 53: Invalid tag nesting <lcl.:290250:20> Warning 23: The tag, word, or command is not allowed in this context

was...

.* Section: :hp2.
GraphMath Operators:ehp2.

change it to...

.* Section:
:hp2.GraphMath Operators:ehp2.

<lcl.:290256:20> Warning 53: Invalid tag nesting <lcl.:290256:20> Warning 23: The tag, word, or command is not allowed in this context

was...

:h3 name=lcl_graphmath_graphmath_operators. :hp2.
GraphMath Operators:ehp2.

change it to...

:h3 name=lcl_graphmath_graphmath_operators.
:hp2.GraphMath Operators:ehp2.

Now wipfc should be able to compile lcl.ipf without errors. The 3rd error was a knock-on effect of the previous two.

Regards,
- Graeme -

fpGUI Toolkit - a cross-platform GUI toolkit using Free Pascal http://fpgui.sourceforge.net/

Reply by email

Michael Schnell
to Mattias Gaertner: ? ? Michael Schnell hat am 20. Juli 2011 um 11:24 geschrieben: ? Have you tried the View…
Mattias Gaertner wrote
Have you tried the View / FPDoc editor?

I understand that I can use same to *edit* the help files, but in the end I understand that I need to *test* the result to be sure that I don't break anything.

Once I know it's working without any changes I might introduce, I can decide whether to do changes using the FPDoc editor or by simply using a text editor.

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

Reply by email

Michael Schnell
to Graeme Geldenhuys: was... .* Section: :hp2. GraphMath Operators:ehp2. change it to... .* Section:…
Graeme Geldenhuys wrote 15 lines
On 07/20/2011 11:24 AM, Michael Schnell wrote: > See http://www.openwatcom.org/ for details. > <lcl.:290250:20> Warning 53: Invalid tag nesting > <lcl.:290250:20> Warning 23: The tag, word, or command is not allowed in > this context was... .* Section: :hp2. GraphMath Operators:ehp2. change it to... .* Section: :hp2.GraphMath Operators:ehp2.

Thanks !

Do you suggest that I should manually do changes in the automatically created ipf file ? Would it not be better to fix the source of the problem ?

Thanks again,
-Michael

Reply by email

Mattias Gaertner
to Michael Schnell: I understand that I can use same to *edit* the help files, but in the end I understand…
Show quoted text 7 lines
On 07/20/2011 11:41 AM, Mattias Gaertner wrote: > > Have you tried the View / FPDoc editor? > I understand that I can use same to *edit* the help files, but in the end I understand that I need to *test* the result to be sure that I don't break anything.

?
Do you mean if it has a bug?

Once I know it's working without any changes I might introduce, I can decide whether to do changes using the FPDoc editor or by simply using a text editor.

Mattias

Reply by email

Felipe Monteiro de Carvalho
to Mattias Gaertner

Something else strange about the docs. When building the LCL docs one gets a lot of these:

Warning: Target ID of <link> is unknown: "#LCL.Graphics.TCanvas.LineTo"

Then I did a search in files and there is only one occurence of this:

<element name="TCanvas.DoLineTo">
<short>
<var>DoLineTo</var> calls
<var>LineTo</var>
</short>
<descr/>
<errors/>
<seealso>
<link
id="#fcl.FPCanvas.TFPCustomCanvas.DoLineTo">TFPCustomCanvas.DoLineTo</link> <link id="#LCL.Graphics.TCanvas.LineTo">TCanvas.LineTo</link> </seealso>
</element>

I tryed to change it to:

lcl.graphics.TCanvas.LineTo
or
TCanvas.LineTo

but nothing helps. And TCanvas.LineTo is defined in the same file and above this!

Felipe Monteiro de Carvalho

Reply by email

Graeme Geldenhuys
to Mattias Gaertner: On Wed, 20 Jul 2011 12:07:02 +0200 ? Do you mean if it has a bug? Mattias
Mattias Gaertner wrote
? Do you mean if it has a bug?

No, I think he means that the help look correct once he is done editing it. eg: That he added closing tags everywhere, did not use HTML specific tags but rather fpdoc tags, formatting looks correct etc. etc.

Until we have a WYSIWIG editor, those are things each person will have to check manually while editing help text.

Regards,
- Graeme -

fpGUI Toolkit - a cross-platform GUI toolkit using Free Pascal http://fpgui.sourceforge.net/

Reply by email

Michael Schnell
to Mattias Gaertner: On Wed, 20 Jul 2011 12:07:02 +0200 ? Do you mean if it has a bug? Mattias
Mattias Gaertner wrote 6 lines
> I understand that I can use same to *edit* the help files, but in the > end I understand that I need to *test* the result to be sure that I > don't break anything. ? Do you mean if it has a bug?

?
If I offer a patch, I want to be sure that it is as bug-free as possible. Regarding the doc this includes creating at least one decent help file (i.e. *.if for DocView) containing my modification and verify that this works and that the result looks as I think it should. If I fail to create a decent patch, I would not bother anybody with same.

This is independent of the way I would do the modifications.

-Michael

Reply by email

Vincent Snijders
to Michael Schnell

2011/7/22 Michael Schnell :

Show quoted text 8 lines
Funny: After anther svn update, "build_lcl_doc" did output the said error messages but did not crash but create an ipf file. But when I tried this again, I got the Access violation again. Maybe I should introduce some debug outputs...

In my experience fpdoc crashes from time to time.

I suspect some buffer overrun, but have not find out where. I suspect the expression evaluator.

Vincent

Reply by email

Graeme Geldenhuys
to Vincent Snijders
Vincent Snijders wrote
I suspect some buffer overrun, but have not find out where. I suspect the expression evaluator.

Isn't that only used if the Implementation section scanning is enabled?

BTW:
Scanning the Implementation section is disabled by default, and not needed for normal fpdoc usage. I believe that option was only added so the expression evaluator and pascal parse could be tested/debugged more thoroughly.

Regards,
- Graeme -

fpGUI Toolkit - a cross-platform GUI toolkit using Free Pascal http://fpgui.sourceforge.net/

Reply by email

Marco van de Voort
to Vincent Snijders: 2011/7/22 Michael Schnell : In my experience fpdoc crashes from time to time. I suspect…
Vincent Snijders wrote 6 lines
> Maybe I should introduce some debug outputs... In my experience fpdoc crashes from time to time. I suspect some buffer overrun, but have not find out where. I suspect the expression evaluator.

Same experience. Only with the LCL files btw. But they are much larger than rtl and fcl.

I hunted it down by adding some writeln, and IIRC it crashes in a procedural type declaration. But that seemed to be the result of an already corrupt tree.

Reply by email

Marco van de Voort
to Felipe Monteiro de Carvalho: Something else strange about the docs. When building the LCL docs one gets a lot of these:
Felipe Monteiro de Carvalho wrote
Something else strange about the docs. When building the LCL docs one gets a lot of these: Warning: Target ID of <link> is unknown: "#LCL.Graphics.TCanvas.LineTo"

I do notice it is next to a "fpimage" package reference, which is standardly not available in fcl. (sb generated XMLs for it in lazarus repo, but they are not used during standard building of the fpcdoc repository)

So it might be the message recycling the previous string instead of the current one, and not the link you are trying to fix.

Reply by email

Hans-Peter Diettrich
to Marco van de Voort
Show quoted text 5 lines
On Wed, Jul 20, 2011 at 10:08:11PM +0200, Felipe Monteiro de Carvalho wrote: > Something else strange about the docs. When building the LCL docs one > gets a lot of these: > > Warning: Target ID of <link> is unknown: "#LCL.Graphics.TCanvas.LineTo"

Links to #LCL now must all be converted into #LCLbase

DoDi

Reply by email