[Lazarus] FPDoc Editor vs Lazarus Documentation Tool

classic Classic list List threaded Threaded
12 messages Options
Reply | Threaded
Open this post in threaded view
|

[Lazarus] FPDoc Editor vs Lazarus Documentation Tool

silvioprog
Hello,

What is the most recomended tool to make documentation?:

2. http://wiki.lazarus.freepascal.org/Lazarus_Documentation_Editor.

I'm writting a new component and I want to use a "doc creator" tool available in own Lazarus.

Thank you!

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

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] FPDoc Editor vs Lazarus Documentation Tool

Mattias Gaertner
On Fri, 19 Dec 2014 18:58:01 -0300
silvioprog <[hidden email]> wrote:

> Hello,
>
> What is the most recomended tool to make documentation?:
>
> 1. http://wiki.lazarus.freepascal.org/LazDoc;
> 2. http://wiki.lazarus.freepascal.org/Lazarus_Documentation_Editor.
>
> I'm writting a new component and I want to use a "doc creator" tool
> available in own Lazarus.

Both work on fpdoc files.

Mattias

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] FPDoc Editor vs Lazarus Documentation Tool

Graeme Geldenhuys-3
In reply to this post by silvioprog
On 2014-12-19 21:58, silvioprog wrote:
> What is the most recomended tool to make documentation?:

I simply use my favourite text editor (EditPad Pro) and code templates.
I don't use indentation in the XML files because unfortunately that
screws with some fpdoc output formats where spaces are kept in the
documentation. Lazarus's built-in doc editor doesn't allow for this as
far as I know.

You can obviously use Lazarus IDE's editor itself for editing those XML
files too.

EditPad Pro has the advantage that code templates can be better
organised, file navigation structures can be defined for easy
navigation, custom highlighting can be defined (though the default XML
highlighting is just fine), and EditPad Pro can do automatic
spell-checking on the content itself (ignoring XML tags).

jEdit is another very good and free (and cross platform) text editor.

Regards,
  - Graeme -

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

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] FPDoc Editor vs Lazarus Documentation Tool

Mattias Gaertner
On Sat, 20 Dec 2014 11:18:36 +0000
Graeme Geldenhuys <[hidden email]> wrote:

> On 2014-12-19 21:58, silvioprog wrote:
> > What is the most recomended tool to make documentation?:
>
> I simply use my favourite text editor (EditPad Pro) and code templates.
> I don't use indentation in the XML files because unfortunately that
> screws with some fpdoc output formats where spaces are kept in the
> documentation. Lazarus's built-in doc editor doesn't allow for this as
> far as I know.

What does it not allow exactly?

 
Mattias

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] FPDoc Editor vs Lazarus Documentation Tool

Graeme Geldenhuys-3
On 2014-12-20 11:29, Mattias Gaertner wrote:
> What does it not allow exactly?

The built-in editor does very weird indentation, and there is no option
to switch indentation off completely. Here is a quick example I just
created with the built-in editor. Also note that the built-in editor
simply appends to the end of the file. So the <module> description is
somewhere in the middle of the file because I didn't write it first (I
know it doesn't matter to fpdoc, but it does to me).

================================
<?xml version="1.0" encoding="UTF-8"?>
<fpdoc-descriptions>
  <package name="project1">
    <module name="mycomponent">
      <element name="TMyComponent">
        <short>My short description</short>
        <descr><printshort id="TMyComponent"/>. My long description goes
here.</descr>
        <seealso>TObject</seealso>
      </element>
    <descr><p>This unit contains my cool component.</p><p>It is just
what I wanted.</p>
      </descr><element name="TMyComponent.Name"><short>Describes the
name of the object</short>
      </element>
    </module>
  </package>
</fpdoc-descriptions>
=================================

I would have written it manually as follows to make sure fpdoc doesn't
get whitespace errors, plus I have more control over ordering the
documentation (not that it really makes a difference to fpdoc).

==================================
<?xml version="1.0" encoding="UTF-8"?>
<fpdoc-descriptions>
<package name="project1">

<module name="mycomponent">
<descr><p>This unit contains my cool component.</p><p>It is just what I
wanted.</p></descr>

<element name="TMyComponent">
<short>My short description</short>
<descr><printshort id="TMyComponent"/>. My long description goes
here.</descr>
<seealso>TObject</seealso>
</element>

<element name="TMyComponent.Name">
<short>Describes the name of the object</short>
</element>
</module>

</package>
</fpdoc-descriptions>
==================================


Doing it manually with code templates, I'm just as fast as the built-in
editor, so it's note a speed thing. ;-)


Regards,
  - Graeme -

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

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] FPDoc Editor vs Lazarus Documentation Tool

leledumbo
Administrator
In reply to this post by silvioprog
> I'm writting a new component and I want to use a "doc creator" tool available in own Lazarus

My recommendation:
fpdoceditor.png

I don't really care about the generated XML as long as it's compilable. I edit from this editor and it's nice to have IDE integrated one. I can both document and code at the same time without the need to switch app.
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] FPDoc Editor vs Lazarus Documentation Tool

silvioprog
In reply to this post by Graeme Geldenhuys-3
On Sat, Dec 20, 2014 at 8:18 AM, Graeme Geldenhuys <[hidden email]> wrote:
On 2014-12-19 21:58, silvioprog wrote:
> What is the most recomended tool to make documentation?:

I simply use my favourite text editor (EditPad Pro) and code templates.
I don't use indentation in the XML files because unfortunately that
screws with some fpdoc output formats where spaces are kept in the
documentation. Lazarus's built-in doc editor doesn't allow for this as
far as I know.

You can obviously use Lazarus IDE's editor itself for editing those XML
files too.

EditPad Pro has the advantage that code templates can be better
organised, file navigation structures can be defined for easy
navigation, custom highlighting can be defined (though the default XML
highlighting is just fine), and EditPad Pro can do automatic
spell-checking on the content itself (ignoring XML tags).

jEdit is another very good and free (and cross platform) text editor.

I use three editors (Intellij IDEA, Eclipse and Notepad++), but I want to use a tool distributed with Lazarus, because I'll make a screencast of my component installed in Lazarus IDE. :-/

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

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] FPDoc Editor vs Lazarus Documentation Tool

silvioprog
In reply to this post by Graeme Geldenhuys-3
On Sat, Dec 20, 2014 at 9:18 AM, Graeme Geldenhuys <[hidden email]> wrote:
On 2014-12-20 11:29, Mattias Gaertner wrote:
> What does it not allow exactly?

The built-in editor does very weird indentation, and there is no option
to switch indentation off completely. Here is a quick example I just
created with the built-in editor. Also note that the built-in editor
simply appends to the end of the file. So the <module> description is
somewhere in the middle of the file because I didn't write it first (I
know it doesn't matter to fpdoc, but it does to me).

================================
<?xml version="1.0" encoding="UTF-8"?>
<fpdoc-descriptions>
  <package name="project1">
    <module name="mycomponent">
      <element name="TMyComponent">
        <short>My short description</short>
        <descr><printshort id="TMyComponent"/>. My long description goes
here.</descr>
        <seealso>TObject</seealso>
      </element>
    <descr><p>This unit contains my cool component.</p><p>It is just
what I wanted.</p>
      </descr><element name="TMyComponent.Name"><short>Describes the
name of the object</short>
      </element>
    </module>
  </package>
</fpdoc-descriptions>
=================================

I would have written it manually as follows to make sure fpdoc doesn't
get whitespace errors, plus I have more control over ordering the
documentation (not that it really makes a difference to fpdoc).

==================================
<?xml version="1.0" encoding="UTF-8"?>
<fpdoc-descriptions>
<package name="project1">

<module name="mycomponent">
<descr><p>This unit contains my cool component.</p><p>It is just what I
wanted.</p></descr>

<element name="TMyComponent">
<short>My short description</short>
<descr><printshort id="TMyComponent"/>. My long description goes
here.</descr>
<seealso>TObject</seealso>
</element>

<element name="TMyComponent.Name">
<short>Describes the name of the object</short>
</element>
</module>

</package>
</fpdoc-descriptions>
==================================


Doing it manually with code templates, I'm just as fast as the built-in
editor, so it's note a speed thing. ;-)

So why not add this option in the built-in editor? It seems a nice alternative to who want work using only Lazarus IDE. =)

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

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] FPDoc Editor vs Lazarus Documentation Tool

silvioprog
In reply to this post by leledumbo
On Sat, Dec 20, 2014 at 3:25 PM, leledumbo <[hidden email]> wrote:
> I'm writting a new component and I want to use a "doc creator" tool
available in own Lazarus

My recommendation:
fpdoceditor.png
<http://free-pascal-lazarus.989080.n3.nabble.com/file/n4039867/fpdoceditor.png>

I don't really care about the generated XML as long as it's compilable. I
edit from this editor and it's nice to have IDE integrated one. I can both
document and code at the same time without the need to switch app.

Yes, I want it too, and this is a very nice option (I use a similar approach in other IDEs).

The documentation generated by the FPDoc is not responsive (e.g: http://goo.gl/bCJoPM), i.e., it does not open well on a mobile device.

But I believe that the FPC team can accept a patch to apply the Bootstrap (http://getbootstrap.com/) in FPDoc and all generated documentation could have a better appearance and be compatible with any device that can render HTML. =)

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

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] FPDoc Editor vs Lazarus Documentation Tool

Graeme Geldenhuys-3
On 2014-12-20 22:06, silvioprog wrote:
> The documentation generated by the FPDoc is not responsive (e.g:
> http://goo.gl/bCJoPM), i.e., it does not open well on a mobile device.

That's down to your choice of CSS style sheets - not a fault of FPDoc.
Simply specify a different stylesheet and the magic will start
happening. :) If you don't specify your own stylesheet, FPDoc will give
you the generic/default one. You are not forced to use the default
stylesheet.


Regards,
  - Graeme -

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

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] FPDoc Editor vs Lazarus Documentation Tool

silvioprog
On Sat, Dec 20, 2014 at 7:21 PM, Graeme Geldenhuys <[hidden email]> wrote:
On 2014-12-20 22:06, silvioprog wrote:
> The documentation generated by the FPDoc is not responsive (e.g:
> http://goo.gl/bCJoPM), i.e., it does not open well on a mobile device.

That's down to your choice of CSS style sheets - not a fault of FPDoc.
Simply specify a different stylesheet and the magic will start
happening. :) If you don't specify your own stylesheet, FPDoc will give
you the generic/default one. You are not forced to use the default
stylesheet.

Wooow, I'll use that!

Now I want to do the built-in editor work here in my PC ...

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

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] FPDoc Editor vs Lazarus Documentation Tool

Marco van de Voort
In reply to this post by silvioprog
On Sat, Dec 20, 2014 at 07:06:09PM -0300, silvioprog wrote:
> Yes, I want it too, and this is a very nice option (I use a similar
> approach in other IDEs).
>
> The documentation generated by the FPDoc is not responsive (e.g:
> http://goo.gl/bCJoPM), i.e., it does not open well on a mobile device.
 
> But I believe that the FPC team can accept a patch to apply the Bootstrap (
> http://getbootstrap.com/) in FPDoc and all generated documentation could
> have a better appearance and be compatible with any device that can render
> HTML. =)

Probably not. CHM Windows viewer operates in an older IE compat mode, and
not all modern sets are supported. Moreover the Lazarus help viewer would
have to implement those features.

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus