[fpc-devel] fpdoc's RTF output

[Michael Van Canneyt]

On Tue, 24 Aug 2010, Graeme Geldenhuys wrote:

> 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?

That happens if it didn't resolve the link.

>> 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;

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.