GNOME Bugzilla – Bug 373421
Bug to follow evolution gnome-doc-tool transition
Last modified: 2008-03-14 18:28:25 UTC
Initial transition for Evolution documentation to gnome-doc-tool.
Created attachment 76329 [details] [review] Patch to implement gnome-doc-tools This is an initial patch that makes the needed changes to begin to use gnome-doc-tools.
Srini: poke.
Created attachment 76591 [details] [review] New version which eliminates some errors with docbook
Created attachment 76608 [details] [review] Fixes a building error
Im reviewed your patch wrt http://live.gnome.org/GnomeDocUtilsMigrationHowTo and it looks pretty neat. But When I try to apply and compile, Running automake-1.9... configure.in:67: warning: AC_ARG_PROGRAM invoked multiple times automake-1.9: cannot open < gnome-doc-utils.make: No such file or directory I get this error. Anything wrong in What ive done? [I use gnome-common-2.12.0-14.2]
The instructions at GNOMEDocUtilsMigrations are a bit outdated. We have been discussing about that about a month ago. Do you have gnome-doc-utils installed? I thought that configure.in should warn about it. I also received multiple AC_ARG_PROGRAM warnings, but they where there before the patch. I'm using gnome-common 2.12.0-2 (Debian) and Ubuntu (Edgy) on this machine and gnome-doc-utils.make works perfectly. Have you tries with another gnome-doc-utils enabled source like eog to see if the same problem persists?
Javier, I just checked out EOG and compiled it. It went well. I dont see any error.
Created attachment 76917 [details] [review] Fixes a building error
I hope this last patch will be ok
this patch seems to be OK during autogen and the other issue is fixed. But I got some warning like Warning: image file '../C/figures/evo_mail_a.png' not found. Warning: image file '../C/figures/ver_view_a.png' not found. Warning: image file '../C/figures/collap_head_a.png' not found. Warning: image file '../C/figures/free_busy.png' not found. Warning: image file '../C/figures/exchng-identity.png' not found. Warning: image file '../C/figures/exchng-rec-mails.png' not found. Warning: image file '../C/figures/exchng-rec-options.png' not found. Warning: image file '../C/figures/exchng-settings.png' not found. Warning: image file '../C/figures/delgt-add.png' not found. Warning: image file '../C/figures/sub-others-folder.png' not found. Warning: image file '../C/figures/sub-pub-fold.png' not found. Warning: image file '../C/figures/free_busy.png' not found. Warning: image file '../C/figures/evo_identityedit_a.png' not found. Warning: image file '../C/figures/evo_gwreceiveedit_a.png' not found. Warning: image file '../C/figures/evo_gwreceiveoptedit_a.png' not found. Warning: image file '../C/figures/free_busy.png' not found. Warning: image file '../C/figures/evo_sendstatus_a.png' not found. Warning: image file '../C/figures/evo_proxyadd_a.png' not found. Warning: image file '../C/figures/proxy-login.png' not found. Warning: image file '../C/figures/proxy-cal.png' not found. Warning: image file '../C/figures/mailer_preferences.png' not found. I guess there seems to be some path issues on 'make'.
Nope, this images are not in CVS, but they are referenced in evolution.xml doc. It seems that somebody forgot to do a 'cvs add' on them. Also some of them do not follow documentation guidelines about using Clearlooks theme.
I can see that Javier. Just another observation. In help/ directory if I do make clean make make install It is perfectly OK. If I do make clean make install I get the following error. Im not sure, if this is intended or not. /usr/bin/install -c -m 644 C/evolution.xml /home/sragavan/opt/gnome216/share/gnome/help/evolution/C/evolution.xml /usr/bin/install -c -m 644 ./es/evolution.xml /home/sragavan/opt/gnome216/share/gnome/help/evolution/es/evolution.xml /usr/bin/install: cannot stat `./es/evolution.xml': No such file or directory make[2]: *** [install-doc-docs] Error 1 make[2]: Leaving directory `/home/sragavan/cvs/gnome216/evolution/help' make[1]: *** [install-am] Error 2 make[1]: Leaving directory `/home/sragavan/cvs/gnome216/evolu If it is OK, then please commit the patch. No other issues apart from this. Thanks for your great patch.
That's because I have not added es.po under es directory yet. I will correct this and I will add the missing screenshots. We are going to have a pretty evolution user manual ;-)
I just updated to head and jhbuild build evolution fails with the following error: make[1]: Leaving directory `/home/build-head/cvs/gnome2/evolution/help' if ! test -d es/; then mkdir es/; fi case "." in /*) sd=".";; *) sd="../.";; esac; \ if [ -f "C/evolution.xml" ]; then d="../"; else d="$sd/"; fi; \ (cd es/ && \ `which xml2po` -e -p \ "${d}es/es.po" \ "${d}C/evolution.xml" > evolution.xml.tmp && \ cp evolution.xml.tmp evolution.xml && rm -f evolution.xml.tmp) 'import site' failed; use -v for traceback Traceback (most recent call last):
+ Trace 90518
import libxml2
make: *** [es/evolution.xml] Error 1 build-head@vvaradhan-test:~/cvs/gnome2/evolution/help>
I think you are missing a build dependency on python libxml bindings.
just built gnome-doc-utils and that error is gone but getting the following errors: C/evolution.xml:58: parser error : Entity 'trade' not defined <productname>&appname;™</productname> ^ C/evolution.xml:66: parser error : Entity 'trade' not defined <para>This guide describes how to use and manage Evolution™ &appversion; ^ C/evolution.xml:121: parser error : Entity 'reg' not defined <para>For support, late-breaking news, and errata, visit the Novell® sup ^ C/evolution.xml:131: parser error : Entity 'reg' not defined <para>A trademark symbol (®, ™, etc.) denotes a Novell trademark. An ^ C/evolution.xml:131: parser error : Entity 'trade' not defined <para>A trademark symbol (®, ™, etc.) denotes a Novell trademark. An ^ C/evolution.xml:138: parser error : Entity 'trade' not defined <para>Evolution™ makes the tasks of storing, organizing, and retrieving ^ C/evolution.xml:258: parser error : Entity 'reg' not defined <para> Select this option if you connect to Novell GroupWise®. Novel ^ C/evolution.xml:949: parser error : Entity 'rdquo' not defined <para>evolution ”%s”</para> ^ C/evolution.xml:949: parser error : Entity 'rdquo' not defined <para>evolution ”%s”</para> ^ C/evolution.xml:963: parser error : Entity 'trade' not defined ink>, provide you with an in-depth guide to the capabilities of Evolution™ ^ C/evolution.xml:1031: parser error : Entity 'ldquo' not defined <para>Check “Shrink To/CC/Bcc headers to” column to limit the ^ C/evolution.xml:1031: parser error : Entity 'rdquo' not defined <para>Check “Shrink To/CC/Bcc headers to” column to limit the ^ C/evolution.xml:1037: parser error : Entity 'rsquo' not defined he <inlinegraphic format="PNG" fileref="figures/plus.png"/> icon or the ’ ^ C/evolution.xml:1037: parser error : Entity 'rsquo' not defined egraphic format="PNG" fileref="figures/plus.png"/> icon or the ’...’ ^ C/evolution.xml:1266: parser error : Entity 'ldquo' not defined nations to get the Cyrillic alphabet, combining letters where necessary. “ ^ C/evolution.xml:1266: parser error : Entity 'rdquo' not defined o get the Cyrillic alphabet, combining letters where necessary. “Zh” ^ C/evolution.xml:1266: parser error : Entity 'ldquo' not defined rillic alphabet, combining letters where necessary. “Zh” and “ ^ C/evolution.xml:1266: parser error : Entity 'rdquo' not defined phabet, combining letters where necessary. “Zh” and “ya” ^ C/evolution.xml:1266: parser error : Entity 'lsquo' not defined ; produce the appropriate single Cyrillic letters, and the single-quote (‘ ^ C/evolution.xml:1294: parser error : Entity 'reg' not defined is a tool designed for use with remote mail storage systems like GroupWise® ^ C/evolution.xml:1432: parser error : Entity 'ldquo' not defined called a <link linkend="regular-expression">regular expression</link> or “ ^ C/evolution.xml:1432: parser error : Entity 'rdquo' not defined nk linkend="regular-expression">regular expression</link> or “regex” ^ C/evolution.xml:1662: parser error : Entity 'ldquo' not defined <para>Always begin and close with a salutation. Say “please” a ^ C/evolution.xml:1662: parser error : Entity 'rdquo' not defined <para>Always begin and close with a salutation. Say “please” a ^ C/evolution.xml:1662: parser error : Entity 'ldquo' not defined a>Always begin and close with a salutation. Say “please” and “ ^ C/evolution.xml:1662: parser error : Entity 'rdquo' not defined d close with a salutation. Say “please” and “thank you,” ^ C/evolution.xml:1753: parser error : Entity 'ldquo' not defined , and then tells Evolution to encrypt the message. The message now reads “ ^ C/evolution.xml:1753: parser error : Entity 'rdquo' not defined ncrypt the message. The message now reads “@#$23ui7yr87#@!48970fsd.” ^ C/evolution.xml:1943: parser error : Entity 'trade' not defined receive hundreds, you probably want to sort and organize them. Evolution™ ^ C/evolution.xml:2070: parser error : Entity 'ldquo' not defined t the top, before the message headers. An overdue message might tell you “ ^ C/evolution.xml:2070: parser error : Entity 'rdquo' not defined e message might tell you “Overdue: Call by April 07, 2003, 5:00 PM.” ^ C/evolution.xml:2291: parser error : Entity 'ldquo' not defined cond time. For example, if a message declares the Resent-From: header as “ ^ C/evolution.xml:2291: parser error : Entity 'rdquo' not defined essage declares the Resent-From: header as “engineering@example.com” ^ C/evolution.xml:2291: parser error : Entity 'ldquo' not defined header as “engineering@example.com” and then restates it as “ ^ C/evolution.xml:2291: parser error : Entity 'rdquo' not defined @example.com” and then restates it as “marketing@example.com,” ^ C/evolution.xml:2501: parser error : Entity 'ldquo' not defined m a message about anything other than Evolution, it only shows up in the “ ^ C/evolution.xml:2501: parser error : Entity 'rdquo' not defined about anything other than Evolution, it only shows up in the “Anna” ^ C/evolution.xml:2501: parser error : Entity 'ldquo' not defined out the user interface for Evolution, he can see the message both in the “ ^ C/evolution.xml:2501: parser error : Entity 'rdquo' not defined r interface for Evolution, he can see the message both in the “Anna” ^ C/evolution.xml:2501: parser error : Entity 'ldquo' not defined see the message both in the “Anna” search folder and in the “ ^ C/evolution.xml:2501: parser error : Entity 'rdquo' not defined Anna” search folder and in the “Internal Evolution Discussion” ^ C/evolution.xml:2607: parser error : Entity 'trade' not defined <para>This section shows you how to use the Evolution™ contacts tool to ^ C/evolution.xml:2654: parser error : Entity 'ldquo' not defined a small dialog box with text boxes for first and last names, titles like “ ^ C/evolution.xml:2654: parser error : Entity 'rdquo' not defined alog box with text boxes for first and last names, titles like “Mr.” ^ C/evolution.xml:2654: parser error : Entity 'ldquo' not defined th text boxes for first and last names, titles like “Mr.” or “ ^ C/evolution.xml:2654: parser error : Entity 'rdquo' not defined t and last names, titles like “Mr.” or “Her Excellency,” ^ C/evolution.xml:2654: parser error : Entity 'ldquo' not defined ike “Mr.” or “Her Excellency,” and suffixes like “ ^ C/evolution.xml:2654: parser error : Entity 'rdquo' not defined ;Mr.” or “Her Excellency,” and suffixes like “Jr.” ^ C/evolution.xml:2654: parser error : Entity 'ldquo' not defined editor would have correctly guessed that the entry should be filed under “ ^ C/evolution.xml:2654: parser error : Entity 'rdquo' not defined orrectly guessed that the entry should be filed under “Doe, John Q.” ^ C/evolution.xml:2654: parser error : Entity 'ldquo' not defined e filed under “Doe, John Q.” However, Miguel's surname, “ ^ C/evolution.xml:2654: parser error : Entity 'rdquo' not defined ldquo;Doe, John Q.” However, Miguel's surname, “de Icaza” ^ C/evolution.xml:2868: parser error : Entity 'ldquo' not defined rd for each family member, then add those cards to a contact list called “ ^ C/evolution.xml:2868: parser error : Entity 'rdquo' not defined mily member, then add those cards to a contact list called “Family.” ^ C/evolution.xml:2868: parser error : Entity 'ldquo' not defined g each person's e-mail address individually, you can send e-mail to “ ^ C/evolution.xml:2868: parser error : Entity 'rdquo' not defined 's e-mail address individually, you can send e-mail to “Family” ^ C/evolution.xml:2886: parser error : Entity 'ldquo' not defined that you leave the addresses hidden. This is the same thing as using the “ ^ C/evolution.xml:2886: parser error : Entity 'rdquo' not defined ave the addresses hidden. This is the same thing as using the “Bcc:” ^ C/evolution.xml:2899: parser error : Entity 'ldquo' not defined or no category at all. For example, you put a friend's card in the “ ^ C/evolution.xml:2899: parser error : Entity 'rdquo' not defined at all. For example, you put a friend's card in the “Business” ^ C/evolution.xml:2899: parser error : Entity 'ldquo' not defined rd in the “Business” category because he works with you, the “ ^ C/evolution.xml:2899: parser error : Entity 'rdquo' not defined uo;Business” category because he works with you, the “Friends” ^ C/evolution.xml:2899: parser error : Entity 'ldquo' not defined , the “Friends” category because he's a friend, and the “ ^ C/evolution.xml:2899: parser error : Entity 'rdquo' not defined iends” category because he's a friend, and the “Frequent” ^ C/evolution.xml:2941: parser error : Entity 'trade' not defined <para>This section shows you how to use the Evolution™ Calendar to manag ^ C/evolution.xml:3199: parser error : Entity 'reg' not defined <para>If you are using a calendar on a Novell GroupWise® or Microsoft E ^ C/evolution.xml:3222: parser error : Entity 'ldquo' not defined recur. Make your selections from left to right, and you form a sentence: “ ^ C/evolution.xml:3222: parser error : Entity 'rdquo' not defined ntence: “Every two weeks on Monday and Friday until January 3, 2008” ^ C/evolution.xml:3222: parser error : Entity 'ldquo' not defined quo;Every two weeks on Monday and Friday until January 3, 2008” or “ ^ C/evolution.xml:3222: parser error : Entity 'rdquo' not defined 2008” or “Every month on the first Friday for 12 occurrences.” ^ C/evolution.xml:3230: parser error : Entity 'ldquo' not defined ppointment, you can specify the attendees in several categories, such as “ ^ C/evolution.xml:3230: parser error : Entity 'rdquo' not defined you can specify the attendees in several categories, such as “chair” ^ C/evolution.xml:3230: parser error : Entity 'ldquo' not defined cify the attendees in several categories, such as “chair” or “ ^ C/evolution.xml:3230: parser error : Entity 'rdquo' not defined es in several categories, such as “chair” or “required.” ^ C/evolution.xml:3558: parser error : Entity 'reg' not defined on lets you view and manage calendars on remote CalDAV servers such as Hula® ^ C/evolution.xml:3644: parser error : Entity 'ldquo' not defined ign a task, you can specify the attendees in several categories, such as “ ^ C/evolution.xml:3644: parser error : Entity 'rdquo' not defined you can specify the attendees in several categories, such as “chair” ^ C/evolution.xml:3644: parser error : Entity 'ldquo' not defined cify the attendees in several categories, such as “chair” or “ ^ C/evolution.xml:3644: parser error : Entity 'rdquo' not defined es in several categories, such as “chair” or “required.” ^ C/evolution.xml:3765: parser error : Entity 'trade' not defined <para>Evolution™ Exchange for Microsoft Exchange allows Evolution client ^ C/evolution.xml:3826: parser error : Entity 'ldquo' not defined s is exactly the one that the Exchange server has on file. This might be “ ^ C/evolution.xml:3826: parser error : Entity 'rdquo' not defined er has on file. This might be “yourname@exchange-server.example.com” ^ C/evolution.xml:3826: parser error : Entity 'ldquo' not defined might be “yourname@exchange-server.example.com” rather than “ ^ C/evolution.xml:3826: parser error : Entity 'rdquo' not defined xchange-server.example.com” rather than “yourname@example.com” ^ C/evolution.xml:3867: parser error : Entity 'ldquo' not defined Folder Content Locally for Offline Operation. For more information, see “ ^ C/evolution.xml:3867: parser error : Entity 'rdquo' not defined y for Offline Operation. For more information, see “Working Offline” ^ C/evolution.xml:3909: parser error : Entity 'reg' not defined <para>The <ulink url="http://support.novell.com">Novell® Web site Knowle ^ C/evolution.xml:3995: parser error : Entity 'ldquo' not defined olution Exchange, like delegation and permissions handling, creation of “ ^ C/evolution.xml:3995: parser error : Entity 'rdquo' not defined ke delegation and permissions handling, creation of “Out of Office” ^ C/evolution.xml:4155: parser error : Entity 'ldquo' not defined are not available during the times you have scheduled a meeting, you can “ ^ C/evolution.xml:4155: parser error : Entity 'rdquo' not defined lable during the times you have scheduled a meeting, you can “nudge” ^ C/evolution.xml:4161: parser error : Entity 'trade' not defined <para>Evolution™ can access accounts on Novell® GroupWise® 7 sys ^ C/evolution.xml:4161: parser error : Entity 'reg' not defined <para>Evolution™ can access accounts on Novell® GroupWise® 7 sys ^ C/evolution.xml:4161: parser error : Entity 'reg' not defined <para>Evolution™ can access accounts on Novell® GroupWise® 7 sys ^ C/evolution.xml:4443: parser error : Entity 'ldquo' not defined are not available during the times you have scheduled a meeting, you can “ ^ C/evolution.xml:4443: parser error : Entity 'rdquo' not defined lable during the times you have scheduled a meeting, you can “nudge” ^ C/evolution.xml:4835: parser error : Entity 'trade' not defined <para>Evolution™ supports mail connectivity to Hula® servers through ^ C/evolution.xml:4835: parser error : Entity 'reg' not defined <para>Evolution™ supports mail connectivity to Hula® servers through ^ C/evolution.xml:4852: parser error : Entity 'trade' not defined for your appointments. Whatever the reason, you can change your Evolution™ ^ C/evolution.xml:4886: parser error : Entity 'ldquo' not defined ling. This includes the ability to substitute graphical smiley faces for “ ^ C/evolution.xml:4886: parser error : Entity 'rdquo' not defined des the ability to substitute graphical smiley faces for “emoticons” ^ C/evolution.xml:4905: parser error : Entity 'reg' not defined op">POP</link>), read and keep it on the server (Microsoft Exchange, Novell® ^ C/evolution.xml:4905: parser error : Entity 'reg' not defined , read and keep it on the server (Microsoft Exchange, Novell® GroupWise® ^ C/evolution.xml:5001: parser error : Entity 'ldquo' not defined age arrives. However, spammers can use image loading patterns to confirm “ ^ C/evolution.xml:5001: parser error : Entity 'rdquo' not defined . However, spammers can use image loading patterns to confirm “live” ^ C/evolution.xml:5086: parser error : Entity 'reg' not defined here. You must install the gnome-spell package, available through ZENworks® ^ C/evolution.xml:5086: parser error : Entity 'reg' not defined in Evolution. Additional dictionaries are also available through Red Carpet® ^ C/evolution.xml:5328: parser error : Entity 'verbar' not defined s from the server.ObjectClass=User: Lists only the user objects.Filter (| ^ C/evolution.xml:5345: parser error : Entity 'trade' not defined uter needs to recognize and access your handheld. At this time, Evolution™ ^ C/evolution.xml:5402: parser error : Entity 'trade' not defined k, but not Microsoft Exchange, this section helps you switch to Evolution™ ^ C/evolution.xml:5464: parser error : Entity 'trade' not defined as a quick reference for most of the things you want to do with Evolution™ ^ C/evolution.xml:5539: parser error : Entity 'trade' not defined <para>Evolution™ bug tracking is done at the <ulink url="http://bugzilla ^ C/evolution.xml:5541: parser error : Entity 'reg' not defined elp with Evolution, visit the <ulink url="http://support.novell.com">Novell® ^ C/evolution.xml:5546: parser error : Entity 'trade' not defined <para>Evolution was written by the Evolution™ team and numerous other de ^ C/evolution.xml:5599: parser error : Entity 'trade' not defined ains terms that are frequently used in this guide as well as in Evolution™ ^ C/evolution.xml:5615: parser error : Entity 'reg' not defined <para>A pre-downloading procedure that allows Novell® Evolution™ t ^ C/evolution.xml:5615: parser error : Entity 'trade' not defined <para>A pre-downloading procedure that allows Novell® Evolution™ t ^ C/evolution.xml:5735: parser error : Entity 'ldquo' not defined For example, the statement fly.*so[au]p means any phrase beginning with “ ^ C/evolution.xml:5735: parser error : Entity 'rdquo' not defined le, the statement fly.*so[au]p means any phrase beginning with “fly” ^ C/evolution.xml:5735: parser error : Entity 'ldquo' not defined *so[au]p means any phrase beginning with “fly” and ending in “ ^ C/evolution.xml:5735: parser error : Entity 'rdquo' not defined ans any phrase beginning with “fly” and ending in “soup” ^ C/evolution.xml:5735: parser error : Entity 'ldquo' not defined ase beginning with “fly” and ending in “soup” or “ ^ C/evolution.xml:5735: parser error : Entity 'rdquo' not defined ng with “fly” and ending in “soup” or “soap” ^ C/evolution.xml:5735: parser error : Entity 'ldquo' not defined o;soap”. If you searched for that expression, you'd find both “ ^ C/evolution.xml:5735: parser error : Entity 'rdquo' not defined searched for that expression, you'd find both “fly in my soup” ^ C/evolution.xml:5735: parser error : Entity 'ldquo' not defined r that expression, you'd find both “fly in my soup” and “ ^ C/evolution.xml:5735: parser error : Entity 'rdquo' not defined 'd find both “fly in my soup” and “fly in my soap.” ^ C/evolution.xml:5816: parser error : Entity 'copy' not defined <member>Copyright © 2004 Novell, Inc. All rights reserved. No part of t ^ xsltproc -o evolution-C.omf --stringparam db2omf.basename evolution --stringparam db2omf.format 'docbook' --stringparam db2omf.dtd "-//OASIS//DTD DocBook XML V4.1.2//EN" --stringparam db2omf.lang C --stringparam db2omf.omf_dir "/home/build-head/mbe/share/omf" --stringparam db2omf.help_dir "/home/build-head/mbe/share/gnome/help" --stringparam db2omf.omf_in "`pwd`/./evolution.omf.in" `/home/build-head/mbe/bin/pkg-config --variable db2omf gnome-doc-utils` C/evolution.xml db2omf: Invalid subject code "GNOME|Internet" in /home/build-head/cvs/gnome2/evolution/help/./evolution.omf.in. make[2]: *** [evolution-C.omf] Error 10 make[2]: Leaving directory `/home/build-head/cvs/gnome2/evolution/help' make[1]: *** [all-recursive] Error 1 make[1]: Leaving directory `/home/build-head/cvs/gnome2/evolution' make: *** [all] Error 2
The last error (db2omf) is explained here. http://www.mail-archive.com/desktop-devel-list@gnome.org/msg07738.html try to run ./autogen.sh before building with jhbuild. The other errors seem to be a problem with docbook entities. I will try to see what's wrong with gnome-doc-utils, i'm using current stable version, and I think I need a fresh one from cvs.
I get a correct docbook document translated. I still see parser errors and warnings about missing files, that should be resolved adding the required files. I will review the original doc during translation. No idea about what is wrong with entities, but the generated doc is ok.
Those entity errors happen because gnome-doc-utils does not load the DTD when it's just parsing. The reason it doesn't is that Yelp doesn't load the DTD. And Yelp doesn't load the DTD because it's caused us nothing but problems in the past. We generally advocate the use of full UTF-8 in DocBook files. On the rare occasion this is insufficient (escaping left angle brackets, for instance), you can always use the decimal or hex entities, rather than the DTD-dependant named entities. I had a look at the Evolution manual to see where you're using named entities. The trade and reg entities should be replaced with DocBook's trademark tag. For registered trademarks, use role="registered". The ldquo and rdquo entities are all over the place. Sometimes they surround interface elements (Shrink To/CC/Bcc headers to), and should be replaced with the guilabel element. Sometimes they surround user input, so should be replaced with the DocBook userinput element. Sometimes they really are just quotes, in which case either the actual characters can be used, or the DocBook quote element can be used.
Bumping version to a stable release.
The parser errors are fixed now so closing this.