Kirill A. Korinskiy catap@catap.ru -------------- GuideXML Crossplatform Toolset for Wysiwyg and Collaboration ------------------------------------------------------------ Greetings! I would like to take part in Google Summer Of Code and spend next 3 months to create a GuideXML toolset enabling the use of _wide set of_ popular general purpose XML and text editors to author GuideXML, at the same time retaining the possibility of CVS-based collaborative manual GuideXML authoring, together with web-based authoring. The GuideXML (http://www.gentoo.org/doc/en/xml-guide.xml) is the standard XML-based format used to prepare, store and publish the Gentoo documentation. This format is much simpler than DocBook or DITA, yet well structured, and has all the chances to become wide spread outside Gentoo with some adequate support added. I'm going to spend 35-40 hours a week for this project during my summer holidays and to dedicate all my free time for this project. It`s a first time I take part in Google Summer Of Code. Project Goals ------------- 1. Let authors write documents in GuideXML in any visual or non-visual XML editor of choice without worrying about GuideXML internal layout (in some cases they will just have to configure a trivial style template). 2. Give authors two ready options to edit GuideXML visually in VEX (doc-oriented open sourced XML editor) and OpenOffice.org. 3. Simplify life for editors and responsible international translators by raising the quality of submitted documents without effort, and save their time by allowing to have each and every document in standard internal coding style (e.g. for text diff). 4. Let much more people collaborate on GuideXML documents via the web-based wikis via smart two-way converter. 5. Prepare the solid ground for further integration of GuideXML into the documentation world. Project Benefits ---------------- More authors of and contributors to Gentoo documentation with document creation simplified. Better quality and amount of Gentoo projects documentation. Much better quality and amount of Gentoo internationalization, (letting more international Gentoo users take part in translation without good command in XML and without the need to become a Gentoo developer). Faster documentation development and translation cycle. A way to offer GuideXML as simple yet powerful technical documentation format throughout the world. Deliverables ------------ At the end of SoC, the following list of tools will be developed, tested on the Gentoo's existing documentation, and ready for deployment either on developers' machines, or on servers such as Gentoo CVS server to work together with Repodoc. 1. TidyGuide Style Formatter (backend): The platform-independent GuideXML internal coding style formatter conforming to guidelines listed in http://www.gentoo.org/doc/en/xml-guide.xml, to let authors choose from wider range of XML/text editing tools (all existing editors break standard GuideXML markup on save and thus are unusable at the moment, and editing manually often results in human errors). A set of XSLT templates processible by standard xsltproc. The main challenge here is that TidyGuide have to work stable with different unpredictable files in automated environment. 2. OpenOffice.org filters (for wp-based frontend): The export/import filters and the style template to allow visual editing and converting to/from the GuideXML in OpenOffice.org Writer using its existing wordprocessing power. Will also allow converting GuideXML to wide variety of existing formats supported by OpenOffice. A set of XSLT and document templates. The challenge here is the need to produce reasonable GuideXML from not so structured text document. 3. VEX filters and templates (for xml-based frontend): Means for strict XML-based editing of GuideXML in VEX visual document-oriented XML editor. A css and some modifications to vex code. 4. Two-way Wiki converter (for web-based frontend): The two-way conversion utility between GuideXML and Wiki formats with adjustable wiki tag markup, to allow collaborative development and discussion on the GuideXML documents. Will be extensible with other similar formats (for example, forums' bbcode). The challenge here is dealing with weak structure of wikis when converting to GuideXML. A set of xsl templates and Python code. 5. Documentation: User documentation and guidelines for extending editor support. The set of tool-independent filter templates will also be supplied, allowing for easy extension of the editors list to help spread GuideXML format throughout the world. Justification ------------- On the one side, Gentoo documentation developers and translators obviously have the need to focus on the documents' actual content, not on the formatting. On the other side, all the Gentoo documentation development is about concurrent commits of the documentation to the CVS, and this reveals the requirement to exactly retain each document's internal formatting on commit regardless of the tool it was processed by. There were several tools proposed previously (both web-based and standalone), but none of them became popular because: (a) Each editing tool makes the doc author stuck with it, (b) All of them make the document incompatible with internal formatting guidelines stated in http://www.gentoo.org/doc/en/xml-guide.xml, (c) Each of the dedicated editors lacks some features needed by the authors as it is not worth such an effort to write a full-scale XML or WYSIWYG editor _just for GuideXML_, (d) Any custom editor will require further support, and the chances are that nobody will do that, (e) None of the editors fits all. The decision is rather obvious: Let popular xml editors and word processors (that the users prefer) read, edit, and write GuideXML that is at least 99% compatible with abovementioned guidelines, and just depend on their own word processing power. Let command-line and 'raw xml' fans use those tools they used to, and give them chance to clean up the document with just running a script; Let wysiwyg'ers who feel inconfident with GuideXML intrinsics just open the file and make their work (especially the translators), allowing any language's Lead Translator to just diff and check the team members' work easily. Let wiki-ers collaborate on the document as they see fit, allowing to convert their effort without pain. Additional group who will obviously benefit from this project is the translators of Gentoo's documentation. Different languages use different tools for translation, and no single solution fits all; even the well-known PO format doesn't fit the translator's needs as it's more dedicated to User interface translation, not to the 'smooth document text flow' translation. My approach lets them all use tools they prefer while still standing close with pure GuideXML. This approach exactly fits the Gentoo philosophy, namely, 'Gentoo is about choice'. It doesn't deny any of the choices possible, only allows for new ones. This way it has all the chances to finally win the community ;-) Finally, this project just adds more power to any other effort to create the dedicated GuideXML editor. Project Schedule ---------------- May: 23-31 Analysis phase, research of the existing tools. Communication with Gentoo documentation and i18n team. Further clarification of the design requirements. June: 01-17 TidyGuide formatter development 18-22 TidyGuide formatter testing and debugging using existing Gentoo documentation June 23 - July 06 OpenOffice.org, filters and templates development July: 07-13 OpenOffice.org, templates testing and debugging together with TidyGuide 14-20 Vex, source modifications and templates development 21-24 Vex, testing and debugging together with TidyGuide July 25 - August: 05 Wiki converter design, development and testing August 06-20 Dedicated to documentation and overall additional testing. Plus some time reserve for Wiki. August 21: Deadline. Prehistory ---------- This project will take into an account some previously made efforts by Scott Cytacki (GuideXML for Vex), and the Russian Gentoo i18n project (project lead Alexey Chumakov, achumakov AT gentoo DOT org). Personal -------- I am a second year student of Computer Science in Moscow Technical University of Communications and Informatics, Russia. 18 years old (I'll be 19 by the end of this May). I have been passionate about computers and related stuff from my childhood. I am attracted and charmed by this digital world-- the world I could freely create on my own. Its accuracy and logicality really draws me, and I am willing to share my world with others, I want to make this world free for everyone to create in, and just to feel it his or her own. I am keen on programming at my spare time (from the childhood again). Although I didn't take part in well-known open source projects yet, I already have rather deep experience with C/C++ programming (actually preferring the former), exceeding 3 years. I have an operational experience with xml/xsl, cvs/svn, too, and base knowledge if php, python together with some other languages. I wrote the web-based student testing application now widely used in my University. I've developed some C-based extensions for Python, and designed a compact ocaml website together with my own fortune implementation compatible with the original database format. I have created several system-level tools for Linux like custom implementation of mount/umount/ fusemount/fuseumount/smbmount/smbumount etc. Did a whole bunch of exercise projects using several languages. Have my own custom .emacs :) At last, I tried my luck and succeeded in implementation of my own portable lisp machine in C++. I became enthusiastic about Gentoo over 2 years ago, already having previous Linux experience. Please feel free to contact me with any questions about this proposal. Thank you for for your attention and for considering all this! Links ----- GuideXML http://www.gentoo.org/doc/en/xml-guide.xml I18N http://www.w3.org/International/ Vex http://vex.sourceforge.net/ OpenOffice.org http://www.openoffice.org/ Wiki: http://www.mediawiki.org/ Russian Gentoo i18n http://www.chumakov.ru/gentoo/ Screenshots from Russian project (page is in Russian): http://www.chumakov.ru/gentoo/technology/documentation.html Home mail/Jabber: catap@catap.ru Mobile phone: +7 (916) 3-604-704