On Mon, 20 Dec 2010 22:19:23 +0100 Lionel Orry <lionel.o...@gmail.com> said:
Hmmm... ok - time to chime in. 1. i'm kind of worried how any such efl manual and doxygen docs will work together. as such doxy is pretty much the best/only way to document an API (we dont use it for documenting the code - we use it to document how to use the library API). so some extent such an efl manual is already crossing paths with the doxygen docs. 2. i understand why kim was going for OO. it is actually an open format and we have good tools to work with it. i know just why. i've been here before. i've tried tex, html, and doxygen docs and frankly - the only thing that produced a nice professional OUTPUT was using OO - when you have to include diagrams, screenshots and so on in-line with the text talking about it along with code samples PLUS the output screenshots, diagrams and so on as you go, OO really begins to show why it's the better tool. all the suggestions on "asciidoc", "markdown", etc. etc. are great if all docs are is big blobs of plain undecorated text. reality is that most of our toolkits and libs focus on graphical things and as such we will need lots of graphics as mentioned above - laid out not just as single images maybe on a page with "see fig 1." in the text etc, but properly layout out and anchored to the text talking about them with multiple images in different alignments, locations, multiple per page and so on. even IF text based docs can do this - having to compile them and re-load them and go find the thing you just tried to lay out vis some cryptic text commands looks right, is a royal pain in the behind and makes life slow and cumbersome. i'd agree with kim's choice here mostly as i've been there and found these problems and ended up with the best choice being OO. that leads to #1. as such developers do hate having to fire up OO to document things. but as such the things they document are in text anyway - in the source in javadoc. what i want to know is.. how will these api docs and such a larger "efl collective" doc work together? do we perhaps want a way to be able to import the output of doxygen into such a document nicely? if so.. what about links? doxygen does generate nice linked documentation where you just mention api_call() and it's a link to the docs for that call immediately. > Damn, still attachment issues... > > On Mon, Dec 20, 2010 at 2:55 PM, Lionel Orry <lionel.o...@gmail.com> wrote: > > On Mon, Dec 20, 2010 at 2:16 PM, Thomas Gstädtner <tho...@gstaedtner.net> > > wrote: > >> 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. > >> > > > > Hi Thomas, > > > > this is pretty much the same with AsciiDoc, the text file format is > > very plain. I suggested it because I use it a lot. I did not want to > > spam the list but since you react about that (and it's a very good > > point, we should react and get the best solution), I attach an archive > > with a first draft of the manual converted to AsciiDoc format. See for > > yourself. It's missing a few formatting bits and embedded URLs > > (lacking free time, sorry) but it should show you the point. > > > > As an additional note, tools provided with or for asciidoc allow > > conversion of the original text file to html, xhtml, docbook-xml, > > LaTeX (though not maintained much), pdf via docbook and fop or dblatex > > backend, man pages (see git man pages), Slidy presentation system, and > > includes automatic syntax highlighting for all languages supported by > > pygments or GNU source-highlight, automatic diagram generation with > > ditaa or graphviz, and other goodies. Just to say that the feature > > list is, IMHO, wider than Markdown which is a very good specification > > but is mostly related to wiki formatting and thus HTML generation. > > Correct me if I'm wrong. > > > > I think we can count on feedback from Kim and others when the holidays > > period is finished. > > > > Regards, > > Lionel > > -- ------------- Codito, ergo sum - "I code, therefore I am" -------------- The Rasterman (Carsten Haitzler) ras...@rasterman.com ------------------------------------------------------------------------------ Learn how Oracle Real Application Clusters (RAC) One Node allows customers to consolidate database storage, standardize their database environment, and, should the need arise, upgrade to a full multi-node Oracle RAC database without downtime or disruption http://p.sf.net/sfu/oracle-sfdevnl _______________________________________________ enlightenment-devel mailing list enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
