GNOME Bugzilla – Bug 513285
Do not use entities in documentation
Last modified: 2013-09-13 00:59:17 UTC
The entities used in the documentation are unneedede and make xml2po eat > 1 GB or memory, which makes the build fail for a lot of people. I'll attach a patch with updated documentation without entities. Quoting some comments from bug #437579: Comment #20 from Claude Paroz (developer, points: 16) 2007-12-25 21:19 UTC [reply] Sorry Matthew, but the patch you committed on the doc (rev. 34695) makes xml2po now crash on my system when I try to update. trunk/help/fr$ xml2po -e -u fr.po ../C/evolution.xml. Comment #23 from Matthew Barnes (Evolution developer, points: 19) 2008-01-09 13:09 UTC [reply] It doesn't necessarily make xml2po crash, but it does seem to make it consume nearly a gig of RAM while processing. If your system doesn't have that much RAM then xml2po will abort. I don't know why my solution causes such extreme memory consumption. Shaun McCance has a alternate solution to the "entity not defined" errors in [1]. I'll try to put a patch together based on his recommendations. [1] http://bugzilla.gnome.org/show_bug.cgi?id=373421#c19
Created attachment 104072 [details] [review] Remove entities from documentation This removes all entities from the documentation, replacing them with the correct UTF-8 characters.
This patch makes the documentation build again for me, except for some warnings in the Spanish translation: es/evolution.xml:71: parser error : Entity 'trade' not defined <para>Esta guía describe cómo usar y gestionar el cliente de Evolution™ ...but those are trivial to fix.
Created attachment 104073 [details] full evolution.xml file FYI, here's the full XML file with the patch applied.
srini, can we please directly get this patch approved and committed? compiling evo is really painful currently...
I would prefer to use DocBook tags like <trademark> and <quote> instead of embedding UTF-8 characters directly. See the patch in [1]. [1] http://bugzilla.gnome.org/show_bug.cgi?id=437579#c25
Matt, feel free to set the patch to needs-work. I'm fine to commit this. Just make sure that Matt's point is taken. We shouldn't be having any more work flow issues of overwriting from here on.
I'd strongly prefer to get this patch in ASAP to fix the most urgent issues. The <trademark> stuff wasn't in the original file either, so my patch is obviously a step forward. Should I commit?
Currently, xml2po have some problems with Unicode in source XML [1][2], so I tend to favour Matthew's patch in #437579. [1] http://bugzilla.gnome.org/show_bug.cgi?id=437371 [2] http://bugzilla.gnome.org/show_bug.cgi?id=441073
I don't see any of these errors with my patched evolution.xml, so I'm not sure whether this applies here.
Wouterm I dont this it was some error. But xml2po was taking 2GB of ram at some point with this. Am I right Claude/Matt?
The RAM issue with xml2po was what urged me to replace the entities with real characters. That fixes the xml2po issues for me, and the documentation builds within a few seconds for me, just like it was before. The real <trademark> stuff and such could be done later when the document is thoroughly reviewed. For now, fixing the most urgent problem without changing any semantics looks like the best thing to do, to me at least.
I'm okay with using the Unicode characters as an interim solution as long as it doesn't cause any of the problems Claude mentioned. Ultimately I want to move to proper DocBook tags.
As I said already, the documentation builds fine in a few seconds on my 512 MB RAM machine, without any errors (except for some entities in the Spanish translation, which are not our problem anyway).
Matt, you decide, as I don't have much insights here. I'm fine you.
Alright, then let's go with Wouter's patch as a quick solution for 2.22 and revisit the DocBook tags patch in bug #437579 for 2.23. Approving the patch; make sure you announce the string changes.
But don't forget that each time you decide to change such things as entities, translators have to change tenth of strings without any added value...
Committed this to trunk quickly as this may cause Radhika to rework on her patch for Evolution 2.22 doc.
I took Revision #34957 from trunk
Srini, do you mind if I mark the patch in bug #437579 as "commit after freeze"? Just so we don't forget.
Matt, go ahead. I don't have any issues :)