Re: [fpc-pascal] Brook 1.0 - A new framework for web was born

[Michalis Kamburelis]

michael.vancann...@wisa.be wrote:

On Sun, 16 Dec 2012, Graeme Geldenhuys wrote:


On 15/12/2012 21:22, Sven Barth wrote:


Maybe because the authors prefered inline comments instead of fpdoc's
XML files...


A shame, because the more detailed the documentation, the more it
obfuscates the code.

eg: Documentation Insight, a popular Delphi IDE plugin for documenting
frameworks from inside the IDE's most requested feature... "external
documentation files" because good documentation means lots of text and
examples, thus lots and lots of code obfuscation.


Exactly the reason why fpdoc uses external XML.

A pasdoc-to-fpdoc conversion is on my TODO list. (tracker item 325689871
;))



(We're getting off-topic from Brook, sorry...)

A couple of answers (from the position of both PasDoc user and developer):

1. Although I personally prefer pasdoc, I was also thinking about 
implementing pasdoc output that produces fpdoc-compatible XML. This is 
quite easy to do in pasdoc (e.g. see our existing "simplexml" output), 
so if you want to do it this way, patches are surely welcome :) I wrote 
about it on http://pasdoc.sipsolutions.net/MichalisKamburelis#Fpdoc_output .


2. As for the discussion about whether it's better to have docs inside 
comments or as a separate files:


2.1. For what it's worth, you can place descriptions in separate files 
and still use PasDoc, see 
http://pasdoc.sipsolutions.net/ReadDescriptionFromFile . Whether this 
format is cleaner or not than fpdoc's XML file is up to the debate, 
anyway you *can* use separate files for the documentation. We also have 
features like introduction/conclusion where you write completely 
separate pages using pasdoc markup.


2.2. As for whether it's better to place documentation in comments or in 
separate files, I wrote about this on 
http://pasdoc.sipsolutions.net/MichalisKamburelis#Should_documentation_be_placed_inside_units_interface.2C_or_in_separate_files_.3F 
. And I still believe that generally the answer is "it is a matter of 
taste".


It comes down to the fact that I don't mind having a large unit 
interface with long comments inside. I don't see this as "code 
obfuscation", I see my comments and examples as crucial and useful 
information that I want to keep together with the interface. You no 
longer can easily see the list of all your methods "at a glance", but 
you can see them in the pasdoc output, so no loss.


And the big advantage of keeping documentation inside source code is 
that it makes documentation easier to keep synchronized with code. 
Patches to the source code often naturally contain also changes to the 
related documentation in the interface. This keeps docs very up-to-date 
in my experience, which also means complete. YMMV of course, but I 
definitely know examples of PasDoc-produced documentation where it's 
very complete and useful.


With documentation in a separate file, there is a risk that you will see 
writing documentation as a "separate task", where you need to go edit 
"these other files". In such case, chances of getting contributions that 
update both the source *and* the relevant documentation are much lower, 
at least in my experience.


One practical note is also that "documentation in source code" approach 
is used by many tools in a lot of other languages too: Doxygen, 
OcamlDoc, JavaDoc, PhpDoc... Languages like Python and Lisp even 
recommend to place docs inside special strings in code (not just 
comments). So, somehow this approach can work Ok :)


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

Re: [fpc-pascal] Brook 1.0 - A new framework for web was born

[michael . vancanneyt]

On Sun, 16 Dec 2012, Graeme Geldenhuys wrote:


On 15/12/2012 21:22, Sven Barth wrote:


Maybe because the authors prefered inline comments instead of fpdoc's
XML files...


A shame, because the more detailed the documentation, the more it obfuscates 
the code.


eg: Documentation Insight, a popular Delphi IDE plugin for documenting 
frameworks from inside the IDE's most requested feature... "external 
documentation files" because good documentation means lots of text and 
examples, thus lots and lots of code obfuscation.


Exactly the reason why fpdoc uses external XML.

A pasdoc-to-fpdoc conversion is on my TODO list. (tracker item 325689871 ;))

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

Re: [fpc-pascal] Brook 1.0 - A new framework for web was born

[Graeme Geldenhuys]

On 15/12/2012 21:22, Sven Barth wrote:


Maybe because the authors prefered inline comments instead of fpdoc's
XML files...


A shame, because the more detailed the documentation, the more it 
obfuscates the code.


eg: Documentation Insight, a popular Delphi IDE plugin for documenting 
frameworks from inside the IDE's most requested feature... "external 
documentation files" because good documentation means lots of text and 
examples, thus lots and lots of code obfuscation.


Anyway, it the Brook author's choice.

Regards,
  - Graeme -

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

Re: [fpc-pascal] Brook 1.0 - A new framework for web was born

[silvioprog]

2012/12/16 Sven Barth 

> On 15.12.2012 04:24, silvioprog wrote:
>
>> More than 15,000 lines of source code, more than 90 test cases, more
>> than one year of work. Today, a new framework for web development was
>> born. It's name is Brook and its nice features are available for you.
>> I thank the FPWeb, the Freespider, the Powtils, the ExtPascal, the
>> CustCGI and the EazyCGI developers. I got inspiration in all of them and
>> and still in Rails and Slim Framework.
>>
>
> This sounds interesting. I'll evaluate your framework once I find the time
> to reimplement my website. :)
>
> A small note though:
> Here 
> http://brookframework.org/get-**started.htmlit
>  should read "If you are a Lazarus user" instead of "If you is a Lazarus
> user"
>
> Regards,
> Sven


Thank you very much Sven! I'm sure Brook will reply your expectations. :)

And, your fix was applied:

https://github.com/silvioprog/brook-site/commit/ca7a742cebcb95da99809506fd2a52a5ceb30eb5

-- 
Silvio Clécio
My public projects - github.com/silvioprog
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Brook 1.0 - A new framework for web was born

[Sven Barth]

On 15.12.2012 04:24, silvioprog wrote:

More than 15,000 lines of source code, more than 90 test cases, more
than one year of work. Today, a new framework for web development was
born. It's name is Brook and its nice features are available for you.
I thank the FPWeb, the Freespider, the Powtils, the ExtPascal, the
CustCGI and the EazyCGI developers. I got inspiration in all of them and
and still in Rails and Slim Framework.


This sounds interesting. I'll evaluate your framework once I find the 
time to reimplement my website. :)


A small note though:
Here http://brookframework.org/get-started.html it should read "If you 
are a Lazarus user" instead of "If you is a Lazarus user"


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

Re: [fpc-pascal] Brook 1.0 - A new framework for web was born

[silvioprog]

2012/12/15 Sven Barth 

> On 15.12.2012 18:16, Graeme Geldenhuys wrote:
>
>> On 15/12/12 17:08, Michalis Kamburelis wrote:
>>
>>>
>>> And the improvements will be (I'm counting on it :) contributed back to
>>> PasDoc and available in it's next version,
>>>
>>
>>
>> More worrying is why fpdoc was not used. ;-)
>>
>
> Maybe because the authors prefered inline comments instead of fpdoc's XML
> files...
>
> Regards,
> Sven
>

Exactly, the reason is precisely this. But as FPDoc is a very good project
and I have never used it, in future projects, it can be a very good option.
:)

-- 
Silvio Clécio
My public projects - github.com/silvioprog
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Brook 1.0 - A new framework for web was born

[silvioprog]

2012/12/15 Michalis Kamburelis 

> luciano de souza wrote:
>
>> Yes, there is a very nice tool. Its name is Pasdoc. Take a look here:
>> http://sourceforge.net/**projects/pasdoc/
>> For this project, the author has changed the source code of Pasdoc.
>> Originally, it's compatible only with HTML 4, but the documentation
>> was released in HTML 5.
>>
>>
>>
> And the improvements will be (I'm counting on it :) contributed back to
> PasDoc and available in it's next version, see http://sourceforge.net/p/**
> pasdoc/feature-requests/50/:)
>
> Michalis
>

I'll send the patchs as soon as I get back from vacation.

Thank you guy! :)

-- 
Silvio Clécio
My public projects - github.com/silvioprog
___
fpc-pascal maillist  -  fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-pascal

Re: [fpc-pascal] Brook 1.0 - A new framework for web was born

[Sven Barth]

On 15.12.2012 18:16, Graeme Geldenhuys wrote:

On 15/12/12 17:08, Michalis Kamburelis wrote:


And the improvements will be (I'm counting on it :) contributed back to
PasDoc and available in it's next version,



More worrying is why fpdoc was not used. ;-)


Maybe because the authors prefered inline comments instead of fpdoc's 
XML files...


Regards,
Sven

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

Re: [fpc-pascal] Brook 1.0 - A new framework for web was born

[Graeme Geldenhuys]

On 15/12/12 17:08, Michalis Kamburelis wrote:
> 
> And the improvements will be (I'm counting on it :) contributed back to 
> PasDoc and available in it's next version,


More worrying is why fpdoc was not used. ;-)


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] Brook 1.0 - A new framework for web was born

[Michalis Kamburelis]

luciano de souza wrote:

Yes, there is a very nice tool. Its name is Pasdoc. Take a look here:
http://sourceforge.net/projects/pasdoc/
For this project, the author has changed the source code of Pasdoc.
Originally, it's compatible only with HTML 4, but the documentation
was released in HTML 5.




And the improvements will be (I'm counting on it :) contributed back to 
PasDoc and available in it's next version, see 
http://sourceforge.net/p/pasdoc/feature-requests/50/ :)


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

Re: [fpc-pascal] Brook 1.0 - A new framework for web was born

[Juha Manninen]

On Sat, Dec 15, 2012 at 12:50 PM, luciano de souza  wrote:
> Yes, there is a very nice tool. Its name is Pasdoc. Take a look here:
> http://sourceforge.net/projects/pasdoc/
> For this project, the author has changed the source code of Pasdoc.
> Originally, it's compatible only with HTML 4, but the documentation
> was released in HTML 5.

Cool, I didn't know it can do that.

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

Re: [fpc-pascal] Brook 1.0 - A new framework for web was born

[luciano de souza]

Yes, there is a very nice tool. Its name is Pasdoc. Take a look here:
http://sourceforge.net/projects/pasdoc/
For this project, the author has changed the source code of Pasdoc.
Originally, it's compatible only with HTML 4, but the documentation
was released in HTML 5.


2012/12/15, Juha Manninen :
> May I ask how were the hierarchy and dependency graps generated?
> Is there a tool that can do it?
>
> Juha
> ___
> 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] Brook 1.0 - A new framework for web was born

[Juha Manninen]

May I ask how were the hierarchy and dependency graps generated?
Is there a tool that can do it?

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

Re: [fpc-pascal] Brook 1.0 - A new framework for web was born

[luciano de souza]

It would be very intersting, but in this moment, it would mean a lost
of focus. The  existant web servers are fortunately reliable. So Brook
has prefered to invest in another aspects.
For example, the route handling. With one line, you can register a
pattern to calll your URLs:

action1.register('/person/:id/');

In the above code, you are saying that:
1. The first level of your pathinfo is "/person";
2. The second level of your PathInfo is a variable containing an ID;
3. The final slash indicates that the URL will be a final slash even
if you have forgoten it.

Examples:

http://www.mysite.com/person/25
http://www.mysite.com/person/25/

If only an example of the power of route handling.
I think people will really appreciate the news Brook implements.


2012/12/15, Rainer Stratmann :
> I thought the webserver itself was programmed in FreePascal...
>
> Am Saturday 15 December 2012 09:59:48 schrieb luciano de souza:
>> No, Brook works with any web server. Apache is only the an example and
>> the preference of the author.
>>
>> 2012/12/15, silvioprog :
>> > Hello all,
>> >
>> > More than 15,000 lines of source code, more than 90 test cases, more
>> > than
>> > one year of work. Today, a new framework for web development was born.
>> > It's name is Brook and its nice features are available for you.
>> > I thank the FPWeb, the Freespider, the Powtils, the ExtPascal, the
>> > CustCGI and the EazyCGI developers. I got inspiration in all of them
>> > and
>> > and still in Rails and Slim Framework.
>> >
>> > Special thanks, I drive to João Moraes, who gave me valuable advices to
>> > decoupling the code. Thanks for Luciano de Souza, responsible for the
>> > documentation and the name of methods and properties. Thanks also for
>> > Marcos Douglas, the author of Greyhound, project  wich started as an
>> > inspiration and finished as a valuable partner in the new web ways.
>> >
>> > Finally, I thank for the Free Pascal and Lazarus community for the
>> > precious tips and quick helps.
>> >
>> > I was thinking about what to write in the launching e-mail. But,
>> > there's
>> > no much to say. The site of Brook and its documentation will speak for
>> > me. So I present the Brook's house:
>> >
>> > http://brookframework.org
>> >
>> > Your visit will be appreciated.
>> >
>> > Their, you find the documentation, you find examples running online and
>> > you find also the hopeness this work will be very useful to the Free
>> > Pascal and Lazarus commoties.
>> >
>> > On Sunday, I am going to start my vacations. Thanks God. The work is
>> > ready and the conscious is quiet.
>> >
>> > Enjoy!
>> >
>> > --
>> > Silvio Clécio
>> > My public projects - github.com/silvioprog
>
>
> ___
> 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] Brook 1.0 - A new framework for web was born

[Rainer Stratmann]

I thought the webserver itself was programmed in FreePascal...

Am Saturday 15 December 2012 09:59:48 schrieb luciano de souza:
> No, Brook works with any web server. Apache is only the an example and
> the preference of the author.
>
> 2012/12/15, silvioprog :
> > Hello all,
> >
> > More than 15,000 lines of source code, more than 90 test cases, more than
> > one year of work. Today, a new framework for web development was born.
> > It's name is Brook and its nice features are available for you.
> > I thank the FPWeb, the Freespider, the Powtils, the ExtPascal, the
> > CustCGI and the EazyCGI developers. I got inspiration in all of them and
> > and still in Rails and Slim Framework.
> >
> > Special thanks, I drive to João Moraes, who gave me valuable advices to
> > decoupling the code. Thanks for Luciano de Souza, responsible for the
> > documentation and the name of methods and properties. Thanks also for
> > Marcos Douglas, the author of Greyhound, project  wich started as an
> > inspiration and finished as a valuable partner in the new web ways.
> >
> > Finally, I thank for the Free Pascal and Lazarus community for the
> > precious tips and quick helps.
> >
> > I was thinking about what to write in the launching e-mail. But, there's
> > no much to say. The site of Brook and its documentation will speak for
> > me. So I present the Brook's house:
> >
> > http://brookframework.org
> >
> > Your visit will be appreciated.
> >
> > Their, you find the documentation, you find examples running online and
> > you find also the hopeness this work will be very useful to the Free
> > Pascal and Lazarus commoties.
> >
> > On Sunday, I am going to start my vacations. Thanks God. The work is
> > ready and the conscious is quiet.
> >
> > Enjoy!
> >
> > --
> > Silvio Clécio
> > My public projects - github.com/silvioprog


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

Re: [fpc-pascal] Brook 1.0 - A new framework for web was born

[luciano de souza]

No, Brook works with any web server. Apache is only the an example and
the preference of the author.


2012/12/15, silvioprog :
> Hello all,
>
> More than 15,000 lines of source code, more than 90 test cases, more than
> one year of work. Today, a new framework for web development was born. It's
> name is Brook and its nice features are available for you.
> I thank the FPWeb, the Freespider, the Powtils, the ExtPascal, the CustCGI
> and the EazyCGI developers. I got inspiration in all of them and and still
> in Rails and Slim Framework.
>
> Special thanks, I drive to João Moraes, who gave me valuable advices to
> decoupling the code. Thanks for Luciano de Souza, responsible for the
> documentation and the name of methods and properties. Thanks also for
> Marcos Douglas, the author of Greyhound, project  wich started as an
> inspiration and finished as a valuable partner in the new web ways.
>
> Finally, I thank for the Free Pascal and Lazarus community for the precious
> tips and quick helps.
>
> I was thinking about what to write in the launching e-mail. But, there's no
> much to say. The site of Brook and its documentation will speak for me. So
> I present the Brook's house:
>
> http://brookframework.org
>
> Your visit will be appreciated.
>
> Their, you find the documentation, you find examples running online and you
> find also the hopeness this work will be very useful to the Free Pascal and
> Lazarus commoties.
>
> On Sunday, I am going to start my vacations. Thanks God. The work is ready
> and the conscious is quiet.
>
> Enjoy!
>
> --
> Silvio Clécio
> My public projects - github.com/silvioprog
>


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

Re: [fpc-pascal] Brook 1.0 - A new framework for web was born

[Rainer Stratmann]

Does it only work with Apache?

Am Saturday 15 December 2012 04:24:48 schrieb silvioprog:
> Hello all,
>
> More than 15,000 lines of source code, more than 90 test cases, more than
> one year of work. Today, a new framework for web development was born. It's
> name is Brook and its nice features are available for you.
> I thank the FPWeb, the Freespider, the Powtils, the ExtPascal, the CustCGI
> and the EazyCGI developers. I got inspiration in all of them and and still
> in Rails and Slim Framework.
>
> Special thanks, I drive to João Moraes, who gave me valuable advices to
> decoupling the code. Thanks for Luciano de Souza, responsible for the
> documentation and the name of methods and properties. Thanks also for
> Marcos Douglas, the author of Greyhound, project  wich started as an
> inspiration and finished as a valuable partner in the new web ways.
>
> Finally, I thank for the Free Pascal and Lazarus community for the precious
> tips and quick helps.
>
> I was thinking about what to write in the launching e-mail. But, there's no
> much to say. The site of Brook and its documentation will speak for me. So
> I present the Brook's house:
>
> http://brookframework.org
>
> Your visit will be appreciated.
>
> Their, you find the documentation, you find examples running online and you
> find also the hopeness this work will be very useful to the Free Pascal and
> Lazarus commoties.
>
> On Sunday, I am going to start my vacations. Thanks God. The work is ready
> and the conscious is quiet.
>
> Enjoy!


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