Hi Mattias,

Here is the email I spoke of.. Note that the URL example I listed, is still affected by the problem as well. The first line with "naAdd" is correct. All the other "naXXX" line are indented incorrectly due to the indentation inserted by FPDoc Editor (or by a human).

And as I mentioned, with RTF, IPF, TXT, MAN etc output the problem is greatly enhanced, because the end result viewers of these formats do not ignore whitespace.

So bottom line... Indentation in XML is evil. ;-) XML is meant to be processed by a computer program, not by a human, so indentation really shouldn't be Forwarded message ----------

Thanks.
As already mentioned: The xml reader/writer needs to be improved to preserve spacing.

some style for readability, just like many programming languages (including pascal).
According to the XML recommendation: "white space is typically not intended for inclusion in the delivered version of the document". Many xml viewers and editors use auto indentation to increase readability.

XML is "eXtensible" and that's why fpdoc must define what space is treated strict and what not. Many xml formats have special elements for preformatted space e.g. "pre". The XML specs recommends the Attribute xml:space="preserve".

Maybe Michael knows what space should be preserved and what is free to change.

Maybe this is not a good example, because this is already wrong in the fpdoc document:

<pre>naAdd, // add as last sibling of Destination naAddFirst, // add as first sibling of Destination naAddChild, // add as last child of Destination naAddChildFirst, // add as first child of Destination naInsert, // insert in front of Destination naInsertBehind // insert behind Destination
</pre>

Note: fpdoc has correctly converted the element to HTML.

I will fix the comctrls.xml.

Mattias

A simple modification could help:
Let all preformatted text start on a new line, not directly after <pre> or <code>. The document generators can remove that additional line ending, if required.

DoDi

Normally, only <code> and <pre> tags need to preserve space.

For the man and .txt formats, it's the writer that should fix whitespace issues.

Michael.

I think that is wrong! Maybe the help author wanted (or didn't want) a blank line to be the first line. Also doing what you say means that fpdoc must be modified because of FPDoc Editor? So what happens if we use another xml editor - modify fpdoc yet again?

I say abandon indentation of fpdoc XML files completely!

I agree with Graeme, but even more with Mattias' earlier post. As Mattias mentioned, apparently the XML standard says that whitespace can be ignored.

I suggest that we follow Mattias' advice and find a way to preserve whitespace the author wants displayed in the output while being XML compliant.

Example of xml:space="preserve":
http://msdn.microsoft.com/en-us/library/ms256097.aspx

I say abandon indentation of fpdoc XML files completely!

That might be a solution but would not be very robust if some tool/author takes it upon himself (or erroneously introduces) whitespace again.

Also, it would not be clear that the FPDoc formats depends on whitespace for its output, and would thus contravene XML standards, and hinder use of tools that can work with standard XML to import/export FPDoc files.

Regards,
Reinier

Empty lines can be added at will:

<pre> <!-- this line does not generate any text -->

Here is the text.

Here is some indented text.

</pre>

DoDi

Reinier Olislagers hat am 9. Februar 2012 um
12:35 geschrieben:

On 9-2-2012 12:18, Graeme Geldenhuys wrote: [...] > On 9 February 2012 09:23, Hans-Peter Diettrich wrote: >> A simple modification could help: >> Let all preformatted text start on a new line, not directly after

<pre> or

>> <code>. The document generators can remove that additional line

ending, if

See Michael's answer: Only "code" and "pre" should preserve whitespace. Anything more is a nice to have.
This means after a small xml definition you can use any decent xml editor to edit fpdoc files. There are several ways to define this in xml. I have to look it up.

I will improve the fpdoc editor to preserve more white spaces and to add the preserve definition.

And someone has to fix the output formats txt and man.

Mattias
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120209/7f2d9a5b/attachment.html>

Dodi, I expected more from you. :) You just made one big rookie mistake. You "assumed" that _only HTML output_ is going to be generated. It's a big known NO-NO, to add HTML specific tags and content in the fpdoc XML. That line will be printed as-is in Latex, TXT, RTF, IPF, MAN etc output formats.

Read chapter 4 of the FPDoc Users Guide. Don't confuse the similarity of fpdoc tags with those of HTML.

Reinier Olislagers wrote

I agree with Graeme, but even more with Mattias' earlier post. As Mattias mentioned, apparently the XML standard says that whitespace can be ignored.

I don't know the XML standards that well.... Does that whitespace rule apply to the Content / Data between XML tags too, or just the placement of XML tags in the file?

I would image in only applies to the placement of XML tags - not the data. And in this case the data is affected by FPDoc Editor's indentation too.

2012/2/9 Mattias Gaertner :

See Michael's answer: Only "code" and "pre" should preserve whitespace.

OK, now I understand Michael's comment.

And someone has to fix the output formats txt and man.

I'll take a am already in the process of rewriting the RTF and TXT output writers (because in their current state the output they generate is total garbage).

If I trust this article http://www.usingxml.com/Basics/XmlSpace then
according to the specification then the content of this node

<some-tag> bla </some-tag>

should be passed to the application as ' bla '. It's only that XML-parsers sometimes deviate from the specification (like the Microsoft one in it's default setting).

Regards,
Sven

Graeme Geldenhuys hat am 9. Februar 2012 um 13:16 geschrieben:

The white space inside the tags, e.g. <a href=""> is not part of the data and always ignored.
The discussion is only about the space in the data. That means outside the tags.

I would image in only applies to the placement of XML tags - not the data. And in this case the data is affected by FPDoc Editor's indentation too.

Again:
Each format can define it. But it is typical to ignore data that contains only white space. For instance it is typical that the following has the same meaning:

<short><var><var/></short>

<short>
<var>
</var>
</short>

As soon as the data contains one non white space character every character counts. The following is not the same:

<var>
a
</var>

<var>a</var>

Note: HTML treats multiple white space as one. But this is not typical for xml.

Mattias
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120209/451a43af/attachment.html>

That is what I meant when I said "data between tags". So when FPDoc Editor indents and word-wraps a long paragraph, it is actually changing the data - which I believe is wrong. Though word wrapping would probably be ok.

I haven't used FPDoc Editor is ages, so hopefully things have improved since I initially stumbled upon the issue.