From kde-i18n-doc Sat Jul 28 02:15:27 2001 From: Eric Bischoff Date: Sat, 28 Jul 2001 02:15:27 +0000 To: kde-i18n-doc Subject: San Diego X-MARC-Message: https://marc.info/?l=kde-i18n-doc&m=99628669005521 Hi all, Sorry for the cross-posting... Below is my summary for the Open Source Documentation Summit that took place in San Diego last week. Happy reading for those who are interested. --------------------------------------------------------------- 2nd O'Reilly Documentation Summit Sheraton San Diego, CA, USA July the 22nd, 2001 The purpose of the Documentation Summit was to evaluate the current state of Open Source documentation and documentation technologies and to impulse initiatives and cooperation beetween the various projects. It took place prior to O'Reilly Open Source Convention. Participants included Guylhelm Aznar (LDP), Eric Bischoff (KDE/Caldera), Nik Clayton (FreeBSD), Mark Galassi (docbook-tools), Ronald Hayden (Apple computer), Brad Kuhn (FSF), Laurie Petrycki (O'Reilly), Eric S. Raymond (author), Michael Smith (xml-doc), Bob Stayton (Caldera ex-SCO), Norman Walsh (Sun Microsystems) and Joy Yokley (IBM), among others. As last years, most participants were DocBook users, and gave the impression the spreading of DocBook technology is bursting. There only seems to be some resistance among some contributors of the LDP project who still use linuxdoc. This year, the participants focused mainly on the tools chain. They identified two major problems: - printing with the XSLT stylesheets; - the lack of a good Open-Sourced, graphical, DocBook editor. For what concerns printing with XSLT, db2latex or passiveTeX were discarded as solutions, essentially due to the poorness of TeX support for internationalization, and to the difficulty to have TeX tools correctly set up for the user. A C++ converter from FO (Formatting Objects) to PDF seems to be the correct solution. In the area of authoring, emacs-based editors were not pushed forward because a vast majority of authors (usually former Windows users) would not adapt to the complexity of emacs. People insisted on two basic needs for such an editor: being able to determine the tags available in the current context, and being able to quickly get an idea of the result. Reasons for failure of similar projects were identified as: - too ambitious and generic (and poor knowledge of DocBook-specific needs) - test cases that do not match the scale of complexity of DocBook The discussion on printing and editing issues will follow up on the mailing list in order to organize the development of proper software (either by starting a new project or by jumping into an existing project). Another technical issue was the problem in XML of packaging separatly a document and its DTD, that is made hard due to the lack of catalogs technology in XML. Someone mentioned xml-packaging@w3c.org as a good place to discuss this. There seemed to be a consensus on providing FPIs (Formal Public Identifiers) in documents although they are not mandatory anymore in XML. I mentioned that restricting DTD customization to suppressions (no additions, no modifications), would help easier display the documents of one project with the browser of another project, now that browsers are becoming able to display DocBook on the flight. Although this proposal did not reach a consensus, Nik Clayton (FreeBSD) showed great interest in being able to hook up FreeBSD's documentation into KHelpCenter. Miles Efrom presented the OMF (OpenSource Metadata Framework) (http://www.biblio.org/osrf/omf). The primary purpose is to index every OpenSource documentation from a single repository (KDE documentation is not in!). For this purpose, they developped a set of tags for metadata in continuation of the Dublin Core effort (http://www.perl.org/dc). In conjunction with this effort, the scrollkeeper project, impulsed by last year's summit, is maturing (there's already a hook for it in khelpcenter); its purpose is to install OMF metadata on the end user's machine to allow easier search for relevant documents. Norman Walsh presented extensively the tools chain and evoked issues like namespaces and links between different source documents. Mark Galassi mentioned that the docbook-tools need to handle the XSLT tools chain in addition to the DSSSL one, and that he would work with me on this. I presented basic notions about the translation environment and the new po2xml technology developped by Stephan Kulow, and this really generated enthusiasm. There seemed to be a real need for a simplified subset of DocBook. We also evocated the motivation issues, and I read the communication of Lauri Watts (KDE documentation coordinator) that evokes the situation of the coordinator that has to deal both with time issues (short development cycles), and contributors psychology. The traditional discussion on licenses concentrated in two areas: - Why not abandoning the OPL (Open Publishing License) for the FDL? This would avoid the problems that araised when mergeing docs with different licenses. Unfortunately, this would require every author to give his/her agreement. - Could the licenses provide a way to prevent outdated documentation from keeping being distributed? After the final wrap-up, Guylhelm Aznar announced that next year's meeting will take place in Bordeaux, France. -- +----------------------------------------------------------------------+ | Éric Bischoff mailto:e.bischoff@noos.fr | +----------------------------------------------------------------------+