[Lazarus] fpdoc + XML description file + indentation whitespace

[Graeme Geldenhuys]

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



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


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


Regards,
 - Graeme -

----------------------------------------------------



-- 
Regards,
  - Graeme -


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