maybe openoffice is an altenative in the way it is open source. ;ynx should also be on the list. The pjal doc is written in it. ( gave it a try but until now, i find it hard to use and can't find some functions (although i can't imagine they are not supported). Joep
2009/8/21, Sebastien Lelong <[email protected]>: > Hi, > > OpenOffice could be an option but have the same problem as Word: > > 1. personal taste: same issue as Word, I don't like triggering a big tool > just to fix few typos for instance. > 2. consistent output: many people (I hope...) will enrich this document. > How to make sure we'll have the same consistent output with tools like OO or > Word ? Correctly use styles ? Will this be enough ? Will we be able to keep > a professional (or high quality) looking documentation ? > 3. important point is to be able to put in under SVN so we can see > differences between two versions, what's been added in the local copy, ... > just like code. Word as OO docs are imported as binary format, and SVN won't > show any diff on it (just an "something has changed..."). How to make sure > someone didn't change something unexpectidely ? > 4. how to (easily) script documentation processing ? When original doc > source is in format like LaTEX, Docbook or ASCIIDOC, you can make it built, > checked and produce output automatically. > > > Cheers, > Seb > > > >> >> I don't understand why not OpenOffice.org doc? It can export also in >> HTML/XHTML, PDF, MediaWiki txt, BibTeX, LaTeX 2e and is ported on all >> operating systems. It can save also in MS Word format, and many >> others. >> >> ------------------ >> Vasi (http://moriscanet.blogspot.com) >> >> On Aug 21, 3:52 pm, Sebastien Lelong <[email protected]> >> wrote: >> > Hi guys, >> > >> > You've probably heard about documentation issues these last weeks. Toon >> and >> > Joep started to write a "jalv2 & jallib - an introduction" document. As >> > a >> > Word file. First drafts clearly show interests for this kind of >> > documentation, but there are lots of other source of information which >> could >> > be used to enrich it, like some blog posts. >> > >> > Maybe it's time to normalize this and provide a common way to produce >> this >> > kind of documentation. One important aspect is it must be under SVN. Not >> > only the file, but also the content. SVN should be able to deal with >> > documentation as it does for the code, namely documentation should be in >> > text format. It also shouldn't a pain fixing just a typo, so not having >> > a >> > turn on Word would really make things easier (IMO). Finally, one source >> (one >> > file) must be able to produce different format, like HTML, PDF, ASCII, >> > PS >> or >> > the like. And this whole thing must be scripted, so it's part of the >> > development process (hopefully as a quality requirement). >> > >> > So... this raises the question: "which tool ?". Professional >> documentation >> > writer, if any here, may help. I'm not a doc write, but used LaTEX, >> Docbook >> > and ReST a litlle. Recently, I had a look at Asciidoc, and it seems >> > quite >> a >> > nice choice (http://www.methods.co.nz/asciidoc/). It allows to have a >> > readable ASCII doc, and produce very nice HTML, XHTML, PDf, etc, ... and >> > intermediary format like Docbook. Highly configurable too. >> > >> > Ideally one would write his doc in his format, integrate it to the main >> book >> > ("an introduction") but also upload it to our upcoming jalv2 website. >> > >> > I think I'll try to convert current Toon&Joep's document and let you >> > have >> a >> > look at the results. In the meantime, if you have suggestions and/or >> > objections... (and most importantly, will you agree to invest some time >> on >> > this kind of tool ?) >> > >> > Cheers, >> > Seb >> > -- >> > Sébastien Lelonghttp://www.sirloon.nethttp://sirbot.org >> > >> > > > > --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "jallib" group. To post to this group, send email to [email protected] To unsubscribe from this group, send email to [email protected] For more options, visit this group at http://groups.google.com/group/jallib?hl=en -~----------~----~----~----~------~----~------~--~---
