At Wed, 30 Oct 2013 13:43:45 -0400 Enlightenment users discussion & support
<enlightenment-us...@lists.sourceforge.net> wrote:
>
> On Wed, Oct 30, 2013 at 1:02 PM, Robert Heller <hel...@deepsoft.com> wrote:
>
> > At Wed, 30 Oct 2013 12:09:52 -0400 Enlightenment users discussion &
> > support <enlightenment-us...@lists.sourceforge.net> wrote:
> >
> > >
> > > Hi,
> > >
> > > Just to chime in with 10c's worth.
> > >
> > > This is my personal preference, working examples atleast as a base works
> > > for me ( examples as in code )... Documentaions words are ok for the
> > nitty
> > > gritty but not as a substitute for a good example.
> > >
> > > If you look at most tech books, the question is how many of us read any
> > of
> > > them cover to cover?.
> >
> > But *I* do find them *very* useful, even if I don't read them cover to
> > cover.
> > Often reading a page here or there (or even a whole section) if *very*
> > useful,
> > and *not* because of the included examples. And an *important* part of
> > any
> > tech book is its index and/or table of contents -- either/both of these
> > gets
> > me to the page or section I need to read.
> >
>
>
> Fair comment,
>
>
>
> >
> > >
> > > Probably near none at all, so really for me thats enough said.
> > >
> >
> > The main problem with documentation-by-example is what happens when there
> > isn't an example that covers the question at hand? Or (worse) when the
> > example's name or title does not fully suggest or explain what it is an
> > example of. Also, sometimes it is critical when looking at examples that
> > there
> > is some explaination of the concepts involved. Examples alone can never
> > really
> > explain how to do things, if the *underlying* concepts are not either
> > known or
> > else explained. For example, what does 'swallow' mean in the context of
> > edje?
> > The code in e_menu is using this, but I have no clue as to what is going on
> > and the swallow example does not really *explain* what is going on, it just
> > shows you how to use it, without explaining why you would do it or what
> > its purpose is. Somehow, I don't think it has anything to do with eating or
> > birds (but maybe it does?).
> >
> >
> I think at this stage, perhaps it would be good to take the opportunity to
> take a look at the documentation available.
I have, and it is not *useful* -- there isn't any explaination of what is
really going on. The 'Swallow Example' does not really explain what
"edje_object_part_swallow(edje_obj, "part_one", rect);" does. There does not
seem to be a *useful* explaination of what edje_object_part_swallow() does,
why you should use it (or not). It is there in the code I copied from
e_menu.c, but I have no clue whether or not it is or is the reason I am not
seeing anything useful on the screen. Or if I need to add something to the
.edc file or what I should add to the .edc file.
Bascially, *none* of the edje_* *C* functions are explained in any detail, the
examples, just show their use, within the context of the given examples, but
without the explaination needed to extrapolate to other contexts.
Maybe the problem is that *I* have not absorbed the 'culture' behind the E17
project. I have not worked with a *C* based GUI API in some time (the last C
based GUI API I worked with was Motif). Most of the GUI programming I have
been doing for the past 20+ years has been with Tcl/Tk. (I have been coding
in C and C++ all though that time, but the C code has not been GUI coding --
the C and C++ code ends up as a loadable shared library loaded into a Tcl/Tk
main program that implements the GUI, if any.)
>
> Alot of these comments though have been made on howto's, in that they
> usually only made sense after you have completed the task yourself.
I am not sure that this really makes sense for anything other then rote tasks.
And then one may end up only learning the rote task without the understanding
how to extend the task to other contexts. That is one can learn that to count
to 10 in C one does:
int i;
for (i=1, i<=10; i++) printf("%d\n",i);
but without additional information it is not clear how to count backwards or
to only count even numbers (the above code does not explain how to do either
of these things). One cannot fully learn how to generally write C programs
from random little examples like the above. A proper reference book for the C
language *has* have more in it besides a dozzen or so examples like the above.
Otherwise it is not really useful.
>
> I would not doubt that the current documents could use some work. I am not
> actually 100% on whom would be doing the task. Possibly the person who
> wrote / contributed to the module in question.
>
> Would be cool to find a common agreement here.
>
> Nige
>
>
> >
> > > Nige
> > >
> > > Disclaimer: This is my personal belief as stated.
> > >
> > >
> > > On Wed, Oct 30, 2013 at 11:58 AM, VinÃcius dos Santos Oliveira <
> > > vini.ipsma...@gmail.com> wrote:
> > >
> > > > Em Qui, 2013-10-31 Ã s 00:48 +0900, Carsten Haitzler escreveu:
> > > >
> > > > > this is simply a matter of time. spend 1hr adding a feature someone
> > > > > wants, or 1
> > > > > hr writing docs.
> > > >
> > > >
> > > > Documentation is a feature too.
> > > >
> > > >
> > > > > i personally use docs as reference only - i ALWAYS use example
> > > > > codee. nothing to do with java - it simply is faster, easier and more
> > > > > practical.
> > > >
> > > >
> > > > Documentation can include snippets.
> > > >
> > > >
> > > > > i read unix man pages to begin with and frankly they told me very
> > > > > little at all. a whole tonne of words for very little use. examples
> > > > > taught me
> > > > > 100x more in the same amount of effort with docs backing it up as
> > > > > reference.
> > > >
> > > >
> > > > Comparing manpages with HTML rich (or even PDFs) docs.
> > > >
> > > >
> > > > * Manpages cannot have images (maybe with Terminology this is no
> > > > longer true) and for a GUI toolkit this is kind of a must.
> > > > * Manpages don't have an easily browsable content (like HTML)
> > have
> > > >
> > > > * Summary
> > > > * Detailed description and extra sections
> > > > * Extra pages (not directly related to one class only)
> > > > * A small text for each function
> > > >
> > > >
> > > >
> > > > > as such most of efl does have docs. they are not voluminous essays.
> > > > > again - a
> > > > > matter of time. if you wish to contribute by writing voluminous
> > docs..
> > > > > go for
> > > > > it. :)
> > > >
> > > >
> > > > The magic of open source. :)
> > > >
> > > >
> > > > --
> > > > VinÃcius dos Santos Oliveira
> > > > https://about.me/vinipsmaker
> > > >
> > > >
> > > >
> > ------------------------------------------------------------------------------
> > > > Android is increasing in popularity, but the open development platform
> > that
> > > > developers love is also attractive to malware creators. Download this
> > white
> > > > paper to learn more about secure code signing practices that can help
> > keep
> > > > Android apps secure.
> > > >
> > http://pubads.g.doubleclick.net/gampad/clk?id=65839951&iu=/4140/ostg.clktrk
> > > > _______________________________________________
> > > > enlightenment-users mailing list
> > > > enlightenment-us...@lists.sourceforge.net
> > > > https://lists.sourceforge.net/lists/listinfo/enlightenment-users
> > > >
> > > >
> > >
> > >
> >
> > --
> > Robert Heller -- 978-544-6933 / hel...@deepsoft.com
> > Deepwoods Software -- http://www.deepsoft.com/
> > () ascii ribbon campaign -- against html e-mail
> > /\ www.asciiribbon.org -- against proprietary attachments
> >
> >
> >
> >
> >
> >
> > ------------------------------------------------------------------------------
> > Android is increasing in popularity, but the open development platform that
> > developers love is also attractive to malware creators. Download this white
> > paper to learn more about secure code signing practices that can help keep
> > Android apps secure.
> > http://pubads.g.doubleclick.net/gampad/clk?id=65839951&iu=/4140/ostg.clktrk
> > _______________________________________________
> > enlightenment-users mailing list
> > enlightenment-us...@lists.sourceforge.net
> > https://lists.sourceforge.net/lists/listinfo/enlightenment-users
> >
> >
>
>
--
Robert Heller -- 978-544-6933 / hel...@deepsoft.com
Deepwoods Software -- http://www.deepsoft.com/
() ascii ribbon campaign -- against html e-mail
/\ www.asciiribbon.org -- against proprietary attachments
------------------------------------------------------------------------------
Android is increasing in popularity, but the open development platform that
developers love is also attractive to malware creators. Download this white
paper to learn more about secure code signing practices that can help keep
Android apps secure.
http://pubads.g.doubleclick.net/gampad/clk?id=65839951&iu=/4140/ostg.clktrk
_______________________________________________
enlightenment-devel mailing list
enlightenment-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
