Recent

Author Topic: fpGUI documentation  (Read 7852 times)

JD

  • Hero Member
  • *****
  • Posts: 1758
fpGUI documentation
« on: November 19, 2015, 12:02:24 pm »
Hi there everyone,

I was just taking a look at fpGUI & I'm interested in knowing how its documentation was generated.

Thanks,

JD

PS: I guess Graeme ought to know anyway.
Windows (10, 7) - Lazarus 2.0RC3/FPC 3.2, NewPascal, Delphi

Indy 10.6 series; mORMot; Zeos 7.2.1; SQLite, Firebird, PostgreSQL & MariaDB; VirtualTreeView 5.5.3 R1

Graeme

  • Hero Member
  • *****
  • Posts: 1430
    • Graeme on the web
Re: fpGUI documentation
« Reply #1 on: November 20, 2015, 02:37:55 pm »
I use FPC's fpdoc. I created a fpdoc project file so I can generate multiple output formats with ease. For the HTML output, I created my own fpdoc.css file, thus the Class documentation looks quite different to the standard HTML output fpdoc generates. I also generate IPF output, which I then compile into binary INF files viewable with DocView.

Does this answer your question?
--
fpGUI Toolkit - a cross-platform GUI toolkit using Free Pascal
http://fpgui.sourceforge.net/

JD

  • Hero Member
  • *****
  • Posts: 1758
Re: fpGUI documentation
« Reply #2 on: November 21, 2015, 09:56:24 am »
I use FPC's fpdoc. I created a fpdoc project file so I can generate multiple output formats with ease. For the HTML output, I created my own fpdoc.css file, thus the Class documentation looks quite different to the standard HTML output fpdoc generates. I also generate IPF output, which I then compile into binary INF files viewable with DocView.

Does this answer your question?

It does answer my question but I still don't know how to do it like you did? Would you mind showing me an example?

Thanks

JD
Windows (10, 7) - Lazarus 2.0RC3/FPC 3.2, NewPascal, Delphi

Indy 10.6 series; mORMot; Zeos 7.2.1; SQLite, Firebird, PostgreSQL & MariaDB; VirtualTreeView 5.5.3 R1

Graeme

  • Hero Member
  • *****
  • Posts: 1430
    • Graeme on the web
Re: fpGUI documentation
« Reply #3 on: November 22, 2015, 09:10:42 pm »
Which documentation are you referring too? HTML, INF or other?

Do you want to know how I generate the documentation, or how I formatted or wrote it, or how I integrate it into an application (application help)?
--
fpGUI Toolkit - a cross-platform GUI toolkit using Free Pascal
http://fpgui.sourceforge.net/

JD

  • Hero Member
  • *****
  • Posts: 1758
Re: fpGUI documentation
« Reply #4 on: November 24, 2015, 10:41:30 pm »
Which documentation are you referring too? HTML, INF or other?

Do you want to know how I generate the documentation, or how I formatted or wrote it, or how I integrate it into an application (application help)?

All of the above. You see I normally create CHM help files (a little outmoded nowadays) but I'm now looking at HTML as an alternative. That's why what you did interests me.

JD
« Last Edit: November 25, 2015, 06:55:38 am by JD »
Windows (10, 7) - Lazarus 2.0RC3/FPC 3.2, NewPascal, Delphi

Indy 10.6 series; mORMot; Zeos 7.2.1; SQLite, Firebird, PostgreSQL & MariaDB; VirtualTreeView 5.5.3 R1

Graeme

  • Hero Member
  • *****
  • Posts: 1430
    • Graeme on the web
Re: fpGUI documentation
« Reply #5 on: November 25, 2015, 10:47:10 am »
All of the above. You see I normally create CHM help files (a little outmoded nowadays)
CHM is still a lot better than the latest offerings from Microsoft.

Quote
...but I'm now looking at HTML as an alternative. That's why what you did interests me.
I find HTML help the worst kind. You normally have to launch a web browser to view it - web browsers are slow to start up and very memory hungry. HTML doesn't have built-in search, Index, Table of Content, user annotation support, and takes up a massive amount of hard drive space (compared to INF and even CHM).

Either way, you are not very specific with what type of help you want to generate... Application help or Class documentation, so I'll cover both.

Object Pascal Class documentation can be generate using the Free Pascal supplied tool called fpdoc. Download the fpdoc manual to find out more and how it works.  ftp://ftp.freepascal.org/pub/fpc/docs-pdf/fpdoc.pdf
The actual documentation is written in XML files. The fpdoc  program then pairs up the XML file with the related *.pas files and then generates the documentation output.

Instead of passing a massive amount of command line parameters to fpdoc, I use a fpdoc project file instead. This is much easier to maintain, and I can easily switch between output formats (INF, CHM, HTML, TXT etc). See the following link to fpGUI's fpdoc project file to give you a working example.  https://github.com/graemeg/fpGUI/blob/develop/docs/fpgui-docs-project.xml

Application Help is what end-users see when they run your application and they press F1 or click the Help button inside the application. To create such CHM help most people use commercial software that helps them write the documentation.

I use INF help files instead. My application help is normally in a single INF file which is very small and compact. INF help files are viewable with DocView. You start by writing marked-up plain text IPF files, which you then compile to highly optimised INF help files using the WIPFC compiler - a stand alone console tool included in the fpGUI code repository ("tools" directory).

DocView is better than any CHM viewer I have come across. It is much faster at starting up and loading INF files (near instant). You can load multiple INF files at the same time too (runtime concatenation of INF files), supports in-line annotations (user comments embedded in the help content), advanced searching with a rating system, runtime building of a Index, font and colour customization etc. DocView is also fully cross-platform, tested under Windows (win2k-win10), Linux, FreeBSD, Solaris and OSX.

Authoring INF help for your own applications (not class documentation):
I use the text editor called EditPad Pro. It has brilliant code template support, live file navigation and customisable syntax highlighter. A IPF syntax highlighter and navigation scheme is freely available on the EditPad Pro website. But any text editor (even Lazarus IDE) can be used to author INF help. The IPF syntax is easy and the tags are mnemonic based, so very easy to learn an associated with their function - it is also much less verbose than HTML or XML.

INF was originally developed by IBM, but is still an excellent (and relevant) choice today. Especially with the much more feature complete DocView INF viewer (compared to IBM's original VIEW application).

Even though Docview was initially written for fpGUI based projects, it works equally well as an eBook type application or integration with LCL based applications. Here is a link to a forum attachment of a fully working LCL application with DocView+INF incorporated. For the full discussion, see the Lazarus Forum post.

  http://forum.lazarus.freepascal.org/index.php/topic,27864.msg173887.html#msg173887

Docview screenshots:
  http://fpgui.sourceforge.net/screenshots_apps.shtml

Docview pre-compiled binaries:
  http://sourceforge.net/projects/fpgui/files/fpGUI/1.4/

INF help files for RTL, FCL, LCL and fpGUI
Pre-built INF files are available for download from the above SourceForge link too. They are also a fraction of the size of HTML or even CHM - yet contain the exact same help content.
« Last Edit: December 07, 2015, 12:07:59 pm by Graeme »
--
fpGUI Toolkit - a cross-platform GUI toolkit using Free Pascal
http://fpgui.sourceforge.net/

JD

  • Hero Member
  • *****
  • Posts: 1758
Re: fpGUI documentation
« Reply #6 on: December 07, 2015, 11:49:36 am »
Sorry for the late reply Graeme. Duty called elsewhere. Thanks a lot for your detailed reply. I actually want to create class & application documentation.

I'll try my hands at what you suggested & I'll get back to you as soon as I can.

JD
Windows (10, 7) - Lazarus 2.0RC3/FPC 3.2, NewPascal, Delphi

Indy 10.6 series; mORMot; Zeos 7.2.1; SQLite, Firebird, PostgreSQL & MariaDB; VirtualTreeView 5.5.3 R1

Thaddy

  • Hero Member
  • *****
  • Posts: 8927
Re: fpGUI documentation
« Reply #7 on: December 07, 2015, 01:31:56 pm »
There is one BIG disadvantage of using .inf files under windows: It gets opened by default as a MS system information file. This has been the case since, well, ever and always. It isn't a well chosen file extension for the windows platform.
Most people that want to use threading should learn to patch their jeans first: use a needle.

Graeme

  • Hero Member
  • *****
  • Posts: 1430
    • Graeme on the web
Re: fpGUI documentation
« Reply #8 on: December 07, 2015, 01:38:00 pm »
Yes, unfortunately MS Windows is the only braindead platform that doesn't actually look at the first few bytes of a file to determine the real mime type of the file. Windows only relies on file extensions. In the Windows world, there are many such file extension conflicts - this is nothing new.

If you use INF help from within your application (eg: via pressing F1), this has never been a problem.

If you use INF help often (via double clicking the INF files), you can always change the file association to point to DocView instead. This is a 2 second fix.
--
fpGUI Toolkit - a cross-platform GUI toolkit using Free Pascal
http://fpgui.sourceforge.net/

Thaddy

  • Hero Member
  • *****
  • Posts: 8927
Re: fpGUI documentation
« Reply #9 on: December 07, 2015, 01:49:35 pm »
I agree about braindead, but they were first so they have a certain prodigy.
But changing the default application to open inf files is of course not a fix.

I also agree that within an application there isn't a problem.

The problem is that there at least three and probably more .inf extensions with different meanings.
This may confuse end-users.
Most people that want to use threading should learn to patch their jeans first: use a needle.

Graeme

  • Hero Member
  • *****
  • Posts: 1430
    • Graeme on the web
Re: fpGUI documentation
« Reply #10 on: December 07, 2015, 02:00:53 pm »
Quote
But changing the default application to open inf files is of course not a fix.
Why not? If you use INF help more (by double clicking), then associating DocView with that file extension (your most used functionality) makes sense.

Note that the right click popup menu will still contain the "Open with..." and all previous programs associated with INF file extensions. At least that is how it works here on my Win2K and Win7 VM's.

Then again, using 3 character extensions is such old-school DOS thinking - hence Maximus IDE (demo app included with fpGUI) uses *.project for project files, instead of *.lpr or *.prj - so maybe I should make the extension *.help or *.infhelp - in addition to .inf.  ;-)
« Last Edit: January 13, 2016, 12:58:05 pm by Graeme »
--
fpGUI Toolkit - a cross-platform GUI toolkit using Free Pascal
http://fpgui.sourceforge.net/