Mail Archive Home | architecture List | Febuary 2005 Index
| <-- Date Index --> | <-- Thread Index --> |
Hi,we have been using Apache Forrest for the XQuark project. Forrest is a nice processor based on Cocoon which helps in generating a Web site (as well as PDF documents) from a set of XML files. Forrest defines a relatively simple DTD (much simpler than DocBook) which is suitable for writing user guides. Please check our site at xquark.objectweb.org to see it in action. I believe a significant part of the apache web site is built with forrest.
We use OpenOffice (OOo) to edit the XML documents. OpenOffice has a nice feature which allows XML documents to be transformed on the fly from the internal OOo format to any XML format, using XSL-T stylesheets and an OpenOffice template (the style names in the template are used to transform the openoffice document into the target document). I am quite sure (but I didn't check yet) that we should be able to find a similar package to translate from OOo to DocBook, if the general feeling is that DocBook is the way to go.
To summarise, the proposed approach is as follows:1. Define a DTD (or XML Schema or Relax NG schema) for the ObjectWeb documentation. It could be DocBook, Forrest or another one. The more standard it will be, the more likely we are to find existing transformations to cover the next two points. 2. Define the appropriate XSL-T transformations to translate documents from that DTD to XHTML and/or PDF, for publishing. 3. Define the appropriate OOo template and XSL-T transformations to translate documents between OOo format and that DTD, for editing.
Obvoiusly, we are ready to contribute our stuff if you feel it can be useful.
Cheers Antoine claus.hirth@xxxxxxxxxxxxxx a écrit :
Emmanuel Cecchet <emmanuel.cecchet@xxxxxxxxxxxxxxxx> wrote on 07.02.2005 10:11:14:> Hi all, > > I forward this thread on the architecture mailing list to have the input > from the community. > As a first answer, I would strongly suggest that all proprietary formats > from commercial tools such as Word are banished for our open source > projects. ok > DocBook is a nice format but as David points out there is currently no > good and free editor for DocBook. Please let us know if you know one ! No. > Recently, we used OpenOffice for all tutorials and howtos in C-JDBC, > that eases contributions and writing docs OpenOffice is a practical choice. But is it good enough long term? > since XML is very tedious > without an appropriate editor. I would like to drop a MUST requirement onto the table: The documentation standard must make it very easy for the reader providing feedback to refer to specific pieces of specific editions of the document in question. Editing or automated generation must be easy, too. But I consider that less important than support for providing feedback. Hm. I would like to write a proposal for a documentation standard and share my experience. Anyone of the industrial members willing to donate money to finance 2 or 3 months of work? > > Don't hesitate to share your experience here, > Emmanuel > > David Li wrote: > > > Hi, > > > > I think this fall under college discussion. Should we have a > > recommendation on the documentation format standard for ObjectWeb > > projects. > While doing Chinese translation, we found that there are > > several formats used: JOnAS is using HTML, Enhydra is in Words. Both > > make the change tracking difficult, especially the translation > > tracking. One thing we found that it's much easier to find initial > > translators for documents but hard to find people to maintain the > > translation up to date. Mostly because the effort needed in tracking > > the change. That would be perfectly well adressed by my proposal. > > > > I'd like to bring up some potential solution on this: > > > > 1. DocBook seems to be good standard. However, the editor for it is a > > bit lacking unless you are using emcas. ;) > > > > 2. There is XLIFF (XML Localisation Interchange File Format) to > > argument XML based DocBook > > > > http://www.xml.com/pub/a/2004/01/07/xmltm.html > > > > 3. There are some computer translation aid tools in open source that > > support translation memory. > > > > http://www.omegat.org/ (Java based) > > > > I think it would a good idea to put together some> > recommendation/guideline of documentation for projects under ObjectWeb.Absolutely. The ability to maintain documentation in a way that brings them close to perfection over time is absolutely critical to long term success. Kind regards Claus Hirth Diplom-Informatiker Universität > > > > I am planning on doing some experiment with XMLC document. I am > > wondering if others may be interested in join this. > > > > David > > > > > >------------------------------------------------------------------------ > > > >> > > >> > > -- > Emmanuel Cecchet > > Principal architect | Chief Architect > Java technologies, Emic Networks | ObjectWeb Consortium > http://www.emicnetworks.com | http://www.objectweb.org > > > > -- > You receive this message as a subscriber of the > architecture@xxxxxxxxxxxxx mailing list. > To unsubscribe: mailto:architecture-unsubscribe@xxxxxxxxxxxxx > For general help: mailto:sympa@xxxxxxxxxxxxx?subject=help > ObjectWeb mailing lists service home page: http://www.objectweb.org/wws
| <-- Date Index --> | <-- Thread Index --> |
Powered by MHonArc.
Copyright © 1999-2005, ObjectWeb Consortium | contact | webmaster.