[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-i18n-doc
Subject:    San Diego
From:       Eric Bischoff <e.bischoff () noos ! fr>
Date:       2001-07-28 2:15:27
[Download RAW message or body]

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 |
+----------------------------------------------------------------------+

[prev in list] [next in list] [prev in thread] [next in thread]