On Tue, 28 Dec 2010, Carsten Haitzler (The Rasterman) wrote:
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.
doxygen can export xml output. So with some xsl scripts, we can do almost
what we want. I already did some stuff about that:
http://trac.enlightenment.org/e/browser/trunk/DOCS/api/ecrin?rev=44200
Vincent
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
------------------------------------------------------------------------------
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
