GNOME Bugzilla – Bug 465460
[patch] French doc improvements
Last modified: 2008-06-29 15:09:27 UTC
Documentation Section: French manual hard copies rendering (pdf & ps) is not conform with French printed documents rules Correct version: corrected by patch (provided you have dblatex -- which is optional) Other information: * improved hardcopies.makefile with selectors * introducing hardcopies.sh: detection of needed software and automated compilation (environment variables setup for hardcopies.makefile) * moving eps captures into graphics directory * installation, uninstallation and cleanup works too * fixed figure filename (preferences_fig) * fixed xml declaration in dia.xml
Created attachment 93450 [details] [review] svn diff -x '-u' => doc patch
Is there are strong reason to use dblatex rather than db2latex? db2latex is more widespread, and besides db2latex is available for my Ubuntu installation:) Also, after the move to SVN, patches are no longer the best way to move files, rather it should be done out-of-band with SVN commands. Keeps the history around.
tom@geekette:~$ lsb_release -i Distributor ID: Debian tom@geekette:~$ uname -a Linux geekette 2.6.18-4-k7 #1 SMP Wed May 9 23:42:01 UTC 2007 i686 GNU/Linux tom@geekette:~$ aptitude search db2latex tom@geekette:~$ :) OK, I'll search for and install it, then makes a switch on dblatex/db2latex commands to be able to built the doc with both ones. I acknowledge too the file moving handle via svn (will also study if it is given in svn patch). Regards,
Well, I tried out db2latex xsls: - doesn't work out of the box, because there is a problem with <variablelist>. - after having modified lists.mod.xsl and commenting offending code, it compile, but xml samples in "shapes" chapter are not correctly rendered - "<" and ">" are displayed as "?" and revert "?" - "verb" TeX command appears in the text :) So, it appears that db2latex xsl are unusable. I will try out the CVS version, as some files seems "newer" than in the _old_ tar.gz distributed at sourceforge. Hope the version distributed along with Ubuntu is the cvs one :)
OK, now that dblatex is part of Ubuntu distro, I can come back on this patch :p - So, the two attachments following are improvement to the whole doc (fr, en, eu, there are still problems with pl on my Debian (lll macro causes pdf and ps compilations to fail on it, but commands are dashed in hardcopies.make). - I think I have definitely solved the resolution from scrollkeeper (skrollkeeper uses a _derivate_ omf format). - there is still a problem with the integrated doc ui while not compiled with gnome support: the directory opened is the good one, but it fails to list it (see "trace" attachment).
Created attachment 111744 [details] [review] svn diff -x '-u' => whole doc patch
Created attachment 111745 [details] => doc/html (png and css) images for admonitions and callouts (for html version)
Created attachment 111746 [details] stack trace (search "help") while help/doc fails (gnome=no)
Created attachment 112006 [details] [review] svn diff -x '-u'. Please use ./configure --with hardbooks Little correction: use "native" dblatex style instead of "simple" from obsoleted patch #111744. also reverted manpages from svn to avoid maintainers have to restore ;)
I have tried to apply your patch and test it but failed (make -f hardcopies.makefile works on the same system). My guess is you configure check is too system specific. My gentoo neither has db2html nor db2latex but it has openjade and jw - enough to build the old way. Some more questions arose while looking in detail: * shouldn't the identical html.xsl in all the language specific subdirctories be moved into the doc/ dir, too? * your patch adds images (doc/html/*.svg) which I would expect to be available with the documentation framework. Wouldn't these local copies decrease overall consistency of the documentation? * the ChangheLog entry I came up with is below. I'm not sure it sufficently decribes your changes. It would simplify the work to apply the patch if the suggested ChangeLog entry would be included in it * as already mentioned on the mailing list [1] keeping the single bug entries on topic also increase the probability to have patches applied. A more iterative set of patches would allow to apply the working parts and not make the rest accumulate to a size barely manageable (at least for me;)) 2008-06-08 Hans Breuer <hans@breuer.org> [Patch from Thomas Harding improving the documentation generation] * doc/*/hardcopies.makefile : moved to parent directory * doc/*/README.hardcopies : removed, now handled by configure * configure.in : check for and do documentation generation when given --with-hardbooks * doc/**/*.xml : dropping HTML entities, making dia-1.xml independant from dia-cmdline.xml, dropping file extension from graphics * doc/*dia-dbk-to-chapter.sed : removed leftovers from previus doc patch * doc/html/images/caution.svg doc/html/images/important.svg doc/html/images/note.svg doc/html/images/tip.svg doc/html/images/prev.svg doc/html/images/home.svg doc/html/images/next.svg doc/html/images/warning.svg doc/html/images/up.svg doc/html/css/dia.css : new files - images for admonitions and callouts (for html version)
* dropped svg files. * guessed finally the right encoding of Polish translation (was iso-8859-2) * added switch to not use Babel for Polish as there is a conflict with AMS fonts package. Allows building of ps and pdf versions, with minor side effect: chapter numbering and admonitions are in English. Will post to the respective maintainers a request to change "lll" macro name to something else (such as AMSlll and Babellll... :) IMPORTANT: * you need to run ./configure --(whatever) --with-hardbooks in order to build them. I can change that to not use switch at all if you think thats harmful * As xsltproc is already used by db2html to build manpages, I guess every maintainers have at least xsltproc, so it's ok for html. * dblatex is a python program you can find at sourceforge if it is not in your distro. cd to the uncompressed top dir then type "python setup.py install" * As Polish is iso-88592 coded, I have no solution other than dblatex to build it in pdf/ps (except iconv to sgml entities, but it will make it unreadable for non-specialists, as the number of glyphs not matching Latin1 is Huge). Same side-effect with utf8 for French and potential future translations (jw needs Latin1 + ISO SGML entities, quite limiteds). * For Polish, I think that we can drop *.sgml in accordance with the maintainer: these files are in Latin2, and doc tools cannot handle that automagically. Minor changes between sgml and xml, such as close the graphic element by />. * Changelog: I do not want to edit it myself -- maintainer job -- What I can do is add Changelog-tmp to the patch. Copy/paste then drop :) ###################### # CHANGELOG ###################### [Patch from Thomas Harding improving the documentation generation] * doc/*/hardcopies.makefile : moved to parent directory * doc/*/README.hardcopies : removed, now handled by configure * configure.in : check for and do documentation generation when given --with-hardbooks * doc/**/*.xml : dropping HTML entities, making dia-1.xml independent from dia-cmdline.xml, dropping file extension from graphics * doc/*dia-dbk-to-chapter.sed : removed leftovers from previous doc patch (was too fragile) * doc/html/images/caution.svg doc/html/images/important.svg doc/html/images/note.svg doc/html/images/tip.svg doc/html/images/prev.svg doc/html/images/home.svg doc/html/images/next.svg doc/html/images/warning.svg doc/html/images/up.svg doc/html/css/dia.css : new files - images for admonitions and callouts (for html version) * doc/fr/dia.xml: switched encoding to utf8 (more versatile for inexperienced maintainers (needs no entities for specific glyphs such as ISO entity oelig) * doc/pl/*.xml: updated some from *.sgml, corrected encoding to iso-8859-2. Corrected graphics "filetype" attribute to uppercase PNG.
Created attachment 112643 [details] [review] svn diff -x '-u'. Please use ./configure --with hardbooks Please see last comment above
############ #CHANGELOG: (forgotten) ############ * hardcopies.make now uses dblatex instead of jw. http://dblatex.sourceforge.net/. unpack then cd to top directory then type "python setup.py install"
Created attachment 112952 [details] [review] svn diff -x '-u'. Please use ./configure --with hardbooks Finally found a solution to fallback on jw, and makes jw works with documents which fit to ISO sgml entities (currently all, but don't expect anything for Chinese ;). Note: you needs both "flip" and "recode", as there are problems with carriage returns with the last. [Patch from Thomas Harding improving the documentation generation] * doc/*/hardcopies.makefile : moved to parent directory * hardcopies.make now uses dblatex or fallback on jw (jade/openjade wrapper). * doc/*/README.hardcopies : removed, now handled by configure * configure.in : check for and do documentation generation when given --with-hardbooks * doc/**/*.xml : dropping HTML entities, making dia-1.xml independent from dia-cmdline.xml, dropping file extension from graphics * doc/*dia-dbk-to-chapter.sed: removed leftovers from previous doc patch (was too fragile) * doc/html/images/caution.svg doc/html/images/important.svg doc/html/images/note.svg doc/html/images/tip.svg doc/html/images/prev.svg doc/html/images/home.svg doc/html/images/next.svg doc/html/images/warning.svg doc/html/images/up.svg doc/html/css/dia.css: new files - images for admonitions and callouts (for html version) * doc/fr/dia.xml: switched encoding to utf8 (more versatile for inexperienced maintainers (needs no entities for specific glyphs such as ISO entity "oelig" or "laquo"...) * doc/pl/*.xml: updated some from *.sgml, corrected encoding to iso-8859-2. Corrected graphics "filetype" attribute to uppercase "PNG". * Adding Changelog-tmp, which may be dropped at any time. * doc/*/dia-*.omf: make indexation really works with scrollkeeper (which extends omf format). Now yelp shows dia manual in its TOC/whatever.
last, and I hope least: html.xsl are not identical for all languages (It is different for French, but I don't know the rules for title placement on figures/tables... for the others)
Finally commited to not go to this huge patch one more time. There are still some glitches where I would like to get help. The most important one first: make distcheck fails with: ERROR: files left after uninstall: (check DESTDIR support) ./mnt/Home/from-svn/dia.doc/dia-0.96+svn/_inst/share/omf/dia/dia-C.omf ./mnt/Home/from-svn/dia.doc/dia-0.96+svn/_inst/share/omf/dia/dia-fr.omf ./mnt/Home/from-svn/dia.doc/dia-0.96+svn/_inst/share/omf/dia/dia-eu.omf ./mnt/Home/from-svn/dia.doc/dia-0.96+svn/_inst/share/omf/dia/dia-pl.omf make[1]: *** [distuninstallcheck] Error 1 doc/(en|fr)/dia-cmdline.xml was missing Making all in pl make[3]: Entering directory `/mnt/Home/from-svn/dia.doc/doc/pl' /bin/sh ../../mkinstalldirs ./dia_html mkdir -p -- ./dia_html /bin/sh ../../mkinstalldirs ./dia_html/graphics mkdir -p -- ./dia_html/graphics /bin/sh ../../mkinstalldirs ./dia_html/images mkdir -p -- ./dia_html/images /bin/sh ../../mkinstalldirs ./dia_html/images/callouts mkdir -p -- ./dia_html/images/callouts /bin/sh ../../mkinstalldirs ./dia_html/css mkdir -p -- ./dia_html/css cp ../html/images/*.png ./dia_html/images cp: cannot stat `../html/images/*.png': No such file or directory make[3]: [dia_html] Error 1 (ignored) cp ../html/images/callouts/*.png \ ./dia_html/images/callouts cp: cannot stat `../html/images/callouts/*.png': No such file or directory make[3]: [dia_html] Error 1 (ignored) cp ../html/css/*.css ./dia_html/css cp ./graphics/*.png ./dia_html/graphics cd ./dia_html \ && xsltproc --stringparam graphic.default.extension png \ ../html.xsl ../dia.xml ../html.xsl:40: parser error : XML declaration allowed only at the start of the document <?xml version="1.0" encoding="US-ASCII"?> ^ ../html.xsl:41: parser error : Extra content at the end of the document <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> ^ cannot parse ../html.xsl make[3]: *** [dia_html] Error 4 make[3]: Leaving directory `/mnt/Home/from-svn/dia.doc/doc/pl' make[2]: *** [all-recursive] Error 1 make[2]: Leaving directory `/mnt/Home/from-svn/dia.doc/doc' make[1]: *** [all-recursive] Error 1 make[1]: Leaving directory `/mnt/Home/from-svn/dia.doc' make: *** [all] Error 2
OOOoops, for me STATUS was CLOSE. I posted a patch to correct that yesterday night (2008-06-23 22:32 UTC) see BUG #539848 COMMENT #539848#c1 ATTACHMENT #113300 [details] ATTACHMENT #113301 [details]
Created attachment 113584 [details] [review] svn diff -x '-u' => re-adding of missings doc/fr/dia-cmdline.xml, doc/eu/dia-1.xml It seems a new checkout working copy of trunk misses * doc/fr/dia-cmdline.xml * doc/eu/dia-1.xml. So, please, either: * re-add these files from your working copy (svn add doc/fr/dia-cmdline.xml doc/eu/dia-1.xml) * **OR** apply the patch, then svn add doc/fr/dia-cmdline.xml doc/eu/dia-1.xml
Created attachment 113589 [details] [review] svn diff -x '-u' * hardcopies.make: * corrected paths to fit --psdir --pdfdir --htmldir ./configure switches * corrected targets $(progname)(.pdf|.ps|_html) and .jw: to depend on $(xml_files) instead of (duplicate of xml_files) $(xmlsources) * doc/(en|eu|fr|pl): deleting $(xmlsources)
restored the files, applied the patch: 2008-06-29 Hans Breuer <hans@breuer.org> [Third iteration on patch from Thomas Harding improving the documentation generation, closing bug #465460] * doc/en/Makefile.am doc/fr/Makefile.am doc/eu/Makefile.am doc/pl/Makefile.am : deleting $(xmlsources) * hardcopies.make : corrected paths to fit --psdir --pdfdir --htmldir ./configure switches; corrected targets $(progname)(.pdf|.ps|_html) and .jw: to depend on $(xml_files) instead of (duplicate of xml_files) * doc/fr/dia-cmdline.xml doc/eu/dia-1.xml : added, bug #465460