[fpc-pascal] State of FPC docs.rant

[Graeme Geldenhuys]

On 27 April 2010 00:51, David Emerson wrote:
>
> I'm far more comfortable using git than svn

Me too, and it didn't take long either.


> Graeme, I have to ask... on the one hand, you noted that having fragmented
> documentations over various locations is unhelpful; and on the other hand, I've
> heard you talk quite a bit about your DocView / INF project; I note in
> particular that you mentioned rewriting the FPC language reference in IPF. How
> is this not an example of the fragmentation you refer to?

OK, maybe you guys don't fully understand what I am doing. I'm not
creating a new documentation system or documentation format. I'm only
creating a more useful cross-platform documentation viewer, and a help
file format that is optimised for size and search speed.

I am still using fpdoc like everybody else, but instead of generating
PDF or HTML or CHM output, I improved the very outdated IPF output
writer of fpdoc. As I mentioned, IPF is the documentation source code
used to generate binary INF help files.

As for the FPC Language Reference. The original document is written
using LaTeX (not fpdoc's XML). LaTeX can be quite complex to parse,
and that was the case with the FPC documentation, so the INF output it
generated was not idea. So I decided to "proof read" the FPC Language
Ref doc (something I wanted to do for years), and then at the same
time, manually translate it to IPF. By that I mean, I did not change
the documentation as such, or add new sections etc. I simply
reformatted the text to fit the INF document and viewer better.
Improving things like cross-linking between various sections and a
better Table Of Content and Index.

All my changes to fpdoc will be submitted as a patch when I am done. I
have already submitted many Lang Ref fixes for the LaTeX version. And
once done, I am submitting the IPF version to the repository as well,
but I'll keep in in sync with the original ref.tex file.

So no, the documentation is not fragmented etc. I hope to keep
everything in the same fpc docs repository, and I hope that the INF
versions of RTL, FCL and Lang Ref can become official documentation as
well (in combination with the existing PDF versions).


> wonder how well it will integrate with the present doc system and if it might
> lower the barrier to entry for contributing to the documentation.

DocView is simply a INF help file viewer. It is not a fpdoc XML editor
like the integrated FPDoc Editor included with Lazarus IDE. What
DocView does allow, is much easier integration with existing IDEs (no
need to install packages and recompile IDE's), offline help, very fast
search, search across all help files at once, bookmarks and
annotations, and small to distribute (1.3MB executable with no
external dependencies). All of this is lacking in the PDF docs and the
Lazarus lhelp viewer.


-- 
Regards,
  - Graeme -


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