Hi

Has anybody been using the RTF output writer of fpdoc? I had a closer look at it last night, and the output (formatting) looks pretty horrible when viewed using OpenOffice 2.4.

Now I know you get tons of version of RTF and it also depends on what RTF viewer you are using (WordPad, OpenOffice, MS Office, Abiword, etc). So I'm not sure if the horrible formatting is caused by OpenOffice - maybe it looks perfect when viewed using MS Office? Could somebody comment on this?

The reason I ask. I think generating RTF docs, opening it with OpenOffice, and then exporting it to PDF is a lot more accessible to users that downloading and installing the 250MB support files for Latex to work. Just a thought.

BTW:
I played around with the RTF output writer last night and modified the code to at least get hyperlinking inside the RTF document to work (using OpenOffice 2.4). Then exported it to a PDF with OpenOffice - the hyperlinking still worked! Cool! :)

Regards,
- Graeme -

In our previous episode, Graeme Geldenhuys said:

The reason I ask. I think generating RTF docs, opening it with OpenOffice, and then exporting it to PDF is a lot more accessible to users that downloading and installing the 250MB support files for Latex to work. Just a thought.

How big was openoffice + java VM again?

This is a known problem :-)

Nono, formatting was the least of our worries. We were glad to get it with improvements are most welcome.

The reason I ask. I think generating RTF docs, opening it with OpenOffice, and then exporting it to PDF is a lot more accessible to users that downloading and installing the 250MB support files for Latex to work. Just a thought.

The plan is to create PDF directly, as soon as I have a suitable PDF rendering engine which can be included in FPC.

Can you share the patches ?

Michael.

Op 2010-08-24 11:16, Marco van de Voort het geskryf:

How big was openoffice + java VM again?

OpenOffice is include with most linux distros and FreeBSD (no extra download required), and "export to PDF" feature doesn't require Java runtime.

Either way, a lot less download and installation effort for most users - compared to getting a working (and unfamiliar to most) LaTeX system.

BTW:
I have nothing against LaTeX, it's a brilliant piece of engineering. I'm just thinking in lines of what most users will have available to them.

Regards,
- Graeme -

Michael Van Canneyt wrote

The plan is to create PDF directly, as soon as I have a suitable PDF rendering engine which can be included in FPC.

Are you writing a PDF generator?

I'm just investigating the possibilities. I will certainly need one in the close future.

I'd prefer to re-use an existing one (if licenses allow), but if that is what it takes, I will start with one myself. It's not that hard, after all.

Why, did you start on one already ?

Michael.

Op 2010-08-24 11:20, Michael Van Canneyt het geskryf:

Nono, formatting was the least of our worries. We were glad to get it with improvements are most welcome.

OK, that's good to know that OpenOffice isn't to blame. I tried OpenOffice 3.2 (at work) today, and formatting looked just as bad as what I saw last night at home. :)

The plan is to create PDF directly, as soon as I have a suitable PDF rendering engine which can be included in FPC.

Good to know. Obviously you wouldn't get the beautiful layout that LaTeX can generate, but I don't think the average read know better. Most read documents published on the web - and typography has taken a serious nose-dive since the web became popular. Quite sad.

Can you share the patches ?

I definitely will. Last night was just me playing around and getting to know RTF tags a bit more. As soon as I have something concrete, I'll submit the patches.

PS:
Resolving links are still very broken in fpdoc. RTF and IPF output (just two output formats that support links) using FPC's RTL & FCL docs or tiOPF & fpGUI class docs show numerous unresolved/broken links. I tried to debug the ResolveLink() method in fpdoc last night, but couldn't find an answer. Some links work, some don't.

Regards,
- Graeme -

Michael Van Canneyt wrote

Why, did you start on one already ?

No, just curiosity and I though about mentioning that if you start one, it would be probably good to make it a generic document manipulation framework, just like we already have:

fcl-image for raster images
fpvectorial for vectorial images
fpspreadsheet for spreadsheets

I suppose that the problem that you need solved would fit into something like a document generation, which would be then possibly a fpdocument framework =)

I see PDF support more as a fcl-image subtype; just an additional canvas, like the PS canvas.

What you mention here is a more high-level layouting engine. But that is what LaTeX or DocBook does; I don't want to repeat that.

I do have the start of a reporting engine; However, I recently had a look at JasperReports, and want to rework what I have to use their XML format as a start.

Michael.

In our previous episode, Graeme Geldenhuys said:

Did you read my msg from a few days back? Unit order matters.

Op 2010-08-24 13:16, Marco van de Voort het geskryf:

Did you read my msg from a few days back? Unit order matters.

Yes, I know about that from years ago, and that still doesn't solve the problem, even in FCL or fpGUI docs. And even if a link points to an element in the same unit.

Here is what I used to compile the IPF output from FCl.

$ make fcl.chk HTMLFMT=ipf FPCSRCDIR=/opt/fpc-2.4.1/src
FPDOC=/opt/fpc-2.5.1/src/utils/fpdoc/fpdoc

Example: Pipes.TInputPipeStream

Here is the actual text from the pipes.xml file.

<seealso>
<link id="#rtl.classes.TStream">TStream</link>
<link id="CreatePipeStreams"/>
<link id="TOutputPipeStream"/>
</seealso>

... and here is the IPF generated text.

:hp2.See Also:ehp2.
:lm margin=3.
.br
:link reftype=hd refid=__/rtl/rtl_classes_tstream.TStream:elink., :link reftype=hd refid=fcl.CreatePipeStreams:elink., :link reftype=hd refid=fcl.TOutputPipeStream:elink.

Note in the attach screenshot (IPF output) that "CreatePipeStreams" and "TOutputPipeStream" are not links. Links in DocView would appear in Blue. Also look at the IPF generate output. It seems to have resolved those links to #fcl directly, instead of #fcl.pipes

What confuses me even more, is that if I generate HTML help of FCL, then the links are correct. So I have no idea why HTML output writer and Linear based output writers resolve links in different ways. Command I used to generate FCL HTML help.

$ make fcl.chk FPCSRCDIR=/opt/fpc-2.4.1/src
FPDOC=/opt/fpc-2.5.1/src/utils/fpdoc/fpdoc

PS:
The reason TStream is not a link in the DocView screenshot, is because it's from another package. IPF doesn't support cross-linked packages yet.

Regards,
- Graeme -

In our previous episode, Graeme Geldenhuys said:

I don't know much about linear. I know nothing about IPF.

What confuses me even more, is that if I generate HTML help of FCL, then the links are correct. So I have no idea why HTML output writer and Linear based output writers resolve links in different ways. Command I used to generate FCL HTML help.

... but I do know that html has own resolving routines. Maybe the design was that each family of outputs (linear vs html/chm) had its own resolving routines, and dwlinear were never updated properly. Do similar links look ok in the latex output? It makes more sense to compare ipf output with that?

Note that html's are not perfect either (e.g. the IInterface case), but I haven't fully looked into that yet. (if it is easily fixable case or not, I know what causes it)

Because links do not exist in linear writers.

Each element results in a HTML page. The name of the HTML page is known. Therefor, when generating a link, it is sufficient to look up the HTML page, and return it's name.

In linear doc, there is no 'page', so it is not possible to look for it.

You are supposed to generate a correct anchor.

Michael.

Op 2010-08-24 16:51, Michael Van Canneyt het geskryf:

> :link reftype=hd refid=fcl.CreatePipeStreams:elink.,

Just to explain IPF links more. The link part is in the refid value string and terminates at the first period (dot). When I receive a link with periods in them, I replace them with underscores. In the above case the refid string value is "fcl", and it should have been "fcl_pipe_createpipestreams"

The documentation section for CreatePipeStreams does indeed have a "anchor" (if you want to call it that). Here is the IPF text for CreatePipeStreams.

------------------------------------------
.* %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% :h4 name=fcl_pipes_createpipestreams. CreatePipeStreams

:p.
:lm margin=1.
:hp2.Synopsis:ehp2.
.br
:lm margin=3.
Create a pair of pipe stream&per.
...
----------------------------------------

In the above text the anchor is the string value of name, in this case "fcl_pipes_createpipestreams". But when the See Also link was resolved in TInputPipeStreams, the link text received from ResolveLink() was only "fcl". The remaining bits are missing?

Because links do not exist in linear writers. You are supposed to generate a correct anchor.

I'm not sure if I understand you correctly, but I think I am already doing what you are saying. See the above explanation. I have an "anchor", and later down the line when a See Also link needs to be created, the only link text I received ResolveLink() was "fcl", and not the full link text, "fcl_pipes_createpipestreams", like the anchor specified.

The procedure I'm talking about is shown below. Aid parameter is not fully resolved, even after I call Engine.ResolveLink().

procedure TIPFNewWriter.DescrBeginLink(const AId: DOMString);
begin
  { Start link to label ID - links are never nested.}
  FLink := Engine.ResolveLink(Module, AId);
  FLink := StringReplace(FLink, ':', '_', [rfReplaceAll]);
  FLink := StringReplace(FLink, '.', '_', [rfReplaceAll]);
  WriteF(':link reftype=hd refid=''%s''.', [flink]);
end;

Regards,
- Graeme -

Op 2010-08-24 16:48, Marco van de Voort het geskryf:

routines, and dwlinear were never updated properly. Do similar links look ok in the latex output? It makes more sense to compare ipf output with that?

I can't generate Latex output, but I can generate RTF output, which is also a linear writer descendant. The links are also broken after a call to ResolveLink(), just like the IPF output. I assume the Latex will be similar.

Regards,
- Graeme -

That happens if it didn't resolve the link.

Well, the thing is that the 2 methods
GetLabel(AElement : TPasElement)
and

  DescrBeginLink(const AId: DOMString);

Should end with the same string (label). Obviously they don't, which is why it goes awry.

One of the problems is that they start out with different information.

GetLabel has the TPasElement - it's all it can rely on, because there may not be a description element.

DescrBeginLink on the other hand starts from a <link> tag's "id" attribute and starts looking for the target XML element tag. NOT for the TPasElement. (again it may not be there, since it can be in another package)

Michael.

OK, based on this, I have a better understanding of how it works and will trying debugging it again.

Another question... I know the units need to be processed by fpdoc in a specific order. Does the documentation inside a XML file need to be in any specific order? Using our "pipes" unit example here, must the documentation for CreatePipeStreams appear before any other element's See Also link tags could link to it?

In our previous episode, Graeme Geldenhuys said:

> in the latex output? It makes more sense to compare ipf output with that? I can't generate Latex output, but I can generate RTF output,

I don't understand? You don't have to have Latex to inspect latex output of fpdoc ?

Marco van de Voort wrote

I don't understand? You don't have to have Latex to inspect latex output of fpdoc ?

I can output latex for fpGUI class docs, but I don't know how to generate latex output for RTL & FCL. Using the make command, it always wants to build the whole thing giving my latex errors. I don't have latex installed.

Here is the command I run in the fpc docs directory.. The resulting fcl.tex file is only 70 lines long.

------------------------------------------
$ make ps FPCSRCDIR=~/programming/fpc-2.4.0/src
FPDOC=~/programming/fpc-2.5.1/bin/fpdoc
cp styles/listings.sty styles/lstdoc.sty styles/lstlang1.sty styles/lstlang2.sty styles/lstlang3.sty styles/lstmisc.sty styles/lstpatch.sty styles/syntax.sty .
make -C /home/graemeg/programming/fpc-2.4.0/src/compiler/utils msg2inc make[1]: Entering directory
`/home/graemeg/programming/fpc-2.4.0/src/compiler/utils' /home/graemeg/programming/fpc-2.5.1/bin/ppc386 -Fu.. -Fu../../rtl/units/i386-linux -FE. -FUunits/i386-linux -di386 msg2inc.pp
Free Pascal Compiler version 2.5.1 [2010/08/23] for i386 Copyright (c) 1993-2010 by Florian Klaempfl
make[1]: Leaving directory
`/home/graemeg/programming/fpc-2.4.0/src/compiler/utils' /home/graemeg/programming/fpc-2.4.0/src/compiler/utils/msg2inc -TE /home/graemeg/programming/fpc-2.4.0/src/compiler/msg/errore.msg messages.inc
Loading messagefile
/home/graemeg/programming/fpc-2.4.0/src/compiler/msg/errore.msg Writing TeXfile messages.inc
echo "% Automatically generated. Do not edit" > comphelp.inc echo -n '\' >> comphelp.inc
echo 'begin{verbatim}' >> comphelp.inc
/home/graemeg/programming/fpc-2.5.1/bin/ppc386 -h >>comphelp.inc echo '\end{verbatim}' >> comphelp.inc
rm user.aux user.idx user.ilg user.ind user.log user.out user.toc user.tmp user.xref user.4ht
rm: cannot remove `user.aux': No such file or directory rm: cannot remove `user.idx': No such file or directory rm: cannot remove `user.ilg': No such file or directory rm: cannot remove `user.ind': No such file or directory rm: cannot remove `user.log': No such file or directory rm: cannot remove `user.out': No such file or directory rm: cannot remove `user.toc': No such file or directory rm: cannot remove `user.tmp': No such file or directory rm: cannot remove `user.xref': No such file or directory rm: cannot remove `user.4ht': No such file or directory make: [user.dvi] Error 1 (ignored)
cp -f preamble.report preamble.inc
latex user
make: latex: Command not found
make: *** [user.dvi] Error 127
------------------------------------

run
make rtl.inc
make fcl.inc

And it will just run the fpdoc command. the rtl.inc and fcl.inc files are the ones you need. the .tex files just include these files.

Michael.

In our previous episode, Graeme Geldenhuys said:

Michael already answered, but I don't have his finesse.

I just run the make command and pipe it to a file, and then copy the "fpdoc" lines into a shellscript. I do this with html too, unless I'm generating definitive chms.

Marco van de Voort wrote

routines, and dwlinear were never updated properly. Do similar links look ok in the latex output? It makes more sense to compare ipf output with that?

I can now confirm that *all* Linear output writers have this bug. Below is the same help text example as the IPF one. Note that the pageref links don't actually point to the correct location, the simply point to the "fcl" package itself. See the pageref details for the CreatePipeStreams and TOutpuPipeStream in the See Also section...

------------------------------------------
% TInputPipeStream
\section{TInputPipeStream}
\label{fcl:pipes:tinputpipestream}
\index{TInputPipeStream}
% Description
\subsection{Description}
\var{TInputPipeStream} is created by the CreatePipeStreams (\pageref{fcl}) call to represent the reading end of a pipe. It is a TStream (\pageref{../rtl/classes/tstream.html}) descendent which does not allow writing, and which mimics the seek operation. \begin{FPCList}
\SeeAlso
TStream (\pageref{../rtl/classes/tstream.html}),
CreatePipeStreams (\pageref{fcl}),
TOutputPipeStream (\pageref{fcl})\end{FPCList}
------------------------------------------

Only good thing so far, is that now I know it's not a IPF specific issue. :-)

I looked at it, and I've seen where the problem is. I'll try and fix it tonight.

Michael.

Michael Van Canneyt wrote

I do have the start of a reporting engine; However, I recently had a look at JasperReports, and want to rework what I have to use their XML format as a start.

I don't really know about JasperReports (I had a quick glance on Wikipedia), but what about using a open standard like XSL-FO ( http://en.wikipedia.org/wiki/XSL_Formatting_Objects )? I'm asking this simply out of curiosity.

Regards,
SVen

I think XSL-FO can be used to describe the result, rather than describe how to get to this result ?

Michael.

In that case I've misread your mail. ^^ I thought you talked about the output end of the reporting instead of the input one.

Regards,
Sven

Nono, jasperreports jrxml describes the input.

Michael.

Yes.

Although it's possible to get a report engine on top of it.

It would require a to use a XSLT to transform a xml data into a XSL-FO.

This would require some work:

- native XSLT processor like http://xmlsoft.org/XSLT/
- native XSL-FO "renderer" like http://xmlgraphics.apache.org/fop/

Anyone?

For more info see:

http://www.w3schools.com/xslfo/xslfo_xslt.asp

For a report generator (in fact xsl-fo designer) see:

https://www.ecrion.com/Products/XFDesigner/Overview.aspx

http://www.antennahouse.com/product/designer/

Luiz

Op 2010-08-25 08:25, Michael Van Canneyt het geskryf:

I looked at it, and I've seen where the problem is. I'll try and fix it tonight.

Please see the patch at:
http://bugs.freepascal.org/view.php?id=17276

Not sure if it's the most efficient, but fixes the problem. I tested with RTL, FCL and fpGUI - looking at all known problem areas in the documentation. All links are now resolved - if there is documentation for them. Tested LaTeX, RTF and IPF output writers.

Regards,
- Graeme -