On Fri, Dec 17, 2010 at 22:13, Lionel Orry <lionel.o...@gmail.com> wrote: > Kim Lester <kim <at> dfusion.com.au> writes: > >> >> All, >> >> A few notes and two requests (marked *** ) >> >> [...] >> Incidentally I wrote this in OO simply because writing either doxygen or xml >> is not a good way to evolve a >> large complex document. I've written large docs in TeX with vi before and >> whilst it is good for producing >> consistent output it sucks from the point of view of massive cut/pastes and >> "creative flow". Eventually >> this doc _could_ be converted to xml or tex or something but not just now. >> > > Hi Kim, > > I've been using TeX for a long time so don't get me wrong, but there exist now > new formats that encourage the creative flow, as you say, by abstracting the > formatting stuff, and that provide the source as a text file (devs love text > files... They really do. They hate binary stuff apart from edje and eet files > of course.), so the manual could also be versioned on the official svn repo. > It could even be provided as README-like files. > > Such formats include AsciiDoc, RestructuredText, Textile, Markdown, etc. > > I am personally using AsciiDoc for, well... nearly everything I write when > it's a bit technical. If you think it's a good idea to see what it looks like, > give me a hour or two to convert your doc tomorrow and I'll show you the > result. > > I'm not the right person to talk about the content though, but I appreciate > the effort very much. Good doc makes enjoyable software. > > -Lionel
I fully agree. I highly suggest to look into Markdown. While having a few flaws in layouting hat other systems might not share, it still has a ton of possibilities to format text while being extremely simple and especially plaintext-friendly. Markdown format just looks like plain textfile format, just like any readme-file and so on uses anyway, so vi or emacs is just fine, and yet you can produce appealing online documentations with CSS. ------------------------------------------------------------------------------ Lotusphere 2011 Register now for Lotusphere 2011 and learn how to connect the dots, take your collaborative environment to the next level, and enter the era of Social Business. http://p.sf.net/sfu/lotusphere-d2d _______________________________________________ enlightenment-devel mailing list enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel