I've read it carefully, and it sounds great if everyone follow the rules. Christian, I'm well aware of documentation process to know that you did a huge and great job, congrats!
Any idea of a collaborative translation work (especially on the initial translation process)? Playing with small teams managed by a leader seems the easiest way to me right now. Emmanuel -----Message d'origine----- De : [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] la part de Christian Bauer Envoye : vendredi 26 mars 2004 00:56 A : [EMAIL PROTECTED] Objet : [Hibernate] Documentation README OK guys, this is the new process. Most of it is only relevant for the translators, they have a copy of that README. Don't be afraid, it's not as complex as it looks. Emmanuel, you are the guy for the French translation, keep a copy and read it thoroughly. All other committers to the original (English) documentation: Read it at least once, especially the parts about "id" and "revision" attributes. I won't have mercy if someone destroys the change tracking for the translators. It's trivial, ask me if you need more info. ----------------------------------------------------------------- THE HIBERNATE DOCUMENTATION Preface The Hibernate documentation is a modular documentation, it uses various XML files (written with the DocBook DTD) and a Java-based build process to generate HTML and PDF output. Use a simple text editor with XML support, such as JEdit, to edit the source files. You will need Java and Ant installed for the output generation, it is Java only and should work on any operating system. Note that this README sounds complex, but the process is actually quite easy to learn and use. Don't skip steps, just because you don't like them, ask first. Read it twice if neccessary. 1. How to get it Check out a copy of Hibernate from CVS (v21branch). A regular Hibernatea download will not contain the build process for the documentation, only the PDF/HTML output, use CVS! You can use anonymous CVS on SourceForge as described on the Hibernate download page, http://www.hibernate.org/Download/DownloadOverview 2. Working on the original language The original and master language is English, hence the "en" subdirectory in /doc/reference/ is authorative. We use "id" and "revision" attributes on XML elements to track changes. Here are the rules, they are mandatory: 2a. Changing existing content involves an update of the "revision" of the XML element you are working on (e.g. a <sect1>, <sect2> or even a <para>). If a <sect1> has a revision="1", you update it to "2" after updating the content in that section. You can also add revision attributes to elements that don't have one, start with "1". You can add revision attributes to any element, dependent on your changes, but the smallest should be a <para>. You can't add a revision attribute to elements without an "id" attribute! If the element you wish to update has no id, have a look at the id of the parent element and use a similar (unique) new identifier attribute for your child element (or, simply update the revision of the parent). Never enumerate new id values, use short clear text. After adding an id attribute, the element will be visible in change tracking. 2b. Adding new content involves adding new elements (even new files), such as <sect1>, <para> and so on. Any new element (or its new parent element) needs an "id" attribute! If you add a <sect1>, give it a unique short text identifer, look at the parent element's identifier for the common prefix. 2c. Deleting content involves removing old elements. Just remove them and make sure that the parent elements revision is updated, if the removed element did not itself have an identifer and a revision. If you removed an element with its own identifier, everything is fine. 3. Starting a new language If you start a translation for a new language, you have to copy the default language (English) and start an initial translation. 3a. First, duplicate the default language "en" by duplicating the directory /doc/reference/en. For example, a new German translation will be a copy of that directory in /doc/reference/de. We use the ISO codes to name the language subdirectories. 3b. You also have to add your new language to the language build file, /doc/reference/build.xml. Look for the lines that have a "TRANSLATOR" comment and duplicate them. Change the default "en" to your language code. You will then be able to use the change tracking and PDF/HTML output generation. 4. The initial translation If you just copied the default language, start translating the DocBook XML modules and illustrations in the new language subdirectory. For example, all modules for German would be in /doc/reference/de/modules and all illustrations in /doc/reference/de/images, note that you also have to translate the master.xml in your language subdirectory. The initial translation is straightforward: Translate all modules and all illustrations, but don't add any files, don't add any new XML elements (like a section or a chapter, not even a paragraph). Simply translate sentence by sentence. This is very important. If you need a new section or paragraph, because your translation requires more explanation, you can add it if you also add an "id" and a "revision". For example, if you add a new <para> element to the existing document, give it an identifier, a short clear text extending the identifier of the parent element: <para id="queryhql-projection-specialnote"> would be a special paragraph in the <sect1 id="queryhql-projection"> section in the chapter <chapter id="queryhql">. Never add a new element in a translated version without setting a new unique identifier value! Also, you have to mark this new element as "only relevant in the translated version". Simply set the "revision" attribute of your new element to "-1". For example, we set the previously created paragraph to "only relevant in the translation" by declaring <para id="queryhql-projection-specialnote" revision="-1">. Changes to that paragraph will not be tracked, it is your responsibility to watch out for neccessary updates. You may alsouse this technique (setting the revision to "-1") later, if you have elements that are only present in your translation). 5. Getting updates Translators get updates by updating their CVS working directory, the default language directory "en" must be updated from the Hibernate CVS. You, as a translator, will get an e-mail from us when translation is required, you can then update your copy. The documentation process can generate a report after you updated from CVS and show you what needs to be translated and/or removed in your local translation copy. To generate that report, run "ant all.revdiff" in the doc/reference/ subdirectory. Click on the generated HTML report file for your language and you will see what has to be updated and/or removed. 6. Translating the updates If the report indicates that content in the original has been removed, simply remove the identified XML element from your language modules. If the report detects a new revision, open the file that has been updated in your translation, find the identified XML element and update/translate its contents. Important: Make sure you also update the "revision" attribute of that XML element by setting it to the same version as in the original file, hence both the original XML file and your translated file should have the same revision number for all elements. If an XML element in your translation doesn't have a revision, but the original file has, add a new "revision" attribute to your XML element. The HTML report shows the identifiers and revisions for both the original and the translated files, use it to compare. Rerun the "ant all.revdiff" report generation as often as you like, until no more differences are detected. You should always try to get your copy clean, with all updated revisions and all identified elements synchronzied. 7. Getting a preview Everyone can generate a PDF and HTML output of the documentation by simply running "ant all.doc" in the doc/reference/ subdirectory. 8. Committing your translation All translators will be asked to submit their translated versions from time to time. This will be a manual process, you will get an e-mail from the Hibernate team and simply send your language subdirectory as a ZIP file to us. It will then be integrated in the main Hibernate distribution and on the website. -- Christian Bauer [EMAIL PROTECTED] http://www.hibernate.org/ ------------------------------------------------------- This SF.Net email is sponsored by: IBM Linux Tutorials Free Linux tutorial presented by Daniel Robbins, President and CEO of GenToo technologies. Learn everything from fundamentals to system administration.http://ads.osdn.com/?ad_id=1470&alloc_id=3638&op=click _______________________________________________ hibernate-devel mailing list [EMAIL PROTECTED] https://lists.sourceforge.net/lists/listinfo/hibernate-devel ------------------------------------------------------- This SF.Net email is sponsored by: IBM Linux Tutorials Free Linux tutorial presented by Daniel Robbins, President and CEO of GenToo technologies. Learn everything from fundamentals to system administration.http://ads.osdn.com/?ad_id=1470&alloc_id=3638&op=click _______________________________________________ hibernate-devel mailing list [EMAIL PROTECTED] https://lists.sourceforge.net/lists/listinfo/hibernate-devel
