Re: [fpc-pascal] Documentation typo?

[Michael Van Canneyt via fpc-pascal]

On Tue, 23 Jul 2024, Thomas Kurz via fpc-pascal wrote:


Hello,

in 
`https://www.freepascal.org/docs-html/current/rtl/sockets/netaddrtostr6.html`, 
it is written:


NetAddrToStr6 converts the IPV6 network address in Entry to a string 
representation in human-readable form.

Basically, it is the same as NetAddrToStr6, but with the bytes in correct order.


I think that the second "NetAddrToStr6" should be something else, probably 
"HostAddrToStr6".


Yes. Thanks, I corrected it.

Michael.
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
https://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

[fpc-pascal] Documentation typo?

[Thomas Kurz via fpc-pascal]

Hello,

in 
`https://www.freepascal.org/docs-html/current/rtl/sockets/netaddrtostr6.html`, 
it is written:


NetAddrToStr6 converts the IPV6 network address in Entry to a string 
representation in human-readable form.

Basically, it is the same as NetAddrToStr6, but with the bytes in correct order.


I think that the second "NetAddrToStr6" should be something else, probably 
"HostAddrToStr6".


___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
https://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation or compiler bug?

[Hairy Pixels via fpc-pascal]

> On Jul 8, 2023, at 3:57 PM, Michael Van Canneyt via fpc-pascal 
>  wrote:
> 
> You must put the cdecl (which is the calling convention) before the external:

o so the order is the problem. That error message is misleading and should 
be changed. I know c library functions are external and cdecl but that error 
really confused me.

As for the internal error that still should't happen but I would have gotten 
the wrong result anyway if it had run. Thanks for clarifying.

Regards,
Ryan Joseph

___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
https://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation or compiler bug?

[Michael Van Canneyt via fpc-pascal]

On Sat, 8 Jul 2023, Michael Van Canneyt via fpc-pascal wrote:




On Sat, 8 Jul 2023, Hairy Pixels via fpc-pascal wrote:

In fact I filed a bug today which was related. Notice how I didn't use 
cdecl in the program but another user tried to compile and had problems 
with cdecl also.


https://gitlab.com/freepascal.org/fpc/source/-/issues/40342 



Small addition:

He did not have problems with cdecl, but with the fact that the c library
was not linked. But this was intended: he wrote it explicitly 'as intended'. 
So all is well, except the internal error (AFAIK you cannot pass a record to printf())


Just so you have a correct picture of what is happening.

Michael.
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
https://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation or compiler bug?

[Michael Van Canneyt via fpc-pascal]

On Sat, 8 Jul 2023, Hairy Pixels via fpc-pascal wrote:


In fact I filed a bug today which was related. Notice how I didn't use cdecl in 
the program but another user tried to compile and had problems with cdecl also.

https://gitlab.com/freepascal.org/fpc/source/-/issues/40342 


Basically this program:

{$mode objfpc}

program test;

function printf(format: PChar): Integer; external; cdecl; varargs;


You must put the cdecl (which is the calling convention) before the external:

{$linklib c}

function printf(format: PChar): Integer; cdecl; external; varargs;

begin
  printf('%d is the answer'#10,42)
end.

Will work and will print

42 is the answer

Michael.
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
https://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation or compiler bug?

[Hairy Pixels via fpc-pascal]

In fact I filed a bug today which was related. Notice how I didn't use cdecl in 
the program but another user tried to compile and had problems with cdecl also.

https://gitlab.com/freepascal.org/fpc/source/-/issues/40342 


Basically this program:

{$mode objfpc}

program test;

function printf(format: PChar): Integer; external; cdecl; varargs;

begin
end.


> On Jul 8, 2023, at 2:12 PM, Michael Van Canneyt via fpc-pascal 
>  wrote:
> 
> They are used together. The FPC sources are full of them, most import
> libraries work like that:
> 
> function PQconnectStart(conninfo:Pchar):PPGconn;cdecl;external 
> External_library name 'PQconnectStart';
> 
> It would be helpful if you would give the exact statement you are writing.

Regards,
Ryan Joseph

___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
https://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation or compiler bug?

[Michael Van Canneyt via fpc-pascal]

On Sat, 8 Jul 2023, Hairy Pixels via fpc-pascal wrote:


I get the error "Procedure directive "CDECL" cannot be used with "EXTERNAL"" when I use 
"cdecl" with external modifiers yet the docs at https://www.freepascal.org/docs-html/ref/refsu73.html say":

When compiling this, and linking to the C-library, the strlen function can be 
called throughout the program. The external directive tells the compiler that 
the function resides in an external object file or library with the “strlen” 
name (see 14.7).

Suggesting they can be used together, so which is right? Compiler is: Free 
Pascal Compiler version 3.3.1 [2023/03/03] for aarch64



They are used together. The FPC sources are full of them, most import
libraries work like that:

function PQconnectStart(conninfo:Pchar):PPGconn;cdecl;external External_library 
name 'PQconnectStart';

It would be helpful if you would give the exact statement you are writing.

Michael.___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
https://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

[fpc-pascal] Documentation or compiler bug?

[Hairy Pixels via fpc-pascal]

I get the error "Procedure directive "CDECL" cannot be used with "EXTERNAL"" 
when I use "cdecl" with external modifiers yet the docs at 
https://www.freepascal.org/docs-html/ref/refsu73.html say":

When compiling this, and linking to the C-library, the strlen function can be 
called throughout the program. The external directive tells the compiler that 
the function resides in an external object file or library with the “strlen” 
name (see 14.7).

Suggesting they can be used together, so which is right? Compiler is: Free 
Pascal Compiler version 3.3.1 [2023/03/03] for aarch64

Regards,
Ryan Joseph

___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
https://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation patch for fcl/netdb

[Michael Van Canneyt via fpc-pascal]

Thank you. 
I will check it out ASAP. 
Before publishing, I will need to document all identifiers in the unit.


Michael.

On Sat, 17 Apr 2021, Noel Duffy via fpc-pascal wrote:

I've added a documentation patch to bug 0037906 in the bug tracker. This 
covers the new code that I added to fcl/netdb for DNS resolution as well 
most of the other functions and procedures in the unit. The patch also 
adds examples that showcase the new functions. I've tested these on 
Fedora 32 only.


https://bugs.freepascal.org/view.php?id=37906#c130418



___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
https://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal


___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
https://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

[fpc-pascal] Documentation patch for fcl/netdb

[Noel Duffy via fpc-pascal]

I've added a documentation patch to bug 0037906 in the bug tracker. This 
covers the new code that I added to fcl/netdb for DNS resolution as well 
most of the other functions and procedures in the unit. The patch also 
adds examples that showcase the new functions. I've tested these on 
Fedora 32 only.


https://bugs.freepascal.org/view.php?id=37906#c130418



___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
https://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation bug - Language Ref - Ordinal types

[Graeme Geldenhuys via fpc-pascal]

On 27/12/2020 4:53 pm, Graeme Geldenhuys via fpc-pascal wrote:
> 
> According to this HTML page:
>https://freepascal.org/docs-html/ref/refsu4.html

Oh wait, the table I was looking at is titled "Integer constant type mapping",
so it's how the compile maps constants to a data type. It's not the actual
range of the data types themselves.

My bad. Sorry for the noise.

Regards,
  Graeme
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
https://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

[fpc-pascal] Documentation bug - Language Ref - Ordinal types

[Graeme Geldenhuys via fpc-pascal]

According to this HTML page:
   https://freepascal.org/docs-html/ref/refsu4.html

The data types Byte, Word and Cardinal (LongWord) has the following ranges:

128..255Byte
32768..65535Word
2147483648..4294967295  Cardinal (longword)


Those should be 0..


Regards,
  Graeme

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

My public PGP key:  http://tinyurl.com/graeme-pgp
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
https://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation generation

[Graeme Geldenhuys]

On 18/08/2019 10:43 am, Michael Van Canneyt wrote:
> One wonders why these README files are created. No-one seems to read them
> anyway.

Yeah, I've been wondering that same thing for years. Maybe we should
create a README.1st file.   :-P



Regards,
  Graeme

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

My public PGP key:  http://tinyurl.com/graeme-pgp
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
https://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation generation

[Marco van de Voort]

Op 2019-08-18 om 11:43 schreef Michael Van Canneyt:



On Sat, 17 Aug 2019, leledumbo via fpc-pascal wrote:

How are the FPC RTL documentations generated? I wanted to see if I 
could

generate .docsets files from them also.

A starting point: https://wiki.freepascal.org/FPCDocs_Tutorial
I believe that "write me" part is not far from calling make with certain
options.


You simply call

make rtl.pdf

for the PDF version or

make rtl.chk


and the fixdocs.sh shell script for the CHM version.


___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
https://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation generation

[Michael Van Canneyt]

On Sat, 17 Aug 2019, leledumbo via fpc-pascal wrote:


How are the FPC RTL documentations generated? I wanted to see if I could

generate .docsets files from them also.

A starting point: https://wiki.freepascal.org/FPCDocs_Tutorial
I believe that "write me" part is not far from calling make with certain
options.


You simply call

make rtl.pdf

for the PDF version or

make rtl.chk

for the HTML version.

The README.DOCS file contains the following:
---
If you only want to generate the RTL and FCL reference documentation
in HTML format, starting from the fpdoc XML descriptions, then the 
following 2 commands should be enough:


make rtl.chk 
make fcl.chk


---


One wonders why these README files are created. No-one seems to read them
anyway.

Michael.
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
https://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation generation

[leledumbo via fpc-pascal]

> How are the FPC RTL documentations generated? I wanted to see if I could
generate .docsets files from them also.

A starting point: https://wiki.freepascal.org/FPCDocs_Tutorial
I believe that "write me" part is not far from calling make with certain
options.



--
Sent from: http://free-pascal-general.1045716.n5.nabble.com/
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
https://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

[fpc-pascal] Documentation generation

[Ryan Joseph]

How are the FPC RTL documentations generated? I wanted to see if I could 
generate .docsets files from them also.

Regards,
Ryan Joseph

___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
https://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation confusion or error

[Graeme Geldenhuys]

On 08/05/2019 12:58 pm, Michael Van Canneyt wrote:
> Can you please create a bugreport so I will not forget ?

No problem.

   https://bugs.freepascal.org/view.php?id=35542


Regards,
  Graeme

___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation confusion or error

[Michael Van Canneyt]

On Wed, 8 May 2019, Graeme Geldenhuys wrote:


Hi,

https://www.freepascal.org/docs-html/rtl/sysutils/longrec.html

I'm referring to the documentation shown in the URL above. As far as I
know the fpdoc is sensitive to which platform it is running on (unless
explicitly told otherwise), and will generate documentation according to
that platform. Please correct me if I am wrong, but this was my personal
experience with fpdoc.

Anyway, as far as I know the FPC documentation is normally generated on
a Linux system with 64-bit Intel type CPU.

If so, that means the documentation shown above has the Hi, Lo fields in
the wrong order. Showing Big Endian instead of Little Endian (what Intel
desktop CPU's are).


The defines need to be added to the fpdoc command-line.
I will add FPC_LITTLE_ENDIAN to the list of defines.

Can you please create a bugreport so I will not forget ?

Michael.
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

[fpc-pascal] Documentation confusion or error

[Graeme Geldenhuys]

Hi,

https://www.freepascal.org/docs-html/rtl/sysutils/longrec.html

I'm referring to the documentation shown in the URL above. As far as I
know the fpdoc is sensitive to which platform it is running on (unless
explicitly told otherwise), and will generate documentation according to
that platform. Please correct me if I am wrong, but this was my personal
experience with fpdoc.

Anyway, as far as I know the FPC documentation is normally generated on
a Linux system with 64-bit Intel type CPU.

If so, that means the documentation shown above has the Hi, Lo fields in
the wrong order. Showing Big Endian instead of Little Endian (what Intel
desktop CPU's are).


Based on the real source code found in sysutilh.inc, this is how the
record is actually defined:


   LongRec = packed record
  case Integer of
{$ifdef FPC_LITTLE_ENDIAN}
0 : (Lo,Hi : Word);
{$else FPC_LITTLE_ENDIAN}
0 : (Hi,Lo : Word);
{$endif FPC_LITTLE_ENDIAN}
1 : (Bytes : Array[0..3] of Byte);
   end;

It seems that when generating documentation the FPC_LITTLE_ENDIAN
compiler define is not specified, thus fpdoc defaults to using and
showing the Big Endian source code.


On a side note:
  It might also be a good idea to indicate inside the documentation
  which system was used to generate the docs. Maybe the footer or some
  "About -> Notations" page. As far as I know fpdoc can't show
  documentation for multiple platforms together (like the source code
  shown above).


Regards,
  Graeme

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

My public PGP key:  http://tinyurl.com/graeme-pgp
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation typo

[Michael Van Canneyt]

On Fri, 15 Feb 2019, Marco Borsari via fpc-pascal wrote:


In the online html documentation, in the Programmer's Guide, at 1.2.4,
it reads:
"If it is + (the default) then the compiler will only evaluate as many
terms as are necessary to determine the result of the complete expression."
Obviously it should be "If it is - (the default)"


Thanks for notifying us. Luckily, this is already fixed in SVN !

Michael.
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

[fpc-pascal] Documentation typo

[Marco Borsari via fpc-pascal]

In the online html documentation, in the Programmer's Guide, at 1.2.4,
it reads:
"If it is + (the default) then the compiler will only evaluate as many
terms as are necessary to determine the result of the complete expression."
Obviously it should be "If it is - (the default)"
Regards, Marco
-- 
Simplex sigillum veri
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation example error

[Graeme Geldenhuys]

On 2016-01-26 10:13, Jonas Maebe wrote:
> The rttiobj unit is compiled in Delphi mode

Ah, I missed that one. Thanks for pointing that out.


>, hence  
> http://wiki.freepascal.org/User_Changes_2.6.0#Sizes_of_sets_in_TP.2FDelphi_mode

Many thanks for the link.


Regards,
  - Graeme -


My public PGP key:  http://tinyurl.com/graeme-pgp
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation example error

[Jonas Maebe]

Graeme Geldenhuys wrote on Tue, 26 Jan 2016:


To make the typeinfex/*.pp examples compilable, I had to make some
changes as shown below. I don't hope text wrapping screws this up, but
just in case, I attached the patch too. Before, it seems it was valid to
typecast a Set as Integer(), but testing with FPC 3.0 it seems
typecasting as Byte() is now required.

If I don't, the compile gives the following error:

   ex8.pp(25,17) Error: Illegal type conversion: "LongInt" to "TMyEnums"

Do you know when this change was made in FPC, and where it is documented
(eg: wiki User Changes ...)?


The rttiobj unit is compiled in Delphi mode, hence  
http://wiki.freepascal.org/User_Changes_2.6.0#Sizes_of_sets_in_TP.2FDelphi_mode



Jonas
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation example error

[Graeme Geldenhuys]

On 2016-01-25 16:32, Michael Van Canneyt wrote:
> They should definitely be compilable.

Complete patch attached in Mantis:

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


Regards,
  - Graeme -

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

My public PGP key:  http://tinyurl.com/graeme-pgp
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation example error

[Graeme Geldenhuys]

On 2016-01-25 16:32, Michael Van Canneyt wrote:
> 
> They should definitely be compilable.


To make the typeinfex/*.pp examples compilable, I had to make some
changes as shown below. I don't hope text wrapping screws this up, but
just in case, I attached the patch too. Before, it seems it was valid to
typecast a Set as Integer(), but testing with FPC 3.0 it seems
typecasting as Byte() is now required.

If I don't, the compile gives the following error:

   ex8.pp(25,17) Error: Illegal type conversion: "LongInt" to "TMyEnums"

Do you know when this change was made in FPC, and where it is documented
(eg: wiki User Changes ...)?


[typinfex (master)]$ git diff ex8.pp
diff --git a/typinfex/ex8.pp b/typinfex/ex8.pp
index 1a9d71e..e0c720c 100644
--- a/typinfex/ex8.pp
+++ b/typinfex/ex8.pp
@@ -20,9 +20,9 @@ begin
   O:=TMyTestObject.Create;
   O.SetField:=[mefirst,meSecond,meThird];
   PI:=GetPropInfo(O,'SetField');
-  Writeln('SetToString (brackets) :
',SetToString(Pi,Integer(O.SetField),True));
-  Writeln('SetToString (default)  : ',SetToString(Pi,Integer(O.SetField)));
-  O.SetField:=TMyEnums(StringToSet(PI,ConstSet));
-  Writeln('Stringtoset: ',SetToString(PI,Integer(O.SetField)));
+  Writeln('SetToString (brackets) :
',SetToString(Pi,Byte(O.SetField),True));
+  Writeln('SetToString (default)  : ',SetToString(Pi,Byte(O.SetField)));
+  O.SetField := TMyEnums(Byte(StringToSet(PI,ConstSet)));
+  Writeln('StringToSet: ',SetToString(PI,Byte(O.SetField)));
   O.Free;
 end.





Regards,
  - Graeme -

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

My public PGP key:  http://tinyurl.com/graeme-pgp
diff --git a/typinfex/ex8.pp b/typinfex/ex8.pp
index 1a9d71e..e0c720c 100644
--- a/typinfex/ex8.pp
+++ b/typinfex/ex8.pp
@@ -20,9 +20,9 @@ begin
   O:=TMyTestObject.Create;
   O.SetField:=[mefirst,meSecond,meThird];
   PI:=GetPropInfo(O,'SetField');
-  Writeln('SetToString (brackets) : ',SetToString(Pi,Integer(O.SetField),True));
-  Writeln('SetToString (default)  : ',SetToString(Pi,Integer(O.SetField)));
-  O.SetField:=TMyEnums(StringToSet(PI,ConstSet));
-  Writeln('Stringtoset: ',SetToString(PI,Integer(O.SetField)));
+  Writeln('SetToString (brackets) : ',SetToString(Pi,Byte(O.SetField),True));
+  Writeln('SetToString (default)  : ',SetToString(Pi,Byte(O.SetField)));
+  O.SetField := TMyEnums(Byte(StringToSet(PI,ConstSet)));
+  Writeln('StringToSet: ',SetToString(PI,Byte(O.SetField)));
   O.Free;
 end.

___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation example error

[Graeme Geldenhuys]

On 2016-01-25 16:44, Stephen Chrzanowski wrote:
> You could possibly just replace it with a tedit or
> tlistbox or something.

No, that would make the example GUI and GUI Toolkit dependant. Free
Pascal doesn't include any GUI dependencies.

Regards,
  - Graeme -

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

My public PGP key:  http://tinyurl.com/graeme-pgp
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation example error

[Stephen Chrzanowski]

I looked at the example, and it isn't compilable by my eye ball, however,
the idea I think is to replace that not found class def'n with something
you already know about.  You could possibly just replace it with a tedit or
tlistbox or something.

On Mon, Jan 25, 2016 at 11:32 AM, Michael Van Canneyt <
mich...@freepascal.org> wrote:

>
>
> On Mon, 25 Jan 2016, Graeme Geldenhuys wrote:
>
> Hi,
>>
>> I was always under the impression that the examples included in the FPC
>> documentation should be compilable examples.
>>
>> Looking at the following example code included with the GenEnumName()
>> documentation, it will not compile because TMyTestObject is undefined.
>>
>>  http://www.freepascal.org/docs-html/rtl/typinfo/getenumname.html
>>
>>
>> If my assumption about compilable examples are correct, I'll be happy to
>> supply a patch to fix it.
>>
>
> They should definitely be compilable.
>
> I do not check this regularly, though :/
>
>
> Michael.
>
> ___
> fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
> http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal
>
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation example error

[Graeme Geldenhuys]

On 2016-01-25 16:32, Michael Van Canneyt wrote:
> They should definitely be compilable.

OK, I found more. I'll send through a patch via Mantis.

Regards,
  - Graeme -


My public PGP key:  http://tinyurl.com/graeme-pgp
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation example error

[Michael Van Canneyt]

On Mon, 25 Jan 2016, Graeme Geldenhuys wrote:


Hi,

I was always under the impression that the examples included in the FPC
documentation should be compilable examples.

Looking at the following example code included with the GenEnumName()
documentation, it will not compile because TMyTestObject is undefined.

 http://www.freepascal.org/docs-html/rtl/typinfo/getenumname.html


If my assumption about compilable examples are correct, I'll be happy to
supply a patch to fix it.


They should definitely be compilable.

I do not check this regularly, though :/


Michael.
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

[fpc-pascal] Documentation example error

[Graeme Geldenhuys]

Hi,

I was always under the impression that the examples included in the FPC
documentation should be compilable examples.

Looking at the following example code included with the GenEnumName()
documentation, it will not compile because TMyTestObject is undefined.

  http://www.freepascal.org/docs-html/rtl/typinfo/getenumname.html


If my assumption about compilable examples are correct, I'll be happy to
supply a patch to fix it.

Regards,
  - Graeme -

My public PGP key:  http://tinyurl.com/graeme-pgp
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation, syntax diagrams

[Michael Van Canneyt]

On Sat, 11 Jan 2014, Marco van de Voort wrote:


In our previous episode, Michael Van Canneyt said:

Am 2014-01-11 13:14, schrieb Michael Van Canneyt:

I meant that I use a diagram typesetting package for LaTeX. This package
definitely works like that.


Then something is wrong with this package.
Which one is it?


listings.sty


syntax.sty?


Sorry, yes. listings.sty is for the code fragments.

Michael.
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation, syntax diagrams

[Marco van de Voort]

In our previous episode, Michael Van Canneyt said:
> > Am 2014-01-11 13:14, schrieb Michael Van Canneyt:
> >> I meant that I use a diagram typesetting package for LaTeX. This package 
> >> definitely works like that.
> >
> > Then something is wrong with this package.
> > Which one is it?
> 
> listings.sty

syntax.sty?
 
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation, syntax diagrams

[Michael Van Canneyt]

On Sat, 11 Jan 2014, Jürgen Hestermann wrote:


Am 2014-01-11 13:14, schrieb Michael Van Canneyt:
I meant that I use a diagram typesetting package for LaTeX. This package 
definitely works like that.


Then something is wrong with this package.
Which one is it?


listings.sty

I didn't write this package, but I'm sure its author will appreciate your 
insights.


And as I wrote, there are diagrams which do *not*
repeat the header (diagram name) in the diagram:
On pages 69,85,98,103,110,114 and 115 each diagram starts with a (bold) 
keyword

("packed"/"class, "Interface", "extended record type", "class"/"record",
"objcclass", "objcprotocol" and "objccategory")
and not with the diagram name.
This is what I would expect for all other diagrams too.
Why this inconsistency?


I don't necessarily consider this inconsistent.


If the diagrams stay like this they are too confusing to be of any use.


That is your opinion, to which you are of course entitled.

Feel free to make suggestions for improvements. 
If I consider the suggestions good, I will certainly incorporate them.


But I kindly suggest you change your tone. You may not realize it, 
but your tone is edging on arrogant.


Michael.___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation, syntax diagrams

[Jürgen Hestermann]

Am 2014-01-11 13:14, schrieb Michael Van Canneyt:

I meant that I use a diagram typesetting package for LaTeX. This package 
definitely works like that.


Then something is wrong with this package.
Which one is it?

And as I wrote, there are diagrams which do *not*
repeat the header (diagram name) in the diagram:
On pages 69,85,98,103,110,114 and 115 each diagram starts with a (bold) keyword
("packed"/"class, "Interface", "extended record type", "class"/"record",
 "objcclass", "objcprotocol" and "objccategory")
and not with the diagram name.
This is what I would expect for all other diagrams too.
Why this inconsistency?
If the diagrams stay like this they are too confusing to be of any use.


There are some other glitches I found while reading the documentation:

*) Page 158: A superfluous line exists.

*) Page 180: The diagram seems to imply that a finalization part cannot be 
added without an initialization part.


___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation, syntax diagrams

[Michael Van Canneyt]

On Fri, 10 Jan 2014, Jürgen Hestermann wrote:


Am 2014-01-10 09:09, schrieb Michael Van Canneyt:

But why is the heading part of the diagram?

Because that is how the typesetting mechanism for syntax diagrams work.


That's not true (at least not in diagrams other than in Free Pascal).


I meant that I use a diagram typesetting package for LaTeX. 
This package definitely works like that.


Michael.___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation, syntax diagrams

[Jürgen Hestermann]

Am 2014-01-10 09:09, schrieb Michael Van Canneyt:
>> But why is the heading part of the diagram?
> Because that is how the typesetting mechanism for syntax diagrams work.

That's not true (at least not in diagrams other than in Free Pascal).
It is very illogical to begin a diagram with the name of what the diagramm 
should specify.
The name has to be put *in front* of the diagram but not inside.
That's like writing a procedure or function and the first command
after the begin is a (recursively) call of the procedure itself.
This would lead to an endless loop.

See page 61 where "object types" are declared with a correct diagramm.
The diagram name ("object types") is on an extra line and
the diagram itself (which starts with 2 arrows) begins on the next line.
So when I start my run throught the diagram at the 2 arrows the first word
I can get is "packed" (and not "object types").
The arrows/line starts *after* the name, not before.
But already the next line is incorrect again because "heritage" is
part of the diagram (the line/2 arrows start left of it but should not).

Look at http://en.wikipedia.org/wiki/Syntax_diagram and see the diagrams at the 
bottom.
These are correct syntax diagrams.
The name ("expression:", "term:", "factor:", etc.) is on one line
and the diagram (the line which here starts with a circle) begins on the next 
line.
Name and diagram can also be on one line (though this makes it already less 
clear)
but the name of the diagram should never appear after the 2 arrows (which start
the path).

___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation, syntax diagrams

[Michael Van Canneyt]

On Fri, 10 Jan 2014, Constantine Yannakopoulos wrote:


On Thu, Jan 9, 2014 at 9:55 AM, Sven Barth  wrote:
  Am 08.01.2014 22:01, schrieb Michael Van Canneyt:
You can preview the result at

http://www.freepascal.org/~michael/ref/refch3.html

You might additionally mention that these type aliases also allow different 
operator and (AFAIK also) function overloads.


Also, that they have different RTTI records, that is the TypeInfo() compiler 
function returns different pointers for the
original and derived type, while for simple type aliases (no "type" after "=") 
it returns the same pointer.

In Delphi and I suppose in Lazarus this is often used in order to register a 
specific property editor for each property of an
otherwise common type that has special semantics, e.g.

type
  TFileName = type string;


I already mention all this.

Michael.___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation, syntax diagrams

[Michael Van Canneyt]

On Thu, 9 Jan 2014, Jürgen Hestermann wrote:


Am 2014-01-09 08:26, schrieb Michael Van Canneyt:

That what should be declared is repeated in the declaration
itself which makes no sense to me.
A syntax diagram for 'type declaration' (which is written in the heading 

already)

The heading is a caption.
In typesetting, normally that is not considered part of the diagram itself,
just like a table or figure caption is not considered part of the table or 

figure.

But why is the heading part of the diagram?


Because that is how the typesetting mechanism for syntax diagrams work.

Michael.___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation, syntax diagrams

[Sven Barth]

On 10.01.2014 00:32, Constantine Yannakopoulos wrote:

On Thu, Jan 9, 2014 at 9:55 AM, Sven Barth mailto:pascaldra...@googlemail.com>> wrote:

Am 08.01.2014 22:01, schrieb Michael Van Canneyt:

You can preview the result at

http://www.freepascal.org/~__michael/ref/refch3.html


You might additionally mention that these type aliases also allow
different operator and (AFAIK also) function overloads.


Also, that they have different RTTI records, that is the TypeInfo()
compiler function returns different pointers for the original and
derived type, while for simple type aliases (no "type" after "=") it
returns the same pointer.


This is already mentioned in Michael's preview.

Regards,
Sven

___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation, syntax diagrams

[Constantine Yannakopoulos]

On Thu, Jan 9, 2014 at 9:55 AM, Sven Barth wrote:

> Am 08.01.2014 22:01, schrieb Michael Van Canneyt:
>
>  You can preview the result at
>>
>> http://www.freepascal.org/~michael/ref/refch3.html
>>
> You might additionally mention that these type aliases also allow
> different operator and (AFAIK also) function overloads.
>

Also, that they have different RTTI records, that is the TypeInfo()
compiler function returns different pointers for the original and derived
type, while for simple type aliases (no "type" after "=") it returns the
same pointer.

In Delphi and I suppose in Lazarus this is often used in order to register
a specific property editor for each property of an otherwise common type
that has special semantics, e.g.

type
  TFileName = type string;

--
Constantine
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation, syntax diagrams

[Jürgen Hestermann]

Am 2014-01-09 08:26, schrieb Michael Van Canneyt:
>> That what should be declared is repeated in the declaration
>> itself which makes no sense to me.
>> A syntax diagram for 'type declaration' (which is written in the heading 
already)
> The heading is a caption.
> In typesetting, normally that is not considered part of the diagram itself,
> just like a table or figure caption is not considered part of the table or 
figure.

But why is the heading part of the diagram?
It should be just that: A heading (in an extra line before the diagram).
For example on page 29:


String Type
- string type -- STRING --||
  \-- [ -- unsigned integer -- ] --/

There is already the heading "String Type",
then - as part of the diagram (surrounded by lines) - "string type" appears 
again!
Why?
That's totally confusing.
It should be like this:

String Type:
- STRING ||
 \-- [ -- unsigned integer -- ] --/

or

String Type =
- STRING ||
 \-- [ -- unsigned integer -- ] --/

___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation, syntax diagrams

[Michael Van Canneyt]

On Thu, 9 Jan 2014, Sven Barth wrote:


Am 08.01.2014 22:01, schrieb Michael Van Canneyt:

You can preview the result at

http://www.freepascal.org/~michael/ref/refch3.html
You might additionally mention that these type aliases also allow different 
operator and (AFAIK also) function overloads.


Will do, thanks.

Michael.
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation, syntax diagrams

[Sven Barth]

Am 08.01.2014 22:01, schrieb Michael Van Canneyt:

You can preview the result at

http://www.freepascal.org/~michael/ref/refch3.html
You might additionally mention that these type aliases also allow 
different operator and (AFAIK also) function overloads.


Regards,
Sven
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation, syntax diagrams

[Michael Van Canneyt]

On Thu, 9 Jan 2014, Jürgen Hestermann wrote:


Am 2014-01-08 21:12, schrieb Sven Barth:

I don’t know whether the first 'type' is the standard type definition
entry keyword but if so it should be typed in bold font.

No, it's not the keyword, it's a "reference" to the syntax diagram named
"type" directly below it (though I have to admit that this is not 

necessarily clear...).

It seems that all syntax diagrams have the same issue:

That what should be declared is repeated in the declaration
itself which makes no sense to me.
A syntax diagram for 'type declaration' (which is written in the heading 
already)


The heading is a caption.

In typesetting, normally that is not considered part of the diagram itself, 
just like a table or figure caption is not considered part of the table or 
figure.


Where can I find the documentation for my original question about the 

double TYPE keyword?
This link explains it a bit: 

http://docwiki.embarcadero.com/RADStudio/XE5/en/Type_Compatibility_and_Identity

But that's not part of the Free Pascal documentation.
So it's not available in the documentation of Free Pascal?


As Sven surmised, it will be in the next version. 
I posted a preview for your benefit, please see my initial answer.


Michael.___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation, syntax diagrams

[Sven Barth]

On 09.01.2014 07:22, Jürgen Hestermann wrote:

 >> Where can I find the documentation for my original question about
the double TYPE keyword?
 > This link explains it a bit:
http://docwiki.embarcadero.com/RADStudio/XE5/en/Type_Compatibility_and_Identity


But that's not part of the Free Pascal documentation.
So it's not available in the documentation of Free Pascal?


Didn't I just write that it is indeed still missing?! (though Michael 
seems to have fixed it in the SVN sources, so this fix will (maybe?) be 
part of the 2.6.4 documentation)



Who can know when he has to look at the Delphi
documentation (which version?) and when this differs from Free Pascal?


You shouldn't need to look at the Delphi documentation. It's just that I 
wanted to answer your question with a source. If I the feature would 
have been available in TP and the syntax would be available I would have 
linked that. Or the ISO specification or whatever. This has nothing to 
do with "this is found in FPC's documentation so you need to look 
somewhere else", but I simply digged out a link were this feature is 
described.


And to come back to the first sentence of the paragraph: and this is 
where you come into play: by raising such questions you can help improve 
the documentation.


Regards,
Sven
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation, syntax diagrams

[Jürgen Hestermann]

Am 2014-01-08 21:12, schrieb Sven Barth:
>> I don’t know whether the first 'type' is the standard type definition
>> entry keyword but if so it should be typed in bold font.
> No, it's not the keyword, it's a "reference" to the syntax diagram named
> "type" directly below it (though I have to admit that this is not necessarily 
clear...).

It seems that all syntax diagrams have the same issue:

That what should be declared is repeated in the declaration
itself which makes no sense to me.
A syntax diagram for 'type declaration' (which is written in the heading 
already)
cannot have the text 'type declaration' again in the diagram.
The diagram just should explain 'type declaration'.
Following the line should reveal a syntactical correct 'type declaration'
so it should not contain itself the text 'type declaration'.
Otherwise it recursively explains itself in an endless loop.



>> Where can I find the documentation for my original question about the double 
TYPE keyword?
> This link explains it a bit: 
http://docwiki.embarcadero.com/RADStudio/XE5/en/Type_Compatibility_and_Identity

But that's not part of the Free Pascal documentation.
So it's not available in the documentation of Free Pascal?
Who can know when he has to look at the Delphi
documentation (which version?) and when this differs from Free Pascal?


___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation, syntax diagrams

[Sven Barth]

Am 08.01.2014 22:11 schrieb "Jürgen Hestermann" :
> But why is it not part of the documentation?

We are all just human beings that make mistakes. Nobody is perfect and so
is the documentation.

> If nobody takes care of the documentation anymore
> then it should better be removed at all.

It's actively maintained on Subversion...

> IMO the current documentation is very bad and outdated.

... but only "publicly" updated on each release.

> Without a reliable documentation all programming is just guessing
> and hoping and trial and error.

Then please continue to point out inconsistencies and unclear parts so that
the documentation can be improved. But please do so - as Michael suggested
as well - without this "bah, there's a problem, so it's crap"-attitude. We
are all working on this during our free time afterall...

Regards,
Sven
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation, syntax diagrams

[Michael Van Canneyt]

On Wed, 8 Jan 2014, Jürgen Hestermann wrote:


Am 08.01.2014 21:01, schrieb Sven Barth:

No, an alias would be
=== code begin ===
type
  Real = Double;
=== code end ===
Using the "type" behind the "=" tells the compiler to declare a new type 

based on the right side.
So a "Double" and a "Real" are not assignment compatible and can have 

different sets of operator overloads.

Thanks for the answer.
I already suspected such a definition.

But why is it not part of the documentation?
If nobody takes care of the documentation anymore
then it should better be removed at all.


I am well aware that documentation needs updating. 
The SVN logs will convince you that it is updated on a regular basis.


I usually respond positively to all requests for updates, as my other reply 
proves.

That is, provided they are put in a positive form, and not with a dosis of 
poison as you just provided.

If you insist on being negative, please find another mailing list to do so.

Michael.___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation, syntax diagrams

[Jürgen Hestermann]

Am 08.01.2014 21:01, schrieb Sven Barth:
> No, an alias would be
> === code begin ===
> type
>   Real = Double;
> === code end ===
> Using the "type" behind the "=" tells the compiler to declare a new 
type based on the right side.
> So a "Double" and a "Real" are not assignment compatible and can have 
different sets of operator overloads.


Thanks for the answer.
I already suspected such a definition.

But why is it not part of the documentation?
If nobody takes care of the documentation anymore
then it should better be removed at all.
IMO the current documentation is very bad and outdated.
Not very inviting for potentially interested programmers.
Without a reliable documentation all programming is just guessing
and hoping and trial and error.

___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation, syntax diagrams

[Michael Van Canneyt]

On Wed, 8 Jan 2014, Howard Page-Clark wrote:


On 08/01/2014 20:01, Sven Barth wrote:

On 08.01.2014 19:40, Howard Page-Clark wrote:

On 08/01/2014 18:16, Jürgen Hestermann wrote:


Today I found this type definition in some FreePascal sources:

TypeReal =type Double;

I wondered what the second “type” keyword means here (I have never seen
this before).


You are being rather obtuse.
Ignore the diagrams in the docs if they don't help you.

The double use of type here simply means that the "Real" type is being
defined as an alias for double. The two type identifiers now mean
exactly the same thing as the "=" indicates.


No, an alias would be

=== code begin ===

type
   Real = Double;

=== code end ===

Using the "type" behind the "=" tells the compiler to declare a new type
based on the right side. So a "Double" and a "Real" are not assignment
compatible and can have different sets of operator overloads.


That is not quite correct.

They ARE assignment compatible, but can indeed have different sets of overloads.

As in the following example:

home: >./ta
Different types
home: >cat ta.pp

Type
  TA = Integer;
  TB = Type TA;

Var
  A : TA;
  B : TB;

begin
  B:=1;
  A:=B;
  if TypeInfo(TA)<>TypeInfo(TB) then
Writeln('Different types');
end.

Michael.
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation, syntax diagrams

[Michael Van Canneyt]

On Wed, 8 Jan 2014, Jürgen Hestermann wrote:



Today I found this type definition in some FreePascal sources:

TypeReal =type Double;

I wondered what the second “type” keyword means here (I have never seen this 
before).



So I looked at 
http://www.freepascal.org/docs-html/ref/refch3.html#refse17.html


where it says:

_
Type declaration

-- - - - -|-- --- type declaration identifier = type 
|- --|; hint directives

___

Although type declarations are very fundamental and I am using them
since 30 years I can’t find out what this diagram is trying to tell me.

For example, I am missing the keyword “TYPE” in this syntax diagramm.


That is right, since it is not the diagram for the type declaration block, 
which appears later in the manual.


However, following your remark I have done some reworking of this part. 
I have referred to the diagram of the type declaration block, and I have 
moved the type alias description to a separate section which explains the 
difference between the 2 concepts:


Type
  MyInteger = Integer;

and
  MyInteger = Type Integer;

You can preview the result at

http://www.freepascal.org/~michael/ref/refch3.html

Michael.___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation, syntax diagrams

[Howard Page-Clark]

On 08/01/2014 20:01, Sven Barth wrote:

On 08.01.2014 19:40, Howard Page-Clark wrote:

On 08/01/2014 18:16, Jürgen Hestermann wrote:


Today I found this type definition in some FreePascal sources:

TypeReal =type Double;

I wondered what the second “type” keyword means here (I have never seen
this before).


You are being rather obtuse.
Ignore the diagrams in the docs if they don't help you.

The double use of type here simply means that the "Real" type is being
defined as an alias for double. The two type identifiers now mean
exactly the same thing as the "=" indicates.


No, an alias would be

=== code begin ===

type
   Real = Double;

=== code end ===

Using the "type" behind the "=" tells the compiler to declare a new type
based on the right side. So a "Double" and a "Real" are not assignment
compatible and can have different sets of operator overloads.


Thanks for the clarification. That is a distinction worth drawing 
attention to in the documentation, and its relevance when writing 
overloaded routines.

Looks like the obtuseness is at this end, as well as at Jürgen's.

Howard

___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation, syntax diagrams

[Sven Barth]

On 08.01.2014 19:16, Jürgen Hestermann wrote:


Today I found this type definition in some FreePascal sources:

TypeReal =type Double;

I wondered what the second “type” keyword means here (I have never seen
this before).


So I looked at
http://www.freepascal.org/docs-html/ref/refch3.html#refse17.html

where it says:

_
Type declaration

-- - - - -|-- --- type declaration identifier =
type |- --|; hint directives
___

Although type declarations are very fundamental and I am using them
since 30 years I can’t find out what this diagram is trying to tell me.

For example, I am missing the keyword “TYPE” in this syntax diagramm.


You are right. That seems to be missing.



I don’t know whether the first “type” is the standard type definition
entry keyword
but if so it should be typed in bold font.


No, it's not the keyword, it's a "reference" to the syntax diagram named 
"type" directly below it (though I have to admit that this is not 
necessarily clear...).




It can also be part of a text “type declaration” (which is obviously not
a keyword).

But then why does “type declaration” appear twice (in the heading
**and** the syntax diagramm)?
Following the line should generate a valid path to a (syntactical)
correct type declaration.
But why is then "type declaration" part of a type declaration?
Makes no sense to me.
It would generate an endless recursive loop.

Another problem is “hint directives”.

What is it? There is no link nor text that explains it.

So I started another google search for “hint directives”

but I only found this:
http://www.freepascal.org/docs-html/ref/refse5.html


where it says that hint directives are for variable declarations but not
for type declarations


Yes, this is indeed the correct documentation and maybe this should be 
linked better...



(and again "hint directives" are part of hint directives which is not
correct IMO).


The "hint directives" is again the "name" of the syntax diagram.



Can someone clarify this documentation please?

Where can I find the documentation for my original question about the
double TYPE keyword?


This link explains it a bit: 
http://docwiki.embarcadero.com/RADStudio/XE5/en/Type_Compatibility_and_Identity


Regards,
Sven
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation, syntax diagrams

[Sven Barth]

On 08.01.2014 19:40, Howard Page-Clark wrote:

On 08/01/2014 18:16, Jürgen Hestermann wrote:


Today I found this type definition in some FreePascal sources:

TypeReal =type Double;

I wondered what the second “type” keyword means here (I have never seen
this before).


You are being rather obtuse.
Ignore the diagrams in the docs if they don't help you.

The double use of type here simply means that the "Real" type is being
defined as an alias for double. The two type identifiers now mean
exactly the same thing as the "=" indicates.


No, an alias would be

=== code begin ===

type
  Real = Double;

=== code end ===

Using the "type" behind the "=" tells the compiler to declare a new type 
based on the right side. So a "Double" and a "Real" are not assignment 
compatible and can have different sets of operator overloads.


Regards,
Sven
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation, syntax diagrams

[Howard Page-Clark]

On 08/01/2014 18:16, Jürgen Hestermann wrote:


Today I found this type definition in some FreePascal sources:

TypeReal =type Double;

I wondered what the second “type” keyword means here (I have never seen
this before).


You are being rather obtuse.
Ignore the diagrams in the docs if they don't help you.

The double use of type here simply means that the "Real" type is being 
defined as an alias for double. The two type identifiers now mean 
exactly the same thing as the "=" indicates.


The documentation for hint directives gives three clear and explicit 
examples of different hint directives showing how to declare them and 
the compiler-generated hints that result from their use.


What more do you want?

Howard



___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

[fpc-pascal] Documentation, syntax diagrams

[Jürgen Hestermann]

  
  


  
  
  
  

  Today I found
  this type definition in some FreePascal sources:

   
  Type  
Real  =   type Double;

   
  I wondered
  what the second “type” keyword means here (I have never
  seen this before).
  
   
  So I looked
  at 
http://www.freepascal.org/docs-html/ref/refch3.html#refse17.html
   
  where it
  says:
   
  _
  Type declaration
  

___
   
  Although type
  declarations are very fundamental and I am using them 
  since 30 years I can’t find out what this diagram is
  trying to tell me.
  For example, I am missing the
keyword “TYPE” in this syntax diagramm.
   
  I don’t know
  whether the first “type” is the standard type definition
  entry keyword
  but if so it should be typed in bold font.

  It can also
  be part of a text “type declaration” (which is obviously
  not a keyword).
  But then why
  does 
 “type declaration” appear twice (in the heading
  *and* the syntax diagramm)?
  Following the line should generate a valid path to a
  (syntactical) correct type declaration.
  But why is then "type declaration" part of a type
  declaration?
  Makes no sense to me.
  It would generate an endless recursive loop.

   
  Another
  problem is “hint directives”.
  What is it?
  There is no link nor text that explains it.
  So I started
  another google search for “hint directives”
  but I only
  found this: 
http://www.freepascal.org/docs-html/ref/refse5.html
  where it says
  that hint directives are for variable declarations but not
  for type declarations
  (and again "hint directives" are part of hint directives
  which is not correct IMO).
   
  Can someone
  clarify this documentation please?
  Where can I
  find the documentation for my original question about the
  double TYPE keyword?
   

  

  

___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

[fpc-pascal] Documentation site: incorrect manual name

[Reinier Olislagers]

On
http://www.freepascal.org/docs-html/
I find
FCL (Free Class Library) reference manual.

however the doc itself (and the 2.6 PDF) specifies Free Component Library

Could this be changed on the site? Does this need to be changed in
Lazarus default online help settings as well?

Thanks,
Reinier
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation

[dev . dliw]

> Well, I have planned a inline-to-external conversion for fpdoc for exactly
> this reason.
That's nice to hear...
[Sorry for late reply]

d.l.l.i.w
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation

[Graeme Geldenhuys]

On 18/12/12 01:25, luciano de souza wrote:
> But my question is: FPDoc can be used without
> an IDE?

Yes, fpdoc is a command line tool, just the fpc (The free pascal compiler).

Some get confused between the fpdoc program, and the FPDoc Editor
(add-on) included within Lazarus IDE. The latter is used to edit the XML
description files (documentation).


> If true, would I have to create the XML structure manually?

I always write my XML description files with a text editor, simply
because there exists no editor application that supports everything
fpdoc syntax does. Also the fpdoc XML syntax is rather simple. I use
MSEide as my editor of choice for documentation - due to much better
code templates support. I have setup quite a few fpdoc code templates in
MSEide, which speeds up my writing of fpdoc xml syntax. That way I can
rather concentrate on writing the documentation and not the XML tags (or
fighting with some documentation editor tool).


> Pasdoc is a very good tool, but that's true the source code becomes 
> overcrowded.

It is very clear that it is a personal preference. There is no right or
wrong. Some like inline documentation, others like external
documentation. I like complete and detailed documentation, not just
one-liners. So External Documentation files is the only way for me,
otherwise I will never be able to read my object pascal source code.
Plus, using fpdoc, I can generate PDF, INF, CHM and HTML output from the
same XML description files.


Regards,
  - Graeme -

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

___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation

[luciano de souza]

I have never used FPDoc, but I'd like to understand how it would work
in my specific case.
I am blind. I use screen reader. I compile my projects without the
intervenience of an IDE. No Lazarus, No FPC console ID, I compile my
projects with commands like that:

fpc myprog.pp

If Myprog.pp has the Pasdoc marks, I can create the documentation also
by means of commandline. But my question is: FPDoc can be used without
an IDE? If true, would I have to create the XML structure manually?
Pasdoc is a very good tool, but that's true the source code becomes overcrowded.
For my case, Pasdoc seems to be better becouse I won't have an IDE to
create the XML. Is this true?


2012/12/17, dev.d...@gmail.com :
> Hi,
> as the question whether inline or external source docs are the way to go
> (again?) came up, here are my thoughts (currently searching for the "best"
> solution :) ):
>
> I personally prefer external docs (and thus started to use fpdoc);
> reasons are uncluttered source, less scrolling and (if you strictly limit
> oneself to 80 chars per line) readability on small screens (mobile).
> At the same time, I use short single (!) line comments to functions, very
> much
> the way pasdoc would use them.
>
> For sources in an early state (moving code around etc.) external
> documentation
> is really annoying, for the detailed documentation of mature source inline
> docs are simply unsuitable IMHO.
>
> Therefore I would really like to see a feature that combines both
> approaches,
> small inline comments, e.g. for IDE tooltips and overview documentation
> together with the possibility to have more detailed infos in external
> files.
>
> Don't get me wrong, that's not an complaint...
> ... I don't how much work it would be to extend fpdoc, but I really would
> like
> to contribute if I knew where to start [and had some more time...] :)
>
> Btw. I really like the lazarus fpdoc GUI...
>
> Just my 2 cents,
> d.l.i.w
>
>
> ___
> fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
> http://lists.freepascal.org/mailman/listinfo/fpc-pascal
>


-- 
Luciano de Souza
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation

[Graeme Geldenhuys]

On 17/12/12 21:45, Mattias Gaertner wrote:
> 
> I thought that was fixed?

OK, my apologies for the false alarm. The XML generation seems fixed now.

There are other issues with the FPDoc Editor dialog though. Off the top
of my head:

 - It allows you to enter long descriptions for method arguments, when
   only short descriptions are allowed. I'm not sure what the fpdoc
   manual says about this.
 - Same as above, but for enums. I did confirm this with Michael, and
   the fpdoc manual actually mentions this.
 - No formatting buttons for things like Unordered List, Ordered Lists,
   List Items etc.
 - "Underline" and "Insert URL" has the same glyphs on the small
   buttons.
 - No place to specify the Package Name when creating a new XML file. It
   can take a while to figure out why that unit's documentation doesn't
   appear when you generate fpdoc output.

There was more, but this was just a quick list of what I could remember now.



Regards,
  - Graeme -

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

___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation

[Graeme Geldenhuys]

On 17/12/12 21:45, Mattias Gaertner wrote:
> 
> I thought that was fixed?


Umm, I'll have to double check.


Regards,
  - Graeme -

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

___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation

[Mattias Gaertner]

On Mon, 17 Dec 2012 20:44:08 +
Graeme Geldenhuys  wrote:

> On 17/12/12 17:57, dev.d...@gmail.com wrote:
> > 
> > Btw. I really like the lazarus fpdoc GUI...
> 
> Compared to Documentation Insight (a Delphi IDE add-on), the UI of FPDoc
> Editor has a lot to be desired for. Plus the fact that FPDoc Editor
> generates undesired formatted XML for fpdoc is not so nice.

I thought that was fixed?

 
> This makes me not use FPDoc Editor in Lazarus - which is unfortunate.
> But the idea of FPDoc Editor (tied into Lazarus IDE and working with the
> code editor) is great. It just needs some more polish.

Mattias
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation

[Graeme Geldenhuys]

On 17/12/12 17:57, dev.d...@gmail.com wrote:
> 
> Btw. I really like the lazarus fpdoc GUI...

Compared to Documentation Insight (a Delphi IDE add-on), the UI of FPDoc
Editor has a lot to be desired for. Plus the fact that FPDoc Editor
generates undesired formatted XML for fpdoc is not so nice.

This makes me not use FPDoc Editor in Lazarus - which is unfortunate.
But the idea of FPDoc Editor (tied into Lazarus IDE and working with the
code editor) is great. It just needs some more polish.


Regards,
  - Graeme -

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

___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation

[Michael Van Canneyt]

On Mon, 17 Dec 2012, dev.d...@gmail.com wrote:


Hi,
as the question whether inline or external source docs are the way to go
(again?) came up, here are my thoughts (currently searching for the "best"
solution :) ):

I personally prefer external docs (and thus started to use fpdoc);
reasons are uncluttered source, less scrolling and (if you strictly limit
oneself to 80 chars per line) readability on small screens (mobile).
At the same time, I use short single (!) line comments to functions, very much
the way pasdoc would use them.

For sources in an early state (moving code around etc.) external documentation
is really annoying, for the detailed documentation of mature source inline
docs are simply unsuitable IMHO.


Well, I have planned a inline-to-external conversion for fpdoc for exactly this 
reason.

Michael.
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-pascal

[fpc-pascal] Documentation

[dev . dliw]

Hi,
as the question whether inline or external source docs are the way to go 
(again?) came up, here are my thoughts (currently searching for the "best" 
solution :) ):

I personally prefer external docs (and thus started to use fpdoc);
reasons are uncluttered source, less scrolling and (if you strictly limit 
oneself to 80 chars per line) readability on small screens (mobile).
At the same time, I use short single (!) line comments to functions, very much 
the way pasdoc would use them.

For sources in an early state (moving code around etc.) external documentation 
is really annoying, for the detailed documentation of mature source inline 
docs are simply unsuitable IMHO.

Therefore I would really like to see a feature that combines both approaches,
small inline comments, e.g. for IDE tooltips and overview documentation 
together with the possibility to have more detailed infos in external files.

Don't get me wrong, that's not an complaint...
... I don't how much work it would be to extend fpdoc, but I really would like 
to contribute if I knew where to start [and had some more time...] :)

Btw. I really like the lazarus fpdoc GUI...

Just my 2 cents,
d.l.i.w


___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation differences...

[Marco van de Voort]

In our previous episode, Graeme Geldenhuys said:
> Ah, it seems Lazarus is using the broken 'fpdoc' to generate the
> online help.  fpdoc recently fails to generate docs for most units
> because of various changes in the source parses (fcl-passrc) that it
> uses. I had the same problem generating tiOPF and fpGUI docs two or so
> weeks ago.
> 
> I think Michael fixed the problem (fpdoc now only parses Interfaces
> section) recently in Trunk - not sure if that fix made it into 2.4.2
> release coming out soon (lets hope it does).

I've received no request of Michael to merge that.
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation differences...

[Graeme Geldenhuys]

On 23 June 2010 10:40, Torsten Bonde Christiansen  wrote:
>
> From what i can see Lazarus (trunk version) does by default open the Lazarus
> CCR version of the documentation file, this was my main reason for asking on
> the list since TComponent does not exists in the CCR version.

Ah, it seems Lazarus is using the broken 'fpdoc' to generate the
online help.  fpdoc recently fails to generate docs for most units
because of various changes in the source parses (fcl-passrc) that it
uses. I had the same problem generating tiOPF and fpGUI docs two or so
weeks ago.

I think Michael fixed the problem (fpdoc now only parses Interfaces
section) recently in Trunk - not sure if that fix made it into 2.4.2
release coming out soon (lets hope it does).

-- 
Regards,
  - Graeme -


___
fpGUI - a cross-platform Free Pascal GUI toolkit
http://opensoft.homeip.net/fpgui/
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation differences...

[Torsten Bonde Christiansen]

On 2010-06-23 10:29, Graeme Geldenhuys wrote:

Op 2010-06-23 10:15, Torsten Bonde Christiansen het geskryf:

The official FPC documentation is:

   

(http://www.freepascal.org/docs-html/rtl/)
 

FPC does not show "skeleton" or partial documented units in it's
documentation. It is all or nothing.


   

(http://lazarus-ccr.sourceforge.net/docs/rtl/)
 

As far as I know the following is true (please correct me if I am wrong).
The Lazarus team thinks that "skeleton" (empty) or partial documentation is
still handy, so they decided to build their own online documentation, but
includes all units from RTL, FCL, LCL etc...  This is what I heard years
ago, but I don't know if this is still true. I'm also not sure what
versions of FPC units does the Lazarus team use for there online docs
(latest release version or Trunk)
   
From what i can see Lazarus (trunk version) does by default open the 
Lazarus CCR version of the documentation file, this was my main reason 
for asking on the list since TComponent does not exists in the CCR version.


Regards,
Torsten Bonde Christiansen.
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation differences...

[Graeme Geldenhuys]

Op 2010-06-23 10:15, Torsten Bonde Christiansen het geskryf:

The official FPC documentation is:

> (http://www.freepascal.org/docs-html/rtl/) 

FPC does not show "skeleton" or partial documented units in it's
documentation. It is all or nothing.


> (http://lazarus-ccr.sourceforge.net/docs/rtl/)

As far as I know the following is true (please correct me if I am wrong).
The Lazarus team thinks that "skeleton" (empty) or partial documentation is
still handy, so they decided to build their own online documentation, but
includes all units from RTL, FCL, LCL etc...  This is what I heard years
ago, but I don't know if this is still true. I'm also not sure what
versions of FPC units does the Lazarus team use for there online docs
(latest release version or Trunk)


Regards,
  - Graeme -

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

___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation differences...

[Michael Van Canneyt]

On Wed, 23 Jun 2010, Torsten Bonde Christiansen wrote:


Hi List.

I have been wondering for some time now what the difference is between the 
source documentation (online versions) on the pascal website 
(http://www.freepascal.org/docs-html/rtl/) and the one placed on the Lazarus 
CCR website (http://lazarus-ccr.sourceforge.net/docs/rtl/) - this goes not 
just for the RTL, but also FCL.


Sometime i can find information regarding some classes in one but not the 
other, and at othertime it's the other way around.


Perhaps I've overlook something, but I can't seem to find any logic in which 
is the most updated and why some things exist one place and not the other.


Well,

http://www.freepascal.org/docs-html/rtl/

is the official documentation. Normally, it is updated only when a new version 
of the compiler is released. That's all I can say about it.


Michael.

___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-pascal

[fpc-pascal] Documentation differences...

[Torsten Bonde Christiansen]

Hi List.

I have been wondering for some time now what the difference is between 
the source documentation (online versions) on the pascal website 
(http://www.freepascal.org/docs-html/rtl/) and the one placed on the 
Lazarus CCR website (http://lazarus-ccr.sourceforge.net/docs/rtl/) - 
this goes not just for the RTL, but also FCL.


Sometime i can find information regarding some classes in one but not 
the other, and at othertime it's the other way around.


Perhaps I've overlook something, but I can't seem to find any logic in 
which is the most updated and why some things exist one place and not 
the other.


Kind regards,
Torsten Bonde Christiansen.


___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation strangeness

[Graeme Geldenhuys]

On 5 April 2010 21:26, John Coppens wrote:
>
> I'm sure the selection of IPF/INF caused some discussion at the time,
> particularly at a time where xml is the magic recipe for everything ;-)

As Marco said, the class documentation is in XML and gets transformed
to other "final" formats via the 'fpdoc' tool.

IPF is a easy to understand mark-up language - similar to HTML, just
shorter to type. IPF is also dedicated to documentation/books only,
and describes the various text (similar to LaTeX). Later I'll
implement some help authoring tool (if the need arises). MSEide
already has syntax highlighting for IPF, which helps a lot in
authoring help.


-- 
Regards,
  - Graeme -


___
fpGUI - a cross-platform Free Pascal GUI toolkit
http://opensoft.homeip.net/fpgui/
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation strangeness

[Marco van de Voort]

In our previous episode, John Coppens said:
> Graeme Geldenhuys  wrote:
> 
> > Wikipedia has some information on IPF.
> >   http://en.wikipedia.org/wiki/Information_Presentation_Facility
> 
> Thanks for the extensive answer, Graeme!
> 
> I'm sure the selection of IPF/INF caused some discussion at the time,
> particularly at a time where xml is the magic recipe for everything ;-)

The library documentation is in XML format, from which other formats can be
generated. 

The other docs are in LaTeX, which is a bit problematic to transform.
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation strangeness

[John Coppens]

On Mon, 5 Apr 2010 17:25:44 +0200
Graeme Geldenhuys  wrote:

> Wikipedia has some information on IPF.
>   http://en.wikipedia.org/wiki/Information_Presentation_Facility

Thanks for the extensive answer, Graeme!

I'm sure the selection of IPF/INF caused some discussion at the time,
particularly at a time where xml is the magic recipe for everything ;-)

Greetings,
John
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation strangeness

[Graeme Geldenhuys]

On 5 April 2010 16:19, John Coppens  wrote:
>
> Sorry for my ignorance - what are INF files? Google seems confused too.

INF files are compiled (binary) IPF [Information Presentation
Facility] help files. It is the help file and digital document format
originally created by IBM for the OS/2 operating system. IPF is a very
easy to learn mark-up language specifically designed for documentation
and produces very good text layout. INF can be used as a help file or
as a digital book (similar to PDF).

For the fpGUI Toolkit project, I looked for a cross-platform help file
format that I can use for the fpGUI project itself and that developers
could use to implement help for their own projects/applications. I
needed something that is a single file (so no raw HTML), that is very
fast and compact. I evaluated various help file formats and decided to
use INF.

Since then, I created a add-on for FPC's fpdoc program to generate IPF
output for class documentation. I also implemented a cross-platform
INF viewer called fpGUI DocView. The Open Watcom project implemented a
open source IPF Compiler (wipfc) which runs under OS/2, DOS, Windows
and Linux. wipfc is a 1MB download. At a later date I'll implement my
own IPF Compiler in Object Pascal which can hopefully be included with
FPC.

I also translated the FPC Language Reference (latex) document to INF
format, so now language reference, class documentation (RTL & FCL0
help is available in IDE's like Lazarus or MSEide. DocView is very
easy to integrate with these IDE's via their 'external tools' options
- no need to write some add-on plugin/package for the IDE's.

Docview supports: Table of Contents, runtime generated Index or can
use the Index included in the INF file, bookmarks, inline annotations,
full text searching, search keyword highlighting, reading multiple INF
files together as one help file (all done at runtime), font
substitution, exporting articles to text etc.

Wikipedia has some information on IPF.
  http://en.wikipedia.org/wiki/Information_Presentation_Facility

I'm busy redesigning the fpGUI website which will then include more
information regarding INF and DocView and some screenshots.

-- 
Regards,
  - Graeme -


___
fpGUI - a cross-platform Free Pascal GUI toolkit
http://opensoft.homeip.net/fpgui/
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation strangeness

[John Coppens]

On Mon, 5 Apr 2010 00:07:07 +0200
Graeme Geldenhuys  wrote:

> Luckily (no offence meant) the documentation doesn't change that much
> or that quickly. I'll probably keep to the same release cycle as FPC -
> whenever a new FPC is released, release new FPC INF docs too.

Hi Graeme,

Sorry for my ignorance - what are INF files? Google seems confused too.

John
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation strangeness

[Graeme Geldenhuys]

On 05/04/2010, Michael Van Canneyt wrote:
>> Yes, it's still on my todo list.
>
> One day, you should publish this list.

:-) By the sounds of things, I don't think your list is going to be
much smaller than mine. ;-)


-- 
Regards,
  - Graeme -


___
fpGUI - a cross-platform Free Pascal GUI toolkit
http://opensoft.homeip.net/fpgui/
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation strangeness

[Michael Van Canneyt]

On Mon, 5 Apr 2010, Graeme Geldenhuys wrote:


On 4 April 2010 18:21, Michael Van Canneyt  wrote:


The disadvantage being that they are not updated when the documentation
is updated.


Luckily (no offence meant) the documentation doesn't change that much
or that quickly. I'll probably keep to the same release cycle as FPC -
whenever a new FPC is released, release new FPC INF docs too.



That said, weren't you going to send me a patch to implement INF support
in fpdoc ?


Yes, it's still on my todo list.


One day, you should publish this list.

Careful, you might create a black hole when doing so... ;)

Michael.
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation strangeness

[Graeme Geldenhuys]

On 4 April 2010 18:21, Michael Van Canneyt  wrote:
>
> The disadvantage being that they are not updated when the documentation
> is updated.

Luckily (no offence meant) the documentation doesn't change that much
or that quickly. I'll probably keep to the same release cycle as FPC -
whenever a new FPC is released, release new FPC INF docs too.


> That said, weren't you going to send me a patch to implement INF support
> in fpdoc ?

Yes, it's still on my todo list.


-- 
Regards,
  - Graeme -


___
fpGUI - a cross-platform Free Pascal GUI toolkit
http://opensoft.homeip.net/fpgui/
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation strangeness

[Michael Van Canneyt]

On Sun, 4 Apr 2010, Graeme Geldenhuys wrote:


On 4 April 2010 12:11, Michael Van Canneyt  wrote:


That depends on the PDF reader. Searching is virtually instantaneous on
Mac OS X with its default PDF reader (but it's indeed fairly slow with at
least Acrobat Reader).


I guess Mac has better PDF support than any other platform. Acrobat
Reader on Linux is slow to start up, does not come standard with Linux
distros, is a rather large download.



Okular also searches very fast.


I have never heard of Okular, but a quick Google search reveals it's
part of KDE apps. I use Evince (included with Ubuntu) or Acrobat
Reader to view or print PDF's. Each have there own strengths, but no
single one is a clear winner.

I must admit, I haven't used FPC's PDF or HTML docs in some time. The
INF versions are very near 100% complete, so they already fulfil my
documentation needs and integrate well with Lazarus IDE and MSEide.


The disadvantage being that they are not updated when the documentation
is updated.

That said, weren't you going to send me a patch to implement INF support
in fpdoc ?

Michael.
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation strangeness

[Graeme Geldenhuys]

On 4 April 2010 12:11, Michael Van Canneyt  wrote:
>>
>> That depends on the PDF reader. Searching is virtually instantaneous on
>> Mac OS X with its default PDF reader (but it's indeed fairly slow with at
>> least Acrobat Reader).

I guess Mac has better PDF support than any other platform. Acrobat
Reader on Linux is slow to start up, does not come standard with Linux
distros, is a rather large download.


> Okular also searches very fast.

I have never heard of Okular, but a quick Google search reveals it's
part of KDE apps. I use Evince (included with Ubuntu) or Acrobat
Reader to view or print PDF's. Each have there own strengths, but no
single one is a clear winner.

I must admit, I haven't used FPC's PDF or HTML docs in some time. The
INF versions are very near 100% complete, so they already fulfil my
documentation needs and integrate well with Lazarus IDE and MSEide.


-- 
Regards,
  - Graeme -


___
fpGUI - a cross-platform Free Pascal GUI toolkit
http://opensoft.homeip.net/fpgui/
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation strangeness

[Graeme Geldenhuys]

On 4 April 2010 12:24, Michael Van Canneyt  wrote:
>
> The community version ("with comments") should be simply deleted; it causes
> only confusion and more work without any benefit.

+1 for the confusion bit.


> I have removed the links to them.

A good decision.


-- 
Regards,
  - Graeme -


___
fpGUI - a cross-platform Free Pascal GUI toolkit
http://opensoft.homeip.net/fpgui/
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation strangeness

[John Coppens]

On Sun, 4 Apr 2010 12:24:36 +0200 (CEST)
Michael Van Canneyt  wrote:

> The community version ("with comments") should be simply deleted; 
> it causes only confusion and more work without any benefit.
> 
> I have removed the links to them.

Proof of concept: I hadn't found the 'good' one - just the old version.
Thanks for deleting ;-)

John
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation strangeness

[Michael Van Canneyt]

On Sun, 4 Apr 2010, John Coppens wrote:


On Sat, 3 Apr 2010 20:36:56 +0200 (CEST)
mar...@stack.nl (Marco van de Voort) wrote:


The refered documentation (on the FPC community server) is from 2006:

Reference guide for Free Pascal, version 2.2
Document version 2.0
August 2006


Yep... But that is the manual which is on-line at the moment. I thought
it would be up-to-date, but it seems the 2.4 package has a much newer
html version.

Wouldn't it be advisable (and probably save a lot of questions) to get
the online version updated?


The online version is up to date. That is, the one on

ftp://ftp.freepascal.org/pub/fpc/docs-pdf/user.pdf

or

http://www.freepascal.org/docs-html/user/user.html

if you prefer HTML.

The community version ("with comments") should be simply deleted; 
it causes only confusion and more work without any benefit.


I have removed the links to them.

Michael.
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation strangeness

[Michael Van Canneyt]

On Sun, 4 Apr 2010, Jonas Maebe wrote:



On 03 Apr 2010, at 22:48, Graeme Geldenhuys wrote:


I must agree. PDF's looks good on paper, but is terrible to search on
screen (very slow)


That depends on the PDF reader. Searching is virtually instantaneous on 
Mac OS X with its default PDF reader (but it's indeed fairly slow with 
at least Acrobat Reader).


Okular also searches very fast.

Michael.
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation strangeness

[John Coppens]

On Sat, 3 Apr 2010 20:36:56 +0200 (CEST)
mar...@stack.nl (Marco van de Voort) wrote:

> The refered documentation (on the FPC community server) is from 2006:
> 
> Reference guide for Free Pascal, version 2.2
> Document version 2.0
> August 2006

Yep... But that is the manual which is on-line at the moment. I thought
it would be up-to-date, but it seems the 2.4 package has a much newer
html version.

Wouldn't it be advisable (and probably save a lot of questions) to get
the online version updated?

John
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation strangeness

[Jonas Maebe]

On 03 Apr 2010, at 22:48, Graeme Geldenhuys wrote:

> I must agree. PDF's looks good on paper, but is terrible to search on
> screen (very slow)

That depends on the PDF reader. Searching is virtually instantaneous on Mac OS 
X with its default PDF reader (but it's indeed fairly slow with at least 
Acrobat Reader).


Jonas___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation strangeness

[Graeme Geldenhuys]

On 3 April 2010 20:36, Marco van de Voort  wrote:
>
> The PDF is mostly good for printing, nothing else.

I must agree. PDF's looks good on paper, but is terrible to search on
screen (very slow), hyperlinks/cross-linking is not always available,
no context sensitive help integration from IDE's etc. The INF versions
solve all those issues and has much better screen format/layout than
the CHM versions.


-- 
Regards,
  - Graeme -


___
fpGUI - a cross-platform Free Pascal GUI toolkit
http://opensoft.homeip.net/fpgui/
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation strangeness

[Marco van de Voort]

In our previous episode, Michael Van Canneyt said:
> >   http://sayamindu.randomink.org/conv_guide/ch01s02.html
> 
> I am aware of the ligature problem; The main problem is that it requires
> re-configuration of tex4ht to fix it. I did it once, maybe an update 
> destroyed this work :/

The refered documentation (on the FPC community server) is from 2006:

Reference guide for Free Pascal, version 2.2
Document version 2.0
August 2006

Micha?l Van Canneyt
 
> The good news is that the PDF documentation is correct, and
> is still - as it always been - the preferred format.

The PDF is mostly good for printing, nothing else.

I don't print the docs at each release.
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation strangeness

[Graeme Geldenhuys]

On 3 April 2010 18:10, Michael Van Canneyt  wrote:
>
> The good news is that the PDF documentation is correct, and
> is still - as it always been - the preferred format.


On a side note: The INF version of the Language Reference is also
correct. Just a few more sections to complete, then I'll make it
publicly available - including the binary DocView (INF viewer).


-- 
Regards,
  - Graeme -


___
fpGUI - a cross-platform Free Pascal GUI toolkit
http://opensoft.homeip.net/fpgui/
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation strangeness

[Michael Van Canneyt]

On Sat, 3 Apr 2010, Graeme Geldenhuys wrote:


On 3 April 2010 17:33, John Coppens  wrote:


I was using the Pascal reference manual, and found that 'fi' was replaced
by some strange character... Modifiers came out as Modi???ers etc. This
seems to have happened all over the document at:


Clearly the export as HTML from LaTeX doesn't support the 'fi'
ligature. The 'f' and 'i' becomes one character. The actual LaTeX
documentation  (*.tex) files has it as 'f' and 'i', so there is no
need for fixing the documentation - it's just the HTML export that is
buggy.

Here is an example of what should have happened.
  http://sayamindu.randomink.org/conv_guide/ch01s02.html


I am aware of the ligature problem; The main problem is that it requires
re-configuration of tex4ht to fix it. I did it once, maybe an update 
destroyed this work :/


The good news is that the PDF documentation is correct, and
is still - as it always been - the preferred format.

Michael.
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation strangeness

[Graeme Geldenhuys]

On 3 April 2010 17:33, John Coppens  wrote:
>
> I was using the Pascal reference manual, and found that 'fi' was replaced
> by some strange character... Modifiers came out as Modi�ers etc. This
> seems to have happened all over the document at:

Clearly the export as HTML from LaTeX doesn't support the 'fi'
ligature. The 'f' and 'i' becomes one character. The actual LaTeX
documentation  (*.tex) files has it as 'f' and 'i', so there is no
need for fixing the documentation - it's just the HTML export that is
buggy.

Here is an example of what should have happened.
   http://sayamindu.randomink.org/conv_guide/ch01s02.html



-- 
Regards,
  - Graeme -


___
fpGUI - a cross-platform Free Pascal GUI toolkit
http://opensoft.homeip.net/fpgui/
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-pascal

[fpc-pascal] Documentation strangeness

[John Coppens]

Hi people,

I was using the Pascal reference manual, and found that 'fi' was replaced
by some strange character... Modifiers came out as Modi�ers etc. This
seems to have happened all over the document at:

http://community.freepascal.org:1/docs-html/ref/ref.html

This is just a little frustrating, but maybe it's an easy thing to avoid
and regenerate the document. If it's more work-intensive, I offer my help
in editing...

John
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-pascal

[fpc-pascal] Documentation for the UTF-8 Functions

[David B Copeland]

Can anyone point me to where the utf-8 functions are documented? I have
tried looking in the docs for the RTL but could not find them.

Thanks,
Dave.



___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation and posts suggestions [LONG]

[Michael Van Canneyt]

On Sun, 15 Mar 2009, Francisco Reyes wrote:

> Tomas Hajny writes:
> 
> > I'm not sure if Francisco meant the Reference Guide or possibly some
> > examples appearing in the other documents;
> 
> I was looking specifically about the rtl pdf.
> 
> 
> >if it's the latter, a more concrete example would be probably useful.
> 
> Where are the examples? I recall seem them in the past, but can't find them
> now.

Only the RTL units have examples in them. FCL units do not, and the classes
unit also do not have them any more. The reason is 2-fold:

- Time
- More complex concepts require more complex examples.

> 
> Also as I become more serious about FPC what would be the recommended order of
> reading the docs?
> 
> I have:
> prog.pdf  ref.pdf  rtl.pdf  user.pdf
> Want to go over them in the coming week. I like to read as much as I can
> before jumping into more serious development. Right now doing a couple of
> simple utilities partly because I need them for work and partly to re-learn
> pascal. 

I don't think it is possible to give an order. Normally I would think
user
ref
prog

and the rtl/fcl as you need them.

> 
> > eyes of a newcomer as suggested by Francisco. I don't think that the places
> > I found (including the dedicated chapter for exceptions in the Reference
> > Guide) make this rule very obvious, so there may be some room for
> > improvement
> 
> Just looked at that part in the reference and agree that it could at least
> mention it needs delphi or objectpascal modes.

I will do so.

> 
> > allowing to change the mode, but the newcomer may not even know / understand
> > that he should be interested in changing the compiler mode 
> 
> Exactly. Specially newcomers may have a good chance to not know what documents
> and in what order they need to read them.
> I think it may be a bit easier for someone coming from Delphi, but someone
> just starting out, may not even know that exception handling is object pascal
> and not part of the standard pascal.

Like I said, I will add some sentences/paragraphs about this.

Michael.
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation and posts suggestions [LONG]

[Michael Van Canneyt]

On Sun, 15 Mar 2009, Tomas Hajny wrote:

> > > * In cases were some code needs a particular mode other than the default 
> > > mode
> > > we can include which mode is needed.
> > 
> > There is no need for this: Classes and exception handling always need mode 
> > objfpc 
> > or Delphi. Regular functions do not need a mode at all. 
> > 
> > This is a simple rule, which can easily be remembered, no ?
> 
> Well, out of curiousity, I tried searching for the word "exceptions" 
> in the Programmer's Guide and Reference Guide and look at it with 
> eyes of a newcomer as suggested by Francisco. I don't think that the 
> places I found (including the dedicated chapter for exceptions in the 
> Reference Guide) make this rule very obvious, so there may be some 
> room for improvement, IMHO. Indeed, this rule is clear from the 
> description of the different compiler modes and various methods 
> allowing to change the mode, but the newcomer may not even know / 
> understand that he should be interested in changing the compiler mode 
> (i.e. visit that part of the document). If nothing else, I'd 
> certainly expect to find this information in the Reference Guide in 
> chapters describing the appropriate language elements.

A good point, and I will add some statements to the docs in the 
appropriate chapters/sections !

Michael.
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation and posts suggestions [LONG]

[Jonas Maebe]

On 15 Mar 2009, at 23:20, Francisco Reyes wrote:


Michael Van Canneyt writes:

or Delphi. Regular functions do not need a mode at all. This is a  
simple rule, which can easily be remembered, no ?


If those are the only two cases sure, but if there are other  
instances that may suffer from the same it may be helpful to have  
the mode mentioned on the instances where it matters.


There's at least also "out" parameters, using the "result" keyword and  
default parameters.



Jonas
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Documentation and posts suggestions [LONG]

[Francisco Reyes]

Tomas Hajny writes:

I'm not sure if Francisco meant the Reference Guide or possibly some 
examples appearing in the other documents;


I was looking specifically about the rtl pdf.



if it's the latter, a more concrete example would be probably useful.


Where are the examples? I recall seem them in the past, but can't find them 
now.


Also as I become more serious about FPC what would be the recommended order 
of reading the docs?


I have:
prog.pdf  
ref.pdf  
rtl.pdf  
user.pdf

Want to go over them in the coming week. I like to read as much as I can 
before jumping into more serious development. Right now doing a couple of 
simple utilities partly because I need them for work and partly to re-learn 
pascal. 



eyes of a newcomer as suggested by Francisco. I don't think that the 
places I found (including the dedicated chapter for exceptions in the 
Reference Guide) make this rule very obvious, so there may be some 
room for improvement


Just looked at that part in the reference and agree that it could at least 
mention it needs delphi or objectpascal modes.


allowing to change the mode, but the newcomer may not even know / 
understand that he should be interested in changing the compiler mode 


Exactly. Specially newcomers may have a good chance to not know what 
documents and in what order they need to read them.
I think it may be a bit easier for someone coming from Delphi, but someone 
just starting out, may not even know that exception handling is object 
pascal and not part of the standard pascal.



___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-pascal