pasdoc-main

[Pasdoc-main] SVN read-only now, moving to GitHub

[Michalis K. <mic...@gm...>]

Hi everyone,

The SVN repository on SourceForge is read-only from now on. The
commits should be pushed now to our GitHub repository on
https://github.com/michaliskambi/pasdoc/ . You can follow the "GIT
way" and just fork PasDoc on GitHub and submit pull requests, or you
can ask me for push access directly to the above repository.

I'm very open to give push access to everyone interested, in
particular to the present PasDoc developers on SourceForge! Just send
me your preferred account/email address on GitHub.

I'm doing this in the hope of getting more exposure, and more
contributors to our PasDoc project. I'm not a GIT fanboy, but the
experience with my projects showed that GitHub (and it's workflow of
"pull requests") really encourages contributions to open-source
projects.

The commits from GitHub are synchronized (one-way) to SVN using my
sync2git fork on https://github.com/michaliskambi/sync2git . I used to
experiment with 2-way synchronization though git-svn, but it was
bothersome, overriding GIT author information and commit hashes. So to
be a 1st class citizen on GitHub, we have to embrace it fully, and
just commit everything through Git and GitHub.

So if you just use our SVN to update (and are not interested in
committing), you can keep using it, things will work Ok. But I
encourage you to clone GIT GitHub repo instead, and push some work:)

Note: PasDoc project admins could overcome this restriction and commit
to SVN anyway --- but please don't do it, as it will probably break
the synchronization. Instead, really, send me your GitHub
username/email, and I'll give you push access on GitHub:) Thanks!

Best regards,
Michalis

Re: [Pasdoc-main] What do you think about a @file option?

[silvioprog <sil...@gm...>]

Sorry for the very late answer! ^^'

Thanks for the tips, I'm going to use it in a new doc that I'm writing.

On Sat, Aug 8, 2015 at 9:46 PM, Michalis Kamburelis <
mic...@gm...> wrote:

> silvioprog wrote:
> > You can use "@file 'your-doc.file.txt'" or "@file", this last option
> > will search the file containing the class and method name like
> > "TMyClass.MyMethod.txt" in current directory or specified via @dir.
> >
> > Is it an good idea or I'm daydreaming? =/
> >
>
> (Sorry for such delay in answering! Busy times....)
>
> Basically, I see that most of your use-cases are covered by the @include
> tag, that allows to include a description from a specified file. See
> http://pasdoc.sipsolutions.net/IncludeTag . This basically does what
> your @file option would do.
>
> And to avoid having to write @include... tag too often, you can use
> --description command-line option, see
> http://pasdoc.sipsolutions.net/ReadDescriptionFromFile . This allows to
> place (multiple) descriptions in an external file, and they will be
> automatically used by PasDoc.
>
> So, some of needs are already implemented:)
>
> What is missing is the automatic guessing of filename to include. That
> is, in your proposal, one can write @file without a parameter, and then
> the name of the file is automatically guessed from the identified name.
> I think that this can be implemented as just an extension of @include
> tag? When the parameters are empty, then guess the file name. The
> contributions are most welcome:)
>
> In your proposal, you also add command-line options and tags to specify
> the directory where to look for files. These seem like good ideas to
> organize descriptions, I only have small notes:
>
> 1. --doc-source-path= should rather be --include-doc-dir= or such? Just
> keep "include" in the name, to make it clear it's used with @include.
>
> 2. For similar reasons, @dir tag should be called @includeDocDir . Keep
> the phrase "include" inside.
>
> 3. The effect of @includeDocDir should only apply to the current unit.
> Otherwise parsing order, command-line order, cache may all cause problems.
>
> Best regards!
> Michalis
>
>
> ------------------------------------------------------------------------------
> _______________________________________________
> Pasdoc-main mailing list
> Pas...@li...
> https://lists.sourceforge.net/lists/listinfo/pasdoc-main
>



-- 
Silvio Clécio

[Pasdoc-main] Default CSS small improvements (use default font), and other

[Michalis K. <mic...@gm...>]

Two small changes:

1. I removed the ugly line "font-size: 12px;" from our CSS. Setting the
font size explicitly, for the whole document, in pixels, is really bad
--- I wanted to remove it since a long time, but didn't have the courage
(your docs will look differently!). But it's about time:)

You can check out e.g. new autodoc to see how it looks:

  http://pasdoc.sourceforge.net/autodoc/html/index.html

Also, other small fixes to CSS and HTML around tipue, also about nicer
CSS and valid HTML. Also also about HTML friendly for mobiles.

Long-term, we should just use Bootstrap, there's even a ticket about it:
https://sourceforge.net/p/pasdoc/feature-requests/50/ . In the meantime,
these little fixes at least fix the most ugly problems.

2. Also, the next binary release will include our tools: Pascal
preprocessor (pascal_pre_proc) and utilities file_to_pascal_string,
file_to_pascal_data. They are generally useful, and it's time to show
them to the world:)

Michalis

[Pasdoc-main] Please help writing wiki page http://pasdoc.sipsolutions.net/PasDocFpDocComparison

[Michalis K. <mic...@gm...>]

Hi,

On the page http://pasdoc.sipsolutions.net/PasDocFpDocComparison I tried
to summarize PasDoc vs FpDoc differences. Since both projects are
open-source documentation generators for modern Object Pascal, the
question about their differences occurs often --- and it's a good
question! So I tried to answer it fairly on the above page.

That said, I'm not an active FpDoc user, nor am I 100% objective:) So
please, please help improve the above wiki page. And we want it to be
fair comparison, so of course if FpDoc is better than PasDoc in some
regards --- do document it. (But also document if you feel that PasDoc
is better at something:)

This is a wiki, so you all should be able to edit it. To avoid anti-spam
captcha you can also register and send me your login, I'll add you to
the "trusted users" list so you will not need to answer the captcha.

Thanks!
Michalis

Re: [Pasdoc-main] PasDoc 0.14.0 released!

[silvioprog <sil...@gm...>]

On Sun, Aug 9, 2015 at 9:46 AM, Michalis Kamburelis <
mic...@gm...> wrote:

> Hi,
>
> I just released version 0.14.0 of PasDoc, incorporating various fixes
> and improvements. Download the latest version from
> https://sourceforge.net/projects/pasdoc/files/ !
>
> ChangeLog:
>
> * Many fixes to parsing "deprecated", "platform", "library" directives.
> * simplexml output fixes (by Denis Grinyuk)
> * The document creation time is not printed in the docs by default. Use
> "--include-creation-time" to show it. --include-creation-time is
> orthogonal to --exclude-generator.
> * The build duration time is not printed in the output by default. Use
> "--verbosity 3" to show it.
> * Brazilian utf8 translation (by Alexsander da Rosa)
> * Upgrade tipue to 3.0.1, update jquery to 2.0.0.
> * Fix Delphi compilation (long generated tipue code) (thanks to Marcos
> Rocha for investigating)
> * Add pasdoc_gui icon (by Karl-Michael Schindler)
> * Copyrights and docs fixes (thanks to Paul Gevers)
> * Various other small fixes and code cleanups.
>
> Have fun!
> Michalis


Congratulations for the good work! =)

-- 
Silvio Clécio

[Pasdoc-main] PasDoc 0.14.0 released!

[Michalis K. <mic...@gm...>]

Hi,

I just released version 0.14.0 of PasDoc, incorporating various fixes
and improvements. Download the latest version from
https://sourceforge.net/projects/pasdoc/files/ !

ChangeLog:

* Many fixes to parsing "deprecated", "platform", "library" directives.
* simplexml output fixes (by Denis Grinyuk)
* The document creation time is not printed in the docs by default. Use
"--include-creation-time" to show it. --include-creation-time is
orthogonal to --exclude-generator.
* The build duration time is not printed in the output by default. Use
"--verbosity 3" to show it.
* Brazilian utf8 translation (by Alexsander da Rosa)
* Upgrade tipue to 3.0.1, update jquery to 2.0.0.
* Fix Delphi compilation (long generated tipue code) (thanks to Marcos
Rocha for investigating)
* Add pasdoc_gui icon (by Karl-Michael Schindler)
* Copyrights and docs fixes (thanks to Paul Gevers)
* Various other small fixes and code cleanups.

Have fun!
Michalis

[Pasdoc-main] PasDoc output reproducible by default

[Michalis K. <mic...@gm...>]

Hi,

The default PasDoc output is now reproducible by default, which means
that executing the same PasDoc version with the same input twice gives
the same output. This is generally a nice idea IMHO, see also Debian
project wiki https://wiki.debian.org/ReproducibleBuilds and related
thread on pkg-pascal-devel
http://lists.alioth.debian.org/pipermail/pkg-pascal-devel/Week-of-Mon-20150511/000473.html
.

In practice, this means that

1. The document creation time is not printed in the docs by default. Use
--include-creation-time to add it back. --include-creation-time is
orthogonal to --exclude-generator.

2. The build duration time is not printed in the output by default. Use
"--verbosity 3" to show it. Or run PasDoc with a timing command, e.g. on
Unix "time pasdoc ...".

Michalis

Re: [Pasdoc-main] What do you think about a @file option?

[Michalis K. <mic...@gm...>]

silvioprog wrote:
> You can use "@file 'your-doc.file.txt'" or "@file", this last option
> will search the file containing the class and method name like
> "TMyClass.MyMethod.txt" in current directory or specified via @dir.
> 
> Is it an good idea or I'm daydreaming? =/
> 

(Sorry for such delay in answering! Busy times....)

Basically, I see that most of your use-cases are covered by the @include
tag, that allows to include a description from a specified file. See
http://pasdoc.sipsolutions.net/IncludeTag . This basically does what
your @file option would do.

And to avoid having to write @include... tag too often, you can use
--description command-line option, see
http://pasdoc.sipsolutions.net/ReadDescriptionFromFile . This allows to
place (multiple) descriptions in an external file, and they will be
automatically used by PasDoc.

So, some of needs are already implemented:)

What is missing is the automatic guessing of filename to include. That
is, in your proposal, one can write @file without a parameter, and then
the name of the file is automatically guessed from the identified name.
I think that this can be implemented as just an extension of @include
tag? When the parameters are empty, then guess the file name. The
contributions are most welcome:)

In your proposal, you also add command-line options and tags to specify
the directory where to look for files. These seem like good ideas to
organize descriptions, I only have small notes:

1. --doc-source-path= should rather be --include-doc-dir= or such? Just
keep "include" in the name, to make it clear it's used with @include.

2. For similar reasons, @dir tag should be called @includeDocDir . Keep
the phrase "include" inside.

3. The effect of @includeDocDir should only apply to the current unit.
Otherwise parsing order, command-line order, cache may all cause problems.

Best regards!
Michalis

[Pasdoc-main] Code repository of Castle Game Engine and PasDoc mirrored on GitHub

[Michalis K. <mic...@gm...>]

Hi,

In short: you can now download Castle Game Engine and PasDoc source code
from GitHub, from

https://github.com/castle-engine/castle-engine
https://github.com/michaliskambi/pasdoc

Some larger games/tools using Castle Game Engine have also their
separate repository, see

https://github.com/castle-engine/view3dscene
https://github.com/castle-engine/darkest-before-dawn
https://github.com/castle-engine/demo-models
and other repositories listed on https://github.com/castle-engine .

Clone us, fork us, submit pull requests, and have fun:)

Longer explanation:

- These repositories mirror (are synchronized on an hourly basis)
appropriate SVN repositories on SourceForge. The synchronization scripts
run on my private server ( http://michalis.ii.uni.wroc.pl/ ) using
sync2git (see my fork of it on https://github.com/michaliskambi/sync2git ).

- Castle Game Engine SVN repository is split into multiple GIT
repositories, because having a large GIT repository is not comfortable
(GIT "sparse checkouts" are not as comfortable as checking our a
subdirectory in SVN). Using "GitHub organization" for this was natural,
to group multiple CGE GIT repositories as one project.

- For now, we treat all these GIT repositories as read-only, and commit
through SVN. But this will change as soon as we see people contributing
through GitHub (pull requests and such)!

  So fork and submit pull requests as you like --- I'm anxious to see
some activity on GitHub related to our engine:)

- One reason for doing this was to not depend so much on SourceForge
(seeing it's recent downtime of ~10 days for SVN).

  Another reason was to just encourage more contributors. Many
developers (including me:) are accustomed to GIT (and GitHub) workflow
and like the ability to fork / submit pull requests. I was working on
the SourceForge<->GIT mirroring even before SF downtime:)

So, let's see how this works:)

Thanks for reading, and have fun!
Regards,
Michalis

[Pasdoc-main] What do you think about a @file option?

[silvioprog <sil...@gm...>]

Hello,

I'm using PasDoc to generate the documentation of my new framework, and I'm
very happy, because PasDoc is a great tool, generating the documentation
from a code that compiles with Free Pascal and Delphi. Nice! =)

However, in some situations, I have a long comment in the source, and it
disrupts the maintenance of the source, e.g:

[code]
{
  Copyright (C) 2015 Brook developers.

  This file is part of "Brook framework".

  See the file LICENSE.txt, included in this distribution,
  for details about the copyright.

  This library is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.


----------------------------------------------------------------------------
}

{ @abstract(Provides root objects for the Brook framework.)
  @author(Silvio Clecio - <sil...@gm...>)
  @author(Luciano Souza - <luc...@gm...>) }

unit Brook.Lang;

{$I Brook.Lang.inc}

interface

uses
{$IFNDEF FPC}
  Windows,
{$ENDIF}
  SysUtils;

type
  { @abstract(The root object of the Brook class hierarchy.) }
  TBrookObject = class(TObject)
  public
    { Creates an instance of its class. }
    constructor Create; virtual;
    { Returns the class's unit name concatenated with the class name.
Example:

      @longCode(#
      begin
        WriteLn(TBrookObject.QualifiedClassName); // displays
Brook.Lang.TBrookObject
        ...
      #)}
    class function QualifiedClassName: string;

...

[/code]

So, what do you think to use something like this:

Content of "Copyright.txt" (in a folder like "../Docs/TXT"):


*Copyright (C) 2015 Brook developers.*

*This file is part of "Brook framework".*

*See the file LICENSE.txt, included in this distribution,*
*for details about the copyright.*

*This library is distributed in the hope that it will be useful,*
*but WITHOUT ANY WARRANTY; without even the implied warranty of*
*MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.*

Content of "Authors.txt":

*@abstract(Provides root objects for the Brook framework.)*
*@author(Silvio Clecio - <sil...@gm... <sil...@gm...>>)*
*@author(Luciano Souza - <luc...@gm... <luc...@gm...>>)*

Content of "TBrookObject.QualifiedClassName.txt":

*Returns the class's unit name concatenated with the class name. Example:*

*  @longCode(#*
*  begin*
*    WriteLn(TBrookObject.QualifiedClassName); // displays
Brook.Lang.TBrookObject*
*    ...*
*  #)*

So, using this files and a @file tag, I could use it as:

{ @file "Copyright.txt" }
{ @file "Authors.txt" }

unit Brook.Lang;

{$I Brook.Lang.inc}

interface

uses
{$IFNDEF FPC}
  Windows,
{$ENDIF}
  SysUtils;

type
  { @abstract(The root object of the Brook class hierarchy.) }
  TBrookObject = class(TObject)
  public
    { @file }
    class function QualifiedClassName: string;

Using this command:

$ pasdoc --doc-source-path=../Doc/TXT/ ...

Or, to use without the extra param above:

    { @file "../Doc/TXT/TBrookObject.QualifiedClassName.txt" }
    class function QualifiedClassName: string;

Or:

{ @dir "/Docs/TXT/" }
{ @file "Copyright.txt" }
{ @file "Authors.txt" }

unit Brook.Lang;

{$I Brook.Lang.inc}

    { @file "TBrookObject.QualifiedClassName.txt" }
    class function QualifiedClassName: string;

Or:

    { @file }
    class function QualifiedClassName: string;

@dir Specify the default directory used by @file tag.
@file Specify a file wich will used as documentation.

You can use "@file 'your-doc.file.txt'" or "@file", this last option will
search the file containing the class and method name like
"TMyClass.MyMethod.txt" in current directory or specified via @dir.

Is it an good idea or I'm daydreaming? =/

Thank you!

-- 
Silvio Clécio
My public projects - github.com/silvioprog

Re: [Pasdoc-main] Inheritance, how to?

[Michalis K. <mic...@gm...>]

silvioprog wrote:
>     The feature from https://sourceforge.net/p/pasdoc/patches/4/ is not
>     implemented. The patch in https://sourceforge.net/p/pasdoc/patches/4/
>     waits for someone to contribute time and actually apply it on top of new
>     pasdoc sources.
> 
> 
> Hm... is this patch compatible with actual PasDoc sources on trunk? This
> is really a great feature because it identifies what's API/interface and
> what's implementation, the guys use it in Java/C#.

The patch should be somewhat, but not 100%, compatible with current
PasDoc sources. So yes, applying it will need some careful work to
restore it's functionality. That's one of the reasons why noone found
the time to do it yet, unfortunately....

> 
>     There is no feature to *automatically inherit* method descriptions now.
>     In case of class descriptions, the ancestor description will be
>     automatically shown in case the descendant class is missing. But in case
>     of methods, no such thing happens automatically. That said, you can use
>     http://pasdoc.sipsolutions.net/InheritedClassnameNameTag like this:
> 
>     TOtherClass = class(TSomeClass)
>     public
>       { See @inherited for description. }
>       procedure SomeMethod; override;
>     end;
> 
>     This will insert an explicit link to ancestor.
> 
> 
> I saw, and it is a very nice feature too. I'll use that. =)

Cool:)

Regards,
Michalis

Re: [Pasdoc-main] Inheritance, how to?

[silvioprog <sil...@gm...>]

On Tue, Jun 9, 2015 at 1:33 AM, Michalis Kamburelis <
mic...@gm...> wrote:

> silvioprog wrote:
> > On Mon, Jun 8, 2015 at 9:31 PM, silvioprog <sil...@gm...
> > <mailto:sil...@gm...>> wrote:
> >
> >     Hello,
> >
> >     I have a structure like this:
> >
> >     { This class provides some features blah blah blah... }
> >     TSomeClass = class abstract(TObject)
> >     public
> >       { This method executes blah blah blah... }
> >       procedure SomeMethod; virtual; abstract;
> >     end;
> >
> >     TOtherClass = class(TSomeClass)
> >     public
> >       { <<< what I put here? >>> }
> >       procedure SomeMethod; override;
> >     end;
> >
> >     I.e, in TOtherClass I need to override the comment "This method
> >     executes blah blah blah..." from the TBaseClass class.
> >
> >     How to do that? Is it possible in current released PasDoc?
> >
> >     Thank you!
> >
> >
> > Oh, I found this link:
> >
> > https://sourceforge.net/p/pasdoc/patches/4/
> >
> > Is this (nice) feature implemented in PasDoc 0.13.0?
> >
> > Thank you!
> >
>
> The feature from https://sourceforge.net/p/pasdoc/patches/4/ is not
> implemented. The patch in https://sourceforge.net/p/pasdoc/patches/4/
> waits for someone to contribute time and actually apply it on top of new
> pasdoc sources.
>

Hm... is this patch compatible with actual PasDoc sources on trunk? This is
really a great feature because it identifies what's API/interface and
what's implementation, the guys use it in Java/C#.


> There is no feature to *automatically inherit* method descriptions now.
> In case of class descriptions, the ancestor description will be
> automatically shown in case the descendant class is missing. But in case
> of methods, no such thing happens automatically. That said, you can use
> http://pasdoc.sipsolutions.net/InheritedClassnameNameTag like this:
>
> TOtherClass = class(TSomeClass)
> public
>   { See @inherited for description. }
>   procedure SomeMethod; override;
> end;
>
> This will insert an explicit link to ancestor.
>

I saw, and it is a very nice feature too. I'll use that. =)


> Other than this, you can just manually copy description from abstract
> SomeMethod to overridden SomeMethod. It's hardly a nice solution, but it
> will work without any problems of course:)
>

Oops, no, because it can duplicates the comments, and I need to unify it in
an one place.

Thank you!

--
Silvio Clécio
My public projects - github.com/silvioprog

Re: [Pasdoc-main] Inheritance, how to?

[Michalis K. <mic...@gm...>]

silvioprog wrote:
> On Mon, Jun 8, 2015 at 9:31 PM, silvioprog <sil...@gm...
> <mailto:sil...@gm...>> wrote:
> 
>     Hello,
> 
>     I have a structure like this:
> 
>     { This class provides some features blah blah blah... }
>     TSomeClass = class abstract(TObject)
>     public
>       { This method executes blah blah blah... }
>       procedure SomeMethod; virtual; abstract;
>     end;
> 
>     TOtherClass = class(TSomeClass)
>     public
>       { <<< what I put here? >>> }
>       procedure SomeMethod; override;
>     end;
> 
>     I.e, in TOtherClass I need to override the comment "This method
>     executes blah blah blah..." from the TBaseClass class.
> 
>     How to do that? Is it possible in current released PasDoc?
> 
>     Thank you!
> 
> 
> Oh, I found this link:
> 
> https://sourceforge.net/p/pasdoc/patches/4/
> 
> Is this (nice) feature implemented in PasDoc 0.13.0?
> 
> Thank you!
> 

The feature from https://sourceforge.net/p/pasdoc/patches/4/ is not
implemented. The patch in https://sourceforge.net/p/pasdoc/patches/4/
waits for someone to contribute time and actually apply it on top of new
pasdoc sources.

There is no feature to *automatically inherit* method descriptions now.
In case of class descriptions, the ancestor description will be
automatically shown in case the descendant class is missing. But in case
of methods, no such thing happens automatically. That said, you can use
http://pasdoc.sipsolutions.net/InheritedClassnameNameTag like this:

TOtherClass = class(TSomeClass)
public
  { See @inherited for description. }
  procedure SomeMethod; override;
end;

This will insert an explicit link to ancestor.

Other than this, you can just manually copy description from abstract
SomeMethod to overridden SomeMethod. It's hardly a nice solution, but it
will work without any problems of course:)

Hope this helps,
Michalis

Re: [Pasdoc-main] Inheritance, how to?

[silvioprog <sil...@gm...>]

On Mon, Jun 8, 2015 at 9:31 PM, silvioprog <sil...@gm...> wrote:

> Hello,
>
> I have a structure like this:
>
> { This class provides some features blah blah blah... }
> TSomeClass = class abstract(TObject)
> public
>   { This method executes blah blah blah... }
>   procedure SomeMethod; virtual; abstract;
> end;
>
> TOtherClass = class(TSomeClass)
> public
>   { <<< what I put here? >>> }
>   procedure SomeMethod; override;
> end;
>
> I.e, in TOtherClass I need to override the comment "This method executes
> blah blah blah..." from the TBaseClass class.
>
> How to do that? Is it possible in current released PasDoc?
>
> Thank you!
>

Oh, I found this link:

https://sourceforge.net/p/pasdoc/patches/4/

Is this (nice) feature implemented in PasDoc 0.13.0?

Thank you!

-- 
Silvio Clécio
My public projects - github.com/silvioprog

[Pasdoc-main] Inheritance, how to?

[silvioprog <sil...@gm...>]

Hello,

I have a structure like this:

{ This class provides some features blah blah blah... }
TSomeClass = class abstract(TObject)
public
  { This method executes blah blah blah... }
  procedure SomeMethod; virtual; abstract;
end;

TOtherClass = class(TSomeClass)
public
  { <<< what I put here? >>> }
  procedure SomeMethod; override;
end;

I.e, in TOtherClass I need to override the comment "This method executes
blah blah blah..." from the TBaseClass class.

How to do that? Is it possible in current released PasDoc?

Thank you!

-- 
Silvio Clécio
My public projects - github.com/silvioprog

[Pasdoc-main] Full support for "deprecated 'followed by a string'"

[Michalis K. <mic...@gm...>]

Hi,

I just committed a small improvement to PasDoc:full parsing and showing of

  deprecated 'followed by a string'

declarations. This is useful to document *why* some identifier is
deprecated, it's understood both by compilers (FPC, Delphi since 2010)
and now by PasDoc too :)

Previously, there was a code to skip it (but only in certain
situations, for procedures/functions --- but not e.g. for classes).
Now it is actually understood by PasDoc (read to
TPasItem.DeprecatedNote), for all cases, and shown in the output
documentation (HTML and LaTeX). It even works for tricky cases like

  procedure MyProc3; deprecated #72#$6 'llo'; // this says 'Hello'

Tests are welcome of course :) My testcase is in SVN in
tests/ok_deprecated_directive_note.pas, see
http://svn.code.sf.net/p/pasdoc/code/trunk/tests/ok_deprecated_directive_note.pas
.

Regards and happy coding in the new year! :)
Michalis

Re: [Pasdoc-main] [pasdoc:feature-requests] #54 Explicit @link doesn't work with urls

[Thomas M. <tw...@du...>]

I agree. Automatically opening links in a new tab or window is
annoying. Every programmer (and PasDoc is used by programmers) should
know how to open link in a new tab/window with his browser.

On 31 October 2013 00:18, Marcos Rocha <mar...@us...> wrote:
> Ok, I simply forgot the Ctrl+Click feature. To be more precise, I use to
> click with the middle mouse button. Anyway, if nobody manifest himself I can
> take this for me.
>
> ________________________________
>
> [feature-requests:#54] Explicit @link doesn't work with urls
>
> Status: open
> Created: Wed Oct 30, 2013 01:29 PM UTC by Marcos Rocha
> Last Updated: Wed Oct 30, 2013 10:46 PM UTC
> Owner: nobody
>
> While making a documentation, I wrote in comment { See
> @link(http://pasdoc.sipsolutions.net/LinkTag this link) for more details }
> and the result in HTML generated document was "See UNKNOWN for more
> details".
>
> I would like to suggest the possibility to make explicit links using @link.
> =)
>
> ________________________________
>
> Sent from sourceforge.net because pas...@li... is
> subscribed to https://sourceforge.net/p/pasdoc/feature-requests/
>
> To unsubscribe from further messages, a project admin can change settings at
> https://sourceforge.net/p/pasdoc/admin/feature-requests/options. Or, if this
> is a mailing list, you can unsubscribe from the mailing list.
>
>
> ------------------------------------------------------------------------------
> Android is increasing in popularity, but the open development platform that
> developers love is also attractive to malware creators. Download this white
> paper to learn more about secure code signing practices that can help keep
> Android apps secure.
> http://pubads.g.doubleclick.net/gampad/clk?id=65839951&iu=/4140/ostg.clktrk
> _______________________________________________
> Pasdoc-main mailing list
> Pas...@li...
> https://lists.sourceforge.net/lists/listinfo/pasdoc-main
>



-- 
Wissen ist das einzige Gut, das sich vermehrt, wenn man es teilt.

Re: [Pasdoc-main] [pasdoc:feature-requests] #35 Load file and generate docs switch

[Michalis K. <mic...@gm...>]

Harald Schmid wrote:
> That would be a fantastic feature.
>

A small reminder: when you want to add a comment to a ticket (like a bug 
or feature request), you should click on the ticket link (like 
http://sourceforge.net/p/pasdoc/feature-requests/35/ ) and add a comment 
there, through your www browser. This way everyone interested in the 
ticket will get your reply (and it will also automatically be posted to 
pasdoc-main mailing list).

Simply replying to the email "[Pasdoc-main] 
[pasdoc:feature-requests]..." or "[Pasdoc-main] [pasdoc:bugs]..." will 
not add your comment to the ticket. (It can't, since it would 
unfortunately open the tickets to spammers.)

Sorry for the complications :)

On an unrelated note, I'm also very happy about the recent interest in 
PasDoc, and looking forward to Marcos patches :)

Regards,
Michalis

Re: [Pasdoc-main] [pasdoc:feature-requests] #46 Parse Comments in Implementation Section

[Harald S. <har...@fi...>]

Should it matter where a developer chooses to place the comments describing
a method? There are four places where a comment describing a function could
be: in the interface section above and below the function, and in the
implementation section above and below the function.

The default behaviour of Pasdoc is to take the comment above the function
in the interface section. In my mind, the comment belongs to a function.
Therefore, it should come after the function declaration. The function
declaration for me is the title of a text or chapter. Comments and source
code are the sentences which follow it. This is not the default way for
Pasdoc. It does allow for a variation. Maybe either way is fine?


2013/10/16 Marcos Rocha <mar...@us...>

> I was talking with a coworker about it and we agreed that developers
> hardly ever stay at interface section. Normally we (developers) stay at
> implementation section, so why leave "trash" at the implementation section
> instead of write them at the interface section?
> Moreover, since of Delphi XE2 you can use DocInsight to see documentation
> about the classes that were written at interface section.
> In other hand, legacy code brings comments before procedures and functions
> inside implementation section, I am moving those comments to interface
> section not just to document with PasDoc, but for cleaning too.
> ------------------------------
>
> * [feature-requests:#46]<http://sourceforge.net/p/pasdoc/feature-requests/46/>Parse Comments in Implementation Section
> *
>
> *Status:* open
> *Created:* Tue Sep 15, 2009 05:17 PM UTC by Larry Hengen
> *Last Updated:* Mon Nov 05, 2012 10:17 AM UTC
> *Owner:* nobody
>
> PasDoc seems to work well, and I have adjusted my JavaDoc comments in
> hcOPF in order to use it, until I discovered that it does not extract
> comments from the implementation section. This makes it unusable as far as
> I am concerned. I have rather large comment blocks at the start of each
> method, and I want them to stay within the method commented so I can move
> the code without losing the comment attached to it. It also makes more
> sense to have the comments as close to the actual code as possible so
> developers can understand the code easier by reading the comments that
> appear on the screen at the same time, and more importantly update the
> comments to ensure they are kept current.
>
> Is this feature likely to be released any time soon, or should I search
> for an alternative?
> ------------------------------
>
> Sent from sourceforge.net because pas...@li... is
> subscribed to https://sourceforge.net/p/pasdoc/feature-requests/
>
> To unsubscribe from further messages, a project admin can change settings
> at https://sourceforge.net/p/pasdoc/admin/feature-requests/options. Or,
> if this is a mailing list, you can unsubscribe from the mailing list.
>
>
> ------------------------------------------------------------------------------
> October Webinars: Code for Performance
> Free Intel webinars can help you accelerate application performance.
> Explore tips for MPI, OpenMP, advanced profiling, and more. Get the most
> from
> the latest Intel processors and coprocessors. See abstracts and register >
> http://pubads.g.doubleclick.net/gampad/clk?id=60135031&iu=/4140/ostg.clktrk
> _______________________________________________
> Pasdoc-main mailing list
> Pas...@li...
> https://lists.sourceforge.net/lists/listinfo/pasdoc-main
>
>

Re: [Pasdoc-main] [pasdoc:feature-requests] #35 Load file and generate docs switch

[Harald S. <har...@fi...>]

That would be a fantastic feature.


2013/10/16 Marcos Rocha <mar...@us...>

> Ok, so I'll work in this feature for now.
> ------------------------------
>
> * [feature-requests:#35]<http://sourceforge.net/p/pasdoc/feature-requests/35/>Load file and generate docs switch
> *
>
> *Status:* open
> *Labels:* GUI interface (pasdoc_gui)
> *Created:* Fri Sep 08, 2006 11:58 AM UTC by kogerbnz
> *Last Updated:* Wed Oct 16, 2013 01:28 AM UTC
> *Owner:* nobody
>
> Could you add a switch to the commandline so it would
> be possible to load a project file and generate the docs.
> I like the gui program, but I can't use it
> automatically from my batch file, which forces me to
> use the commandline tool.
>
> Thanks
> ------------------------------
>
> Sent from sourceforge.net because pas...@li... is
> subscribed to https://sourceforge.net/p/pasdoc/feature-requests/
>
> To unsubscribe from further messages, a project admin can change settings
> at https://sourceforge.net/p/pasdoc/admin/feature-requests/options. Or,
> if this is a mailing list, you can unsubscribe from the mailing list.
>
>
> ------------------------------------------------------------------------------
> October Webinars: Code for Performance
> Free Intel webinars can help you accelerate application performance.
> Explore tips for MPI, OpenMP, advanced profiling, and more. Get the most
> from
> the latest Intel processors and coprocessors. See abstracts and register >
> http://pubads.g.doubleclick.net/gampad/clk?id=60135031&iu=/4140/ostg.clktrk
> _______________________________________________
> Pasdoc-main mailing list
> Pas...@li...
> https://lists.sourceforge.net/lists/listinfo/pasdoc-main
>
>

[Pasdoc-main] Pasdoc Logo

[Harald S. <har...@fi...>]

Hello,

Michael asked about ideas for a logo. Here is mine.

Harry

Re: [Pasdoc-main] [pasdoc:bugs] #82 On compile pasdoc_package.bpl Delphi xe Fatal Error

[Harald S. <har...@fi...>]

That is fantastic!

Harry

On Tue, 2013-10-08 at 17:04 +0000, Marcos Rocha wrote:
> Great news people, I've just done my tests on TipueAddFiles and
> reached the simplest solution which satisfy both FPC and Delphi.
> Otherwise I can't commit the changed unit so follow the steps:
> 
> 1) Generate .inc files from tipue using file_to_pascal_data tool.
> 2) Change the method TipueAddFiles in PasDoc_Tipue.pas as follow.
> 
>     // original code here
>     const
>         TipueSearchCss : {$I tipuesearch.css.inc}; //Modified Line
>         TipueSearchScript : {$I tipuesearch.js.inc}; //Modified Line
>         TipueSearchSetScript : {$I tipuesearch_set.js.inc}; //Modified Line
>         JQueryScript : {$I jquery-1.7.1.min.js.inc}; //Modified Line
>         TipueSearchImage : {$I search.gif.inc};
>     var
>         TipueResultsPage: string;
>     begin
>         CreateDir(OutputPath + 'tipuesearch');
>         DataToFile(OutputPath + 'tipuesearch' + PathDelim + 'tipuesearch.css', TipueSearchCss); //Modified Line
>         DataToFile(OutputPath + 'tipuesearch' + PathDelim + 'tipuesearch.js', TipueSearchScript); //Modified Line
>         DataToFile(OutputPath + 'tipuesearch' + PathDelim + 'tipuesearch_set.js', TipueSearchSetScript); //Modified Line
>         DataToFile(OutputPath + 'tipuesearch' + PathDelim + 'jquery-1.7.1.min.js', JQueryScript);//Modified Line
>     // original code here
> 
> ______________________________________________________________________
> 
> [bugs:#82] On compile pasdoc_package.bpl Delphi xe Fatal Error
> 
> Status: accepted
> Labels: Delphi XE not compile 
> Created: Tue Mar 12, 2013 01:11 PM UTC by Grigoriy Poverenniy
> Last Updated: Tue Sep 24, 2013 04:47 PM UTC
> Owner: Michalis Kamburelis
> 
> Hello!
> 
> On compile pasdoc_package.bpl
> 
> in module PasDoc_Tipue.pas line
> 
> JQueryScript = {$I jquery-1.7.1.min.js.inc};
> use file - jquery-1.7.1.min.js.inc
> 
> this file not compile with error 
> 
> [DCC Fatal Error] jquery-1.7.1.min.js.inc(4): F2069 Line too long
> (more than 1023 characters)
> 
> Sorry for my english...
> 
> 
> ______________________________________________________________________
> 
> Sent from sourceforge.net because pas...@li... is
> subscribed to https://sourceforge.net/p/pasdoc/bugs/
> 
> To unsubscribe from further messages, a project admin can change
> settings at https://sourceforge.net/p/pasdoc/admin/bugs/options. Or,
> if this is a mailing list, you can unsubscribe from the mailing list.
> 
> 
> ------------------------------------------------------------------------------
> October Webinars: Code for Performance
> Free Intel webinars can help you accelerate application performance.
> Explore tips for MPI, OpenMP, advanced profiling, and more. Get the most from 
> the latest Intel processors and coprocessors. See abstracts and register >
> http://pubads.g.doubleclick.net/gampad/clk?id=60134071&iu=/4140/ostg.clktrk
> _______________________________________________ Pasdoc-main mailing list Pas...@li... https://lists.sourceforge.net/lists/listinfo/pasdoc-main

Re: [Pasdoc-main] pasdoc returns an error for my source file. The error msg is not clear to me.

[Harald S. <har...@fi...>]

Hello Michalis,

thanks a lot for your help. The directory was missing.

Regards,
Harald


2013/9/28 Michalis Kamburelis <mic...@gm...>

> Harald Schmid wrote:
> > Hi guys,
> > The error occurs with the compiled binary from the current source, and
> > the 0.13 binaries I got from sourceforge. Would you point me towards the
> > direction where I can find my mistake?
>
> > pasdoc --output doc MyUnit.pas
>
> > Error[1]:   Could not create HTML unit doc file for unit MyUnit.
> > Error[1]:   Could not create output file "automated.gif".
> > Error[1]:   Could not create output file "private.gif".
> > Error[1]:   Could not create output file "protected.gif".
> > Error[1]:   Could not create output file "public.gif".
> > Error[1]:   Could not create output file "published.gif".
> > Fatal Error: Unable to create file "doc/pasdoc.css"
>
> All these errors mean that pasdoc tried to write a file, but received an
> exception. This means that operating system doesn't allow to write such
> file.
>
> Most probable cause is that you did not create directory "doc" (which
> you indicated by --output doc). PasDoc *does not* (at least now) create
> it automatically. Use "mkdir -p doc/" in your scripts to always first
> make sure that doc/ subdirectory exists.
>
> Other possible causes are that you disk is full, or you don't have
> permission to write files inside doc subdirectory.
>
> I documented this on http://pasdoc.sipsolutions.net/OutputOption . I
> also committed a change to code so that CreateStream now shows the
> underlying message (from TFileStream.Create), that *could* describe an
> exact reason why creation failed (unfortunately this depends on RTL, and
> on Linux it just shows "Unable to create file" without any more
> information).
>
> Regards,
> Michalis
>
>
> ------------------------------------------------------------------------------
> October Webinars: Code for Performance
> Free Intel webinars can help you accelerate application performance.
> Explore tips for MPI, OpenMP, advanced profiling, and more. Get the most
> from
> the latest Intel processors and coprocessors. See abstracts and register >
> http://pubads.g.doubleclick.net/gampad/clk?id=60133471&iu=/4140/ostg.clktrk
> _______________________________________________
> Pasdoc-main mailing list
> Pas...@li...
> https://lists.sourceforge.net/lists/listinfo/pasdoc-main
>

[Pasdoc-main] PasDoc icon --- anyone wants to contribute?

[Michalis K. <mic...@gm...>]

Hi,

It was brought to my attention that our PasDoc GUI doesn't have a 
suitable icon :) I just committed to SVN a simple ASCII icon from 
Karl-Michael Schindler (it's in trunk/source/gui/icons). The icon is set 
in Lazarus project, so Lazarus should handle all the gory details of 
correctly using it on all OSes.

Now, does anyone want to take a shot at creating a "real", more 
graphical icon for PasDoc? As I don't really any idea how such icon 
could look like, you'll have a complete artistic freedom :) Googling 
other doc generators, I only found a nice icon for Doxygen (don't open 
this link if you don't want to be biased :) ---
http://roaringapps.com/app:4932 .

Preferably, the icon should be scalable in SVG format. From that, we can 
autogenerate other sizes. The small raster version of the icon could 
also be placed in the default footer in PasDoc HTML output. The license 
of the icon should of course be GNU GPL 2, just like whole PasDoc sources.

Regards,
Michalis

Re: [Pasdoc-main] pasdoc returns an error for my source file. The error msg is not clear to me.

[Michalis K. <mic...@gm...>]

Harald Schmid wrote:
> Hi guys,
> The error occurs with the compiled binary from the current source, and
> the 0.13 binaries I got from sourceforge. Would you point me towards the
> direction where I can find my mistake?

> pasdoc --output doc MyUnit.pas

> Error[1]:   Could not create HTML unit doc file for unit MyUnit.
> Error[1]:   Could not create output file "automated.gif".
> Error[1]:   Could not create output file "private.gif".
> Error[1]:   Could not create output file "protected.gif".
> Error[1]:   Could not create output file "public.gif".
> Error[1]:   Could not create output file "published.gif".
> Fatal Error: Unable to create file "doc/pasdoc.css"

All these errors mean that pasdoc tried to write a file, but received an 
exception. This means that operating system doesn't allow to write such 
file.

Most probable cause is that you did not create directory "doc" (which 
you indicated by --output doc). PasDoc *does not* (at least now) create 
it automatically. Use "mkdir -p doc/" in your scripts to always first 
make sure that doc/ subdirectory exists.

Other possible causes are that you disk is full, or you don't have 
permission to write files inside doc subdirectory.

I documented this on http://pasdoc.sipsolutions.net/OutputOption . I 
also committed a change to code so that CreateStream now shows the 
underlying message (from TFileStream.Create), that *could* describe an 
exact reason why creation failed (unfortunately this depends on RTL, and 
on Linux it just shows "Unable to create file" without any more 
information).

Regards,
Michalis