[fpc-pascal] Makeskel & how to add Firebird connection documentation?

[Graeme Geldenhuys]

On 17 November 2011 11:45,  <michael.vancanneyt at ....> wrote:
>
> I'm not sure why you recommend leaving makeskel ? I use it always for the
> initial file ? Given the proper parameters, it
> creates a very usable initial file ?

Maybe fpdoc has improved in those areas since I found the issues with
makeskel generated xml files.  So this might be a moot point now. From
memory (this was a long time back), makeskel generates many empty tags
for each element. Often documentation wasn't added in each of those
empty nodes, yet the nodes exist in the xml.

Lets take the following example:

      <element name="SomeName">
        <short/>
        <descr>Some cool description</descr>
        <seealso/>
         <example/>
      </element>

Problem #1:
Some tags might get populated with content, and others might be left
empty. fpdoc generate headers for some of those empty tags, even
though they did not contain content.

Just an example (not saying this is how fpdoc works now)

         Synopsis:  some text here
      Declaration:  procedure MyProc(....);
    Parameters:  [blank]
     Visibility: default
 Description: some long description here
   See also:  [blank]
   Example:  [blank]

Like I said, fpdoc might have been fixed now. But I do remember seeing
in some of the fpdoc output writers that titles were generated like
"Example" or "See Also", but then there was no content.


Problem #2:
Makeskel generates XML that are indented for human readability. This
causes problems with some output writers. XML, HTML & LaTeX might
ignore whitespace or CR/LF characters in the final output, but other
output writers like RTF, IPF and TXT don't. Thus your might have
malformed help text.

eg:
      <element name="SomeName">
        <short/>
        <descr>This is some long description.
My second sentence.
        </descr>
        <example>...</example>
      </element>

vs

<element name="SomeName">
<short/>
<descr>This is some long description. My second sentence.</descr>
<example>...</example>
</element>

Some output writers will interpret the first example as some actual
text, then CR/LF, then more text, then  "          " spaces (the
indentation level of the xml nodes).

So instead of ending with something like:

---------------------------------
   Description:
   This is some long description.  My second sentence.

   Example:
       .....
---------------------------------

...you end up with something like ....

---------------------------------
   Description:
   This is some long description.                   <-- unwanted line break
   My second sentence.

   Example:
       .....
---------------------------------

... or sometimes something like....

---------------------------------
   Description:
                                                                   <--
unwanted blank line
   This is some long description.               <-- unwanted line break
   My second sentence.

   Example:
       .....
---------------------------------

depending where the CR or LF characters were placed in the XML.


I have seen problem #2 quite often. Next time I see it again, I'll
file a bug report with a screenshot.  I tried fixing this problem
before by simply using something like Trim(...) inside those specific
output writers, but that caused all kinds of problems.


-- 
Regards,
  - Graeme -


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