On 17 November 2011 11:45, <michael.vancanneyt@....> 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 _______________________________________________ fpc-pascal maillist - fpc-pascal@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-pascal