Hi,

I read the fpdoc documentation, and think I understand it correctly, but would just like to confirm.

For fpGUI's class documentation, it uses a single 'fpgui' package in the fpdoc command line, covering all the units documented.

When one XML description file references another description file in the same package, do I need to use the link format as
#<package_name>.<unit_name>.<identifier>

or will the following suffice?

<unit_name>.<identifier>

The reason I ask. If I use the latter, then my links are not resolved correctly in the fpdoc output. This is why I believe I need to always add the #<package_name> in front of all links that don't reference a identifier in the same unit. Maybe the fpdoc documentation could be enhanced to state this fact more clearly.

If my assumption is wrong, then I found another bug in fpdoc, or in the linear output writer code.

eg:
docs for 'fpg_base.pas'
TfpgColor

docs for 'fpg_main':
Some help content with a link to TfpgColor. If I write it as <link id='fpg_base.TfpgColor'/> then the output generated by fpdoc tries to find fpg_main.TfpgColor - which results in a broken link. I have to specify the link as
<link id='#fpgui.fpg_base.TfpgColor"/>, then the output generated has a correct link.

Regards,
- Graeme -

In one package, <unit_name>.<identifier> should be enough in the description text.

In 'short' tags, however, something goes wrong when creating TOC pages that use this tag, and the resolving goes wrong; so there #<package_name>.<unit_name>.<identifier>
is needed.

It is a bug, but I haven't gotten around to investigate it seriously. I did some half-hearted attempts, but it obviously wasn't easily fixable.

Michael.

Op 2010-08-10 14:37, Michael Van Canneyt het geskryf:

I can confirm that this bug occurs in the <descr> tag as well, and happens in both the New IPF and LaTeX output writers. So it's not an IPF output writer issue.

------------[ fpg_main.xml ]------------------------------- ...
<element name="fpgColorToRGB">
<short>Convert a color to RGB values of that color</short> <descr><printshort id="fpgColorToRGB"/>. Not all <link id="fpg_base.TfpgColor">TfpgColor</link> values are in RGB format. For example you are "named" colors too. eg: clWindowBackground</descr> </element>
...
--------------------------------------------------

--------------[ fpgui.latex ]----------------------- ...
% fpgColorToRGB
\subsection{fpgColorToRGB}
\label{fpgui:fpgmain:fpgcolortorgb}
\index{fpgColorToRGB}
\begin{FPCList}
\Synopsis
Convert a color to RGB values of that color\Declaration

\begin{verbatim}
function fpgColorToRGB(col: TfpgColor) : TfpgColor \end{verbatim}
\Visibility
default
\Description
Convert a color to RGB values of that color. Not all TfpgColor (\pageref{fpgui:fpgmain}) values are in RGB format. For example you are "named" colors too. eg: clWindowBackground\end{FPCList} % fpgDeleteFirstMessage
...
-------------------------------------------------------

As you can see the \pageref is trying to referencing TfpgColor in fpgui.fpgmain when in fact it is defined in fpg_base.pas

Adding the #fpgui. to the front of the link in the XML file, then it generates the correct \pageref link.

---------------------------------------------------- ....
% fpgColorToRGB
\subsection{fpgColorToRGB}
\label{fpgui:fpgmain:fpgcolortorgb}
\index{fpgColorToRGB}
\begin{FPCList}
\Synopsis
Convert a color to RGB values of that color\Declaration

\begin{verbatim}
function fpgColorToRGB(col: TfpgColor) : TfpgColor \end{verbatim}
\Visibility
default
\Description
Convert a color to RGB values of that color. Not all TfpgColor (\pageref{fpgui:fpgbase:tfpgcolor}) values are in RGB format. For example you are "named" colors too. eg: clWindowBackground\end{FPCList} % fpgDeleteFirstMessage

....
----------------------------------------------------

I'll report this in Mantis.

Regards,
- Graeme -