Hi, I understand Lyx as being a layer over LaTEX. Maybe "just" a GUI. What I don't like with LaTEX is, by default, it produces document with quite ugly police, old-style HTML, etc... Every time I open pjal manual, my first thoughts are: "it's ugly, I don't want to read, looks old, looks like a thesis"... But typography is just perfect. But not sexy.
About ASCIIDOC, my recent tries tend to show it probably will be too complicated. Dealing with tables sometime works, sometime won't. I may give another try with Docbook, being the reference in documentation writing (with LaTEX). I've found this GUI: http://www.xmlmind.com/xmleditor/. Works nice, available on all platforms (java). Docbook also requires some customization, but we may be able to take one and adapt it to jallib. Ex: gnome project has its doc written with docbook, we could use their stylesheets. Now it may seem a little bit overkill for a project like jallib (like SVN was overkill ?...). Should we go this way ? I tend to say "yes", but I also know it won't succeed without agreement of all of us. Please advise ! Cheers, Seb -- Sébastien Lelong http://www.sirloon.net http://sirbot.org 2009/8/23 Joep Suijs <[email protected]> > > 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 -~----------~----~----~----~------~----~------~--~---
