[Lazarus] fpdoc + XML description file + indentation whitespace

[Mattias Gaertner]

On Wed, 8 Feb 2012 23:03:26 +0200
Graeme Geldenhuys <graemeg.lists at gmail.com> wrote:

> 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).

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

 
> 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 needed at all.

No. XML is a markup language for texts. You are free to apply
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.


 
> ---------- Forwarded message ----------
> From: Graeme Geldenhuys <graemeg.lists at ......m>
> Date: 6 August 2010 11:01
> Subject: fpdoc + XML description file + indentation whitespace
> To: FPC developers' list <fpc-devel at lists.freepascal.org>
> 
> 
> Hi,
> 
> What is supposed to happen with whitespace in the XML Description files.
> For example. Say you edit an XML file with your favourite text editor, and
> you have a long description. So you add newlines (by pressing ENTER), then
> indent the text to the DESCR node for easier human reading. It seems fpdoc
> inserts that indented (spacing) whitespace as actual space characters (part
> of the help content) in the help content. This is seen all over the place,
> but not always noticed in the final output.
> 
> Examples:
> 
> LaTeX:
> automatically ignores whitespace and will place words next to each other
> with a single space. So this issue is never noticed.
> 
> HTML:
> The web browser will ignore whitespace unless that whitespaces was inside a
> PRE tag in the XML Description file. See example URL below.
> 
> IPF:
> IPF -> INF keeps all whitespace exactly as you typed it inside the XML
> Description files. So if you do indented text, you are going to have huge
> sections of spaces between some words.
> 
> TXT and MAN
> Both have misaligned text due to this problem as well.
> 
> RTF
> ?? I have not tested this output format.
> 
> 
> Here is an example of indentation inside a PRE tag in the XML Description
> file causing misaligned output when viewed with the web browser. See the
> Description section.
> 
> http://lazarus-ccr.sourceforge.net/docs/lcl/comctrls/ttreenode.moveto.html

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.

 
> With INF, TXT (slightly better due to manual line wrapping implementation)
> and MAN the problem is much worse because they treat the content exactly as
> the user entered it. So indentation, to make human readable XML, is not
> recommended. Is there some way fpdoc could help alleviate the problem, or
> is it the job of the output writer to trim such spaces (though this will be
> very hard to catch all cases because you will never know exactly when you
> should or shouldn't trim spaces).


Mattias