View Issue Details

IDProjectCategoryView StatusLast Update
0015120LazarusIDEpublic2012-01-18 15:38
ReporterStefan Müller Assigned ToMattias Gaertner  
PrioritynormalSeverityminorReproducibilityalways
Status resolvedResolutionfixed 
Product Version0.9.29 (SVN) 
Summary0015120: FPDoc-Editor: when saving changes, XML validity must be checked, otherwise error in fpdoc
DescriptionCharacters like "<" have to be manually replaced in the XML description files, otherwise causing fpdoc to fail (because they wreck the XML syntax) when converting the documentation to HTML (and likely when converting to something else as well). In addition, these manual changes are overwritten by the FPDoc Editor everytime something else changes in the XML file.
Additional InformationI'm documenting, for example, the overloaded operator "<" using the FPDoc Editor. The editor generates an XML tag, which looks like:

  <element name="operator <(TPoint, TPoint): Boolean">

which is not a valid XML tag because of the extra "<". Because of this fpdoc terminates with an error when trying to convert this XML file into HTML. When I manually replace this tag by

  <element name="operator <(TPoint, TPoint): Boolean">

fpdoc will convert this just as intended. The problem here is that when I change something different in the documentation (causing the FPDoc Editor to rewrite the XML file), my manually inserted "<" is replaced by "<" again. Finally I tried replacing the tag manually by

  <element name="operator <(TPoint, TPoint): Boolean">

After that fpdoc does not recognize this node anymore as the node belonging to the operator "<", therefore leaving the documentaion page blank. Interestingly, this XML tag is not changed the way the one before was when rewriting the XML file.
TagsNo tags attached.
Fixed in Revision28526
LazTarget0.99.0
WidgetsetWin32/Win64
Attached Files

Relationships

related to 0014423 assignedMattias Gaertner Feature request for IDE FPDoc Editor: document overloaded operators 

Activities

Stefan Müller

2009-11-17 12:25

reporter   ~0032202

Last edited: 2009-11-17 12:26

I think this may be related to http://mantis.freepascal.org/view.php?id=14423 , because I can't imagine any characters causing trouble which are allowed to be in identifier names in FPC.

Stefan Müller

2010-07-08 15:39

reporter   ~0039128

I don't think this issue is about "checking XML validity", because an operator named "<" is possible and should therefore be allowed in the description files. If it is properly replaced by the corresponding HTML entity the XML file will automatically be valid.

But, depending on what happens if an XML is recognized as invalid, because you can't just reject the changes, it is maybe alright.

Mattias Gaertner

2010-07-08 16:13

manager   ~0039129

fpdoc uses xml, not html. It can produce html from it.
The xml must be valid enough to edit the file.
I think the fpdoc editor should automatically fix a few common typos like
and convert special characters like &, < and >.
And the editor should be extended to reject changes and show errors, so that the user can fix them.

Graeme Geldenhuys

2010-07-08 16:53

reporter   ~0039132

Last edited: 2010-07-08 16:57

@Stefan
Mattias is 100% correct. The help is in XML format, but fpdoc support various output formats. Most of those output formats have nothing to do with HTML, so adding HTML tags inside documentation descriptions is inherently VERY BAD practice. Ideally fpdoc should have it's own text formatting syntax (eg: wiki-text, creole, basic markup like [b] for bold etc). That syntax should then get translated to the syntax used by the various output target formats.

The integrated Lazarus FPDoc Editor should ideally also have a rich text edit so special marking is automatically managed and output content to what fpdoc and it's XML format understands. Hiding the raw tag complexity from the person writing the documentation.

The following output formats are supported by fpdoc:
 chm - Compressed HTML file output using fpdoc.css stylesheet.
 dxml - fpdoc Delphi XML output.
 htm - HTM (8.3 filenames) output using fpdoc.css stylesheet.
 html - HTML output using fpdoc.css stylesheet.
 ipf - IPF output (newer fpGUI output).
 ipf_old - IPF output (old OS/2 output).
 latex - Latex output using fpc.sty class.
 man - UNIX man page output.
 rtf - RTF output.
 txt - Plain text.
 xml - fpdoc XML output.

Stefan Müller

2010-08-18 15:09

reporter   ~0040265

Yes, you two are totally right. I was just thinking that &, < and > have to be converted to something and shouldn't just be dropped (and this should be handled by fpdoc and not by the user). So replacing them by HTML entities seemed just as a straight forward approach for me. I don't know another way to go, but, as you said, it may be good to do it different than by utilizing HTML specific stuff.

Mattias Gaertner

2010-11-28 13:56

manager   ~0043648

There is now a simple xml validator.
For the documentation of operators see bug 14423.

Stefan Müller

2011-01-04 15:38

reporter   ~0044867

Thank you very much so far. At which point is this xml validator supposed to step in? Do I have to run it manually or configure it somehow?

When I enter documentation information for the above mentioned operator ( < ) using the FPDocEditor the generated XML still contains the "<" inside the attribute which still causes fpdoc to crash when trying to generate HTML.

I noticed that I did not append the error message from fpdoc:

"An unhandled exception occurred at $0046A3FD :
EXMLReadError : In 'file:lazdoc/UHelper.xml' (line 323 pos 31): Character '<' is not allowed in attribute value
  $0046A3FD
  ..."

By now I am thinking that maybe the XML is valid, but fpdoc itself cannot handle the "<" for some obscure reason.

Hans-Peter Diettrich

2011-10-02 23:56

reporter   ~0052393

XML specifies escapes, which should be recognized and handled by fpdoc or by the XML classes:
<
>
&
The XML classes IMO are the best candidates for such handling, then it's not required to update LazDE etc. separately.

Mattias Gaertner

2011-10-03 02:07

manager   ~0052397

Last edited: 2011-10-03 02:15

I tested with current svn version:

operator < (const p1: TPoint; const p2: TPoint): Boolean;

creates the xml element:

 <element name="operator&lt;(TPoint;TPoint):Boolean">
   <short>Operator &lt;</short>
 </element>

What is wrong with that?

Mattias Gaertner

2012-01-18 15:38

manager   ~0055827

It works here.

Issue History

Date Modified Username Field Change
2009-11-17 12:22 Stefan Müller New Issue
2009-11-17 12:22 Stefan Müller Widgetset => Win32/Win64
2009-11-17 12:25 Stefan Müller Note Added: 0032202
2009-11-17 12:26 Stefan Müller Note Edited: 0032202
2009-11-17 18:49 Vincent Snijders Relationship added parent of 0014423
2009-11-17 18:49 Vincent Snijders Relationship replaced related to 0014423
2009-11-17 18:49 Vincent Snijders LazTarget => 1.0
2009-11-17 18:49 Vincent Snijders Assigned To => Mattias Gaertner
2009-11-17 18:49 Vincent Snijders Status new => assigned
2009-11-17 18:49 Vincent Snijders Target Version => 1.0.0
2010-07-02 20:22 Mattias Gaertner LazTarget 1.0 => 0.9.30
2010-07-02 20:22 Mattias Gaertner Description Updated
2010-07-02 20:22 Mattias Gaertner Additional Information Updated
2010-07-08 08:25 Mattias Gaertner Summary FPDoc-Editor: when saving changes, HTML entities are replaced, which can result in error in fpdoc => FPDoc-Editor: when saving changes, XML validity must be checked, otherwise error in fpdoc
2010-07-08 08:25 Mattias Gaertner Additional Information Updated
2010-07-08 15:39 Stefan Müller Note Added: 0039128
2010-07-08 16:13 Mattias Gaertner Note Added: 0039129
2010-07-08 16:53 Graeme Geldenhuys Note Added: 0039132
2010-07-08 16:57 Graeme Geldenhuys Note Edited: 0039132
2010-08-18 15:09 Stefan Müller Note Added: 0040265
2010-11-26 10:32 Vincent Snijders Target Version 1.0.0 => 0.9.30
2010-11-26 10:32 Vincent Snijders Additional Information Updated
2010-11-28 13:56 Mattias Gaertner Fixed in Revision => 28526
2010-11-28 13:56 Mattias Gaertner Note Added: 0043648
2010-11-28 13:56 Mattias Gaertner Status assigned => resolved
2010-11-28 13:56 Mattias Gaertner Resolution open => fixed
2011-01-04 15:38 Stefan Müller Status resolved => assigned
2011-01-04 15:38 Stefan Müller Resolution fixed => reopened
2011-01-04 15:38 Stefan Müller Note Added: 0044867
2011-01-04 16:24 Vincent Snijders LazTarget 0.9.30 => 0.99.0
2011-01-04 16:24 Vincent Snijders Target Version 0.9.30 => 0.99.0
2011-10-02 23:56 Hans-Peter Diettrich Note Added: 0052393
2011-10-03 02:07 Mattias Gaertner Note Added: 0052397
2011-10-03 02:15 Mattias Gaertner Note Edited: 0052397
2011-10-03 11:08 Felipe Monteiro de Carvalho Status assigned => feedback
2012-01-18 15:38 Mattias Gaertner Note Added: 0055827
2012-01-18 15:38 Mattias Gaertner Status feedback => resolved
2012-01-18 15:38 Mattias Gaertner Resolution reopened => fixed