Sign in Join

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

Mailing lists / lazarus / 2009-04

Latest RTL, FCL and LCL online docs

21 messages · 3 people ·

Reply by email Subscribe to this list Your subscription

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

Graeme Geldenhuys

Compare these for example...

http://lazarus-ccr.sourceforge.net/docs/rtl/
vs
http://www.freepascal.org/docs-html/rtl/

Which one is newer? fpdoc now supports a command line parameter (--footer-date='yyyy-mm-dd') which allows the date the documentation was generated on to be added to the footer. I would suggest this be used for RTL, FCL and LCL documentation. This clearly indicates to the user how old or new the documentation is. I noticed that RTL and FCL documentation hosted on www.freepascal.org already uses this.

I would suggest the ISO 8601 international date format (as shown above) to prevent any confusion with dates.
Summary of ISO 8601 http://www.cl.cam.ac.uk/~mgk25/iso-time.html

  cIntlDateTimeStor = 'yyyymmdd"T"hhmmss';    // for storage
  cIntlDateTimeDisp = 'yyyy-mm-dd hh:mm:ss';  // for display

Regards,
- Graeme -

_______________________________________________
fpGUI - a cross-platform Free Pascal GUI toolkit
http://opensoft.homeip.net/fpgui/

Reply by email

Vincent Snijders
to Graeme Geldenhuys

2009/4/28, Graeme Geldenhuys :

Show quoted text 14 lines
Compare these for example... http://lazarus-ccr.sourceforge.net/docs/rtl/ vs http://www.freepascal.org/docs-html/rtl/ Which one is newer? fpdoc now supports a command line parameter (--footer-date='yyyy-mm-dd') which allows the date the documentation was generated on to be added to the footer. I would suggest this be used for RTL, FCL and LCL documentation. This clearly indicates to the user how old or new the documentation is. I noticed that RTL and FCL documentation hosted on www.freepascal.org already uses this.

I am hesitant to do that. Documentation on sourceforge is generated nighlty and rsynced with the files on SourceForge. It is a bit silly to update these files daily because the datestamp changed.

For local (off line) docs it is a good idea.

Vincent

Reply by email

Graeme Geldenhuys
to Vincent Snijders
Vincent Snijders wrote
I am hesitant to do that. Documentation on sourceforge is generated nighlty and rsynced with the files on SourceForge. It is a bit silly to update these files daily because the datestamp changed.

OK, I see your point. Then again, if the documentation is generate nightly, it is always up to date, so the whole issue of out-of-date docs is moot. :-)

FCL and RTL docs are not created nightly - hence the reason I thought the LCL ones follow suit. I guess I was wrong.

Regards,
- Graeme -

_______________________________________________
fpGUI - a cross-platform Free Pascal GUI toolkit
http://opensoft.homeip.net/fpgui/

Reply by email

Graeme Geldenhuys
to Graeme Geldenhuys
Graeme Geldenhuys wrote
FCL and RTL docs are not created nightly - hence the reason I thought the LCL ones follow suit. I guess I was wrong.

By that I mean the FCL and RTL docs hosted on www.freepascal.org. Are the FCL and RTL docs hosted on lazarus-ccr also created nightly? Or just the LCL ones?

Regards,
- Graeme -

_______________________________________________
fpGUI - a cross-platform Free Pascal GUI toolkit
http://opensoft.homeip.net/fpgui/

Reply by email

Vincent Snijders
to Graeme Geldenhuys: On Tue, Apr 28, 2009 at 11:39 AM, Vincent Snijders OK, I see your point. Then again, if…

2009/4/28, Graeme Geldenhuys :

Show quoted text 7 lines
OK, I see your point. Then again, if the documentation is generate nightly, it is always up to date, so the whole issue of out-of-date docs is moot. :-) FCL and RTL docs are not created nightly - hence the reason I thought the LCL ones follow suit. I guess I was wrong.

Why do you think so? What files are out of date on http://lazarus-ccr.sourceforge.net/docs/rtl/
or
http://lazarus-ccr.sourceforge.net/docs/fcl/

Vincent

Reply by email

Graeme Geldenhuys
to Vincent Snijders
Vincent Snijders wrote 7 lines
> ?FCL and RTL docs are not created nightly - hence the reason I thought > ?the LCL ones follow suit. I guess I was wrong. Why do you think so? What files are out of date on http://lazarus-ccr.sourceforge.net/docs/rtl/ or http://lazarus-ccr.sourceforge.net/docs/fcl/

As my next message said:
"By that I mean the FCL and RTL docs hosted on www.freepascal.org. Are the FCL and RTL docs hosted on lazarus-ccr also created nightly? Or just the LCL ones?"

So from your reply I gather that *all* documentation hosted on lazarus-ccr (rtl, fcl and lcl) are created nightly. That's good to know.

Regards,
- Graeme -

_______________________________________________
fpGUI - a cross-platform Free Pascal GUI toolkit
http://opensoft.homeip.net/fpgui/

Reply by email

Vincent Snijders
to Vincent Snijders: 2009/4/28, Graeme Geldenhuys : I am hesitant to do that. Documentation on sourceforge is…

2009/4/28, Vincent Snijders :

Show quoted text 22 lines
2009/4/28, Graeme Geldenhuys : > Compare these for example... > > http://lazarus-ccr.sourceforge.net/docs/rtl/ > vs > http://www.freepascal.org/docs-html/rtl/ > > > Which one is newer? fpdoc now supports a command line parameter > (--footer-date='yyyy-mm-dd') which allows the date the documentation > was generated on to be added to the footer. I would suggest this be > used for RTL, FCL and LCL documentation. This clearly indicates to the > user how old or new the documentation is. I noticed that RTL and FCL > documentation hosted on www.freepascal.org already uses this. > I am hesitant to do that. Documentation on sourceforge is generated nighlty and rsynced with the files on SourceForge. It is a bit silly to update these files daily because the datestamp changed.

I tried to do it for the off line docs, but the --footer-date parameter is overridden by the --footer parameter which adds a link to the on-line documentation. So for now, also no date stamp in the off line documentation.

Vincent

Reply by email

Graeme Geldenhuys
to Vincent Snijders
Vincent Snijders wrote 5 lines
I tried to do it for the off line docs, but the --footer-date parameter is overridden by the --footer parameter which adds a link to the on-line documentation. So for now, also no date stamp in the off line documentation.

As expected, but local help is not really an issue, seeing that it must be generated by the user itself.

BTW:
The process of generating local HTML help for LCL is pretty easy under Linux. Well done. Easier than RTL and FCL. ;-)

Regards,
- Graeme -

_______________________________________________
fpGUI - a cross-platform Free Pascal GUI toolkit
http://opensoft.homeip.net/fpgui/

Reply by email

Michael Van Canneyt
to Graeme Geldenhuys
Graeme Geldenhuys wrote 14 lines
On Tue, Apr 28, 2009 at 12:54 PM, Vincent Snijders wrote: > > I tried to do it for the off line docs, but the --footer-date > parameter is overridden by the --footer parameter which adds a link to > the on-line documentation. So for now, also no date stamp in the off > line documentation. As expected, but local help is not really an issue, seeing that it must be generated by the user itself. BTW: The process of generating local HTML help for LCL is pretty easy under Linux. Well done. Easier than RTL and FCL. ;-)

What is so hard about typing
make html
?

Michael.

Reply by email

Vincent Snijders
to Graeme Geldenhuys: On Tue, Apr 28, 2009 at 12:54 PM, Vincent Snijders As expected, but local help is not…

2009/4/28, Graeme Geldenhuys :

Show quoted text 11 lines
On Tue, Apr 28, 2009 at 12:54 PM, Vincent Snijders wrote: > > I tried to do it for the off line docs, but the --footer-date > parameter is overridden by the --footer parameter which adds a link to > the on-line documentation. So for now, also no date stamp in the off > line documentation. As expected, but local help is not really an issue, seeing that it must be generated by the user itself.

Not really, it is part of releases and snapshots too.

Vincent

Reply by email

Graeme Geldenhuys
to Michael Van Canneyt: What is so hard about typing make html ? Michael.
Michael Van Canneyt wrote
What is so hard about typing make html ?

/opt/fpcdocs_svn $ make html
make -C ../compiler/utils msg2inc
make: *** ../compiler/utils: No such file or directory. Stop. make: *** [../compiler/utils/msg2inc] Error 2

OK, so clearly 'fpcdocs_svn' must be in a different directory layout. The README.DOCS doesn't mention a required directory structure. Also the documentation repository (located at
http://svn.freepascal.org/svn/fpcdocs/trunk) doesn't give any indication that it must be a sub-directory of FPC somewhere.

The readme file also says that to create html help, it uses latex2html, but what if I am only interested in the class documentation for RTL and FCL? Onl HTML output, not the pretty PDF manuals that I always download. What make parameter do I pass in then
- that doesn't require latex2html? Something that only uses fpdoc for html output?

Regards,
- Graeme -

_______________________________________________
fpGUI - a cross-platform Free Pascal GUI toolkit
http://opensoft.homeip.net/fpgui/

Reply by email

Graeme Geldenhuys
to Graeme Geldenhuys
Graeme Geldenhuys wrote
OK, so clearly 'fpcdocs_svn' must be in a different directory layout.

I then guessed that fpcdocs_svn must be somewhere in the FPC source directory. So I did that by creating a 'docs' symlink in my FPC source directory:

/opt/fpc/src $ l
total 112K
-rw-r--r-- 1 6 2009-03-13 09:28 build-stamp.i386-linux drwxr-xr-x 20 4.0K 2009-03-13 09:26 compiler
lrwxrwxrwx 1 16 2009-04-28 14:05 docs -> /opt/fpcdocs_svn drwxr-xr-x 6 4.0K 2009-03-13 09:28 ide
drwxr-xr-x 4 4.0K 2009-03-13 09:28 installer
-rw-r--r-- 1 62K 2009-03-13 09:21 Makefile
-rw-r--r-- 1 6.3K 2009-03-13 09:21 Makefile.fpc
drwxr-xr-x 96 4.0K 2008-12-05 11:08 packages
drwxr-xr-x 43 4.0K 2009-03-13 09:28 rtl
-rwxrwxr-- 1 67 2009-03-13 09:38 startbuild.sh
drwxr-xr-x 11 4.0K 2008-06-09 09:26 tests
drwxr-xr-x 19 4.0K 2009-03-13 09:28 utils

So now lets try the following:

/opt/fpc/src $ cd docs
/opt/fpc/src/docs $ make html
make -C ../compiler/utils msg2inc
make: *** ../compiler/utils: No such file or directory. Stop. make: *** [../compiler/utils/msg2inc] Error 2

Umm... see the problem? It's just not that easy like the LCL help. Yes I know the RTL and FCL help is obviously a bit more complex. It's LaTeX manuals and fpdoc help all in one. But clearly this is not easy for any user to generate HTML (from fpdoc output) help. I see LCL uses a console application to help the build process. I thought of doing the same thing for fpGUI Toolkit. Maybe we could knock something together for FPC docs as well and get rid of makefiles? And hopefully get run of latex2html requirement for HTML class help which fpdoc can do on it's own.

Regards,
- Graeme -

_______________________________________________
fpGUI - a cross-platform Free Pascal GUI toolkit
http://opensoft.homeip.net/fpgui/

Reply by email

Michael Van Canneyt
to Graeme Geldenhuys: On Tue, Apr 28, 2009 at 1:17 PM, Michael Van Canneyt /opt/fpcdocs_svn $ make html make -C…
Graeme Geldenhuys wrote 25 lines
On Tue, Apr 28, 2009 at 1:17 PM, Michael Van Canneyt wrote: > > What is so hard about typing > make html > ? /opt/fpcdocs_svn $ make html make -C ../compiler/utils msg2inc make: *** ../compiler/utils: No such file or directory. Stop. make: *** [../compiler/utils/msg2inc] Error 2 OK, so clearly 'fpcdocs_svn' must be in a different directory layout. The README.DOCS doesn't mention a required directory structure. Also the documentation repository (located at http://svn.freepascal.org/svn/fpcdocs/trunk) doesn't give any indication that it must be a sub-directory of FPC somewhere. The readme file also says that to create html help, it uses latex2html, but what if I am only interested in the class documentation for RTL and FCL? Onl HTML output, not the pretty PDF manuals that I always download. What make parameter do I pass in then - that doesn't require latex2html? Something that only uses fpdoc for html output?

The following should do it:

make rtl.chk
make fcl.chk

And you don't need latex2html, but tex4ht for the other things.

I changed the README file so it's more correct.

Michael.

Reply by email

Graeme Geldenhuys
to Michael Van Canneyt
Michael Van Canneyt wrote 8 lines
The following should do it: make rtl.chk make fcl.chk And you don't need latex2html, but tex4ht for the other things. I changed the README file so it's more correct.

Thanks, the description is now much better (clearer). I still have problems though. Can I use a symlink'ed docs directory? The layout is still as I shown in my previous email, but I get the following output.

=========================
/opt/fpc/src/docs $ make clean
<.....removed lots of output...>
/opt/fpc/src/docs $ make rtl.chk
fpdoc --warn-no-node --package=rtl --descr=rtl.xml --content=rtl.xct --hide-protected --descr=strutils.xml
--input="../rtl/objpas/strutils.pp " --descr=sysutils.xml --input="../rtl/unix/sysutils.pp -Fi../rtl/objpas/sysutils -Fi../rtl/inc " ........
<....lots more text gets displayed and then the following....> FPDoc - Free Pascal Documentation Tool
Version 2.2.5 [2009/03/13]
(c) 2000 - 2003 Areca Systems GmbH / Sebastian Guenther,

An unhandled exception occurred at $080CD8D9 :
EFileNotFoundError : ../rtl/objpas/strutils.pp
$080CD8D9
$080CDCF4
$080493A8
$08049931

make: *** [rtl.chk] Error 217
=========================

Yet the ../rtl/objpas/strutils.pp file *does* exist.

Regards,
- Graeme -

_______________________________________________
fpGUI - a cross-platform Free Pascal GUI toolkit
http://opensoft.homeip.net/fpgui/

Reply by email

Michael Van Canneyt
to Graeme Geldenhuys
Graeme Geldenhuys wrote 14 lines
On Tue, Apr 28, 2009 at 2:15 PM, Michael Van Canneyt wrote: > > The following should do it: > > make rtl.chk > make fcl.chk > > And you don't need latex2html, but tex4ht for the other things. > I changed the README file so it's more correct. Thanks, the description is now much better (clearer). I still have problems though. Can I use a symlink'ed docs directory? The layout is still as I shown in my previous email, but I get the following output.

You can't use a symlinked docs directory, the link points in the wrong direction.

You could try symlinked rtl/compiler/packages directories from the point of view of the docs.

Michael.

Reply by email

Graeme Geldenhuys
to Graeme Geldenhuys: On Tue, Apr 28, 2009 at 2:15 PM, Michael Van Canneyt Thanks, the description is now much…
Graeme Geldenhuys wrote
Thanks, the description is now much better (clearer). ?I still have problems though. Can I use a symlink'ed docs directory? The layout is still as I shown in my previous email, but I get the following output.

OK, clearly for some very strange reason symlink'ed folders are NOT allowed. I removed the /opt/fpc/src/docs symlink and copied the fpcdocs_svn directory into /opt/fpc/src/

Then I ran 'make rtl.chk' and it worked! :-)

Then I ran 'make fcl.chk' and it failed! :-(

=========================
/opt/fpc/src/fpcdocs_svn $ make fcl.chk
../utils/fpdoc/fpdoc --package=fcl --warn-no-node --descr=fcl.xml --content=fcl.xct --import=rtl.xct,../rtl/ --descr=iostream.xml --input="-S2 ../packages/fcl-base/src/iostream.pp" ...... [ ****** cut lots of text so I can email the output *****] FPDoc - Free Pascal Documentation Tool
Version 2.2.5 [2009/03/13]
(c) 2000 - 2003 Areca Systems GmbH / Sebastian Guenther,

An unhandled exception occurred at $080CD8D9 :
EFileNotFoundError : ../packages/fcl-base/src/ascii85.pp $080CD8D9
$080CDCF4
$080493A8
$08049931

make: *** [fcl.chk] Error 217
=======================

Ah, now it's actually reporting a missing unit. ascii85.pp doesn't exist in FPC 2.2.5. Any ideas how I can make it works without using FPC trunk?

PS:
I'm working on some minor improvements to the fpdoc.css file as well. It doesn't have any formatting for definition lists.

Regards,
- Graeme -

_______________________________________________
fpGUI - a cross-platform Free Pascal GUI toolkit
http://opensoft.homeip.net/fpgui/

Reply by email

Vincent Snijders
to Michael Van Canneyt: You can't use a symlinked docs directory, the link points in the wrong direction. You…

2009/4/28, Michael Van Canneyt :

Show quoted text 13 lines
On Tue, 28 Apr 2009, Graeme Geldenhuys wrote: > Thanks, the description is now much better (clearer). I still have > problems though. Can I use a symlink'ed docs directory? The layout is > still as I shown in my previous email, but I get the following output. You can't use a symlinked docs directory, the link points in the wrong direction. You could try symlinked rtl/compiler/packages directories from the point of view of the docs.

I just do:
FPCSRCDIR=/path/to/fpc/sources
make rtl.chk FPCSRCDIR=$FPCSRCDIR

Vincent

Reply by email

Graeme Geldenhuys
to Michael Van Canneyt: You can't use a symlinked docs directory, the link points in the wrong direction. You…
Michael Van Canneyt wrote 6 lines
You can't use a symlinked docs directory, the link points in the wrong direction. You could try symlinked rtl/compiler/packages directories from the point of view of the docs.

I'm curious as to why it should make a difference? If I am in the 'fpcdocs_svn' directory (symlinked into /opt/fpc/src/docs) I can do a 'ls -l ../rtl/*' and see the relevant files. So why doesn't the make work.

Regards,
- Graeme -

_______________________________________________
fpGUI - a cross-platform Free Pascal GUI toolkit
http://opensoft.homeip.net/fpgui/

Reply by email

Michael Van Canneyt
to Graeme Geldenhuys: On Tue, Apr 28, 2009 at 2:47 PM, Graeme Geldenhuys OK, clearly for some very strange…
Show quoted text 14 lines
On Tue, 28 Apr 2009, Graeme Geldenhuys wrote: > On Tue, Apr 28, 2009 at 2:47 PM, Graeme Geldenhuys wrote: > > Thanks, the description is now much better (clearer). ?I still have > problems though. Can I use a symlink'ed docs directory? The layout is > still as I shown in my previous email, but I get the following output. OK, clearly for some very strange reason symlink'ed folders are NOT allowed. I removed the /opt/fpc/src/docs symlink and copied the fpcdocs_svn directory into /opt/fpc/src/

This is not strange at all, because if you have
FPC/src/something/mydocs/
symlinked as
FPC/src/docs
with the rest of the sources under FPC/src
then inside FPC/src/something/mydocs/
../rtl
is
FPC/src/something/rtl

The shells (bash/tch) can do some tricks so that a cd ../rtl will work if you entered /FPC/src/docs.

Show quoted text 9 lines
Then I ran 'make rtl.chk' and it worked! :-) Then I ran 'make fcl.chk' and it failed! :-( Ah, now it's actually reporting a missing unit. ascii85.pp doesn't exist in FPC 2.2.5. Any ideas how I can make it works without using FPC trunk?

Currently none, except of editing the Makefile

Michael.

Reply by email

Michael Van Canneyt
to Graeme Geldenhuys
Graeme Geldenhuys wrote 10 lines
On Tue, Apr 28, 2009 at 3:13 PM, Vincent Snijders wrote: > > I just do: > FPCSRCDIR=/path/to/fpc/sources > make rtl.chk FPCSRCDIR=$FPCSRCDIR That's even better. :-) Michael, could you add this to the readme file as well?

Done.

Michael.

Reply by email