On Wed, 30 Oct 2013 14:49:27 -0400 Robert Heller <[email protected]> said:
> At Wed, 30 Oct 2013 13:43:45 -0400 Enlightenment users discussion & support > <[email protected]> wrote: > > > > > On Wed, Oct 30, 2013 at 1:02 PM, Robert Heller <[email protected]> wrote: > > > > > At Wed, 30 Oct 2013 12:09:52 -0400 Enlightenment users discussion & > > > support <[email protected]> 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, http://docs.enlightenment.org/stable/edje/Edje_8h.html#a1d9a921c4e78fd9a2879ae8a7b7c0bc9 as a reference efl is pretty good. it tells you precisely what swalllow does. that's pretty accurate in that reference too. > 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. what you are lacking is simply experience with a codebase AND a whole toolkit that is rather large and complex. from what you write here you are jumping into something relatively complex at the start without having masttered the basics. > 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. i see a rather large set of text describing swallowing an object above. to me that text is already rather verbose. :) > 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.) i think that is the key here. you have strayed into an entirely foreign land. while c itself is familiar - everything else is utterly strange and foreign. trust me - knowing c or c++ gets you maybe 0.5% of the way there. the other 99.5% if the toolkit and e's code itself (for your situation). and that means understanding a very large set of complex interactions between a vast set of different libraires, api's and abstractions. no document is ever goign to sensibly cover ALL of that. if i had to hazard a guess as to a document that might, it'd probably be many times the size of war and peace (remember that it has to cover not just the expplicit intents of specific apis but how you would use several api's in combination to manipulate a state machine and thus manipulate the flow of events, logic, display and so on as a result - and the numebr of permutations and combinations of this is just mind-boggling) and you'd instead be complaining about how it's impossible to learn efl because you can never finish reading all the documentation. a think to take home here is that a vast amount of efl is not "immediate mode" api. you don't fire and forget. you don't call and something is done and returns a result (or draws it ot the screen). it sets up some element of a larger scene or graph. it sets up a function to be called when a an event happens in the future. it manipulates the scene itself re-arranging elements of the graph and their properties (which affect flow). to describe all of that succinctly is a huge task. my BEST advice is not to give up, but to ... be more modest in your initial forays and do something very simple and see how it wobbles. ask questions. don't fall into a pit of despair and grumbling. start small, then ask "so.. i want to ultimately make a new menu - but for now just having a box appear on screen will be good. i've got this here but i just see a single pixel - why?" (and then show us your code). :) then go back and forth. lets take that simple red solid box and then let's get it sized nicely. let's have you seeing events on the red rectangle. then track them. then do some fun stuff - make a yellow rectangle follow the mouse as it mouses over. then let's add in some keyboard controls of the yellow rect and then let's cleanly pop down the box like the menu does. then we can go to the next stage... make that red+yellow box styled (use edje). so they now look and feel the part. next step is that you don't want to manually size the box but want it to adapt to the size of its content (ie wrap around it tightly)... then start with simple content, then expand that content to more complex content, etc. etc. get the idea? :) trust me on this. do it this way and efl and e will beocme insanely less mysterious and you will maybe suddenly "get" things that were there in docs already - or in examples. or in existing code. suddenly the code will make sense without docs. it will tell a story and flow. you're a stranger in a strange land. find a local bar - make some friends. share some beers. talk to the locals. hear some stories, ask questions... we're not an unfriendly bunch (most of the time) > > 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 learned c this way - exmaples like the above speak to me and say.. "what if i swapped 1 and 10... oh wait. that doesn't work. hmm i see a ++. let's try reversing that to -- as - is reverse of plus?"... things start to work.. but help.. it goes below 0 to negatives (when run)... wait... hmm <= .. thats a math compariosn. if going up that works and then fails when we hit 10. ok - it must be abe to do the rfers so make it i >= 0 .... bingo! reverse!. i guess int i declares a variable of "int".... which i guess is short for integer... and the stuff i see on screen mys be because of printf... as i know print from basic printed stuff out... and there is i - the thin git prints.. what's %d? thats odd. hmm ... oh look man printf works! <read.... 30 mins later> oh it has this %XXX system where XXX can be some letter representing a number. d is a decimal. why do people insist on d - there is %i? it makes so much more sense as i... is short for int... integer... much cleaner!". thats how i learned c. and where needed reference docs. do the rest by inference. :) > > > > 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 < > > > > [email protected]> 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 > > > > > [email protected] > > > > > https://lists.sourceforge.net/lists/listinfo/enlightenment-users > > > > > > > > > > > > > > > > > > > > > > > > -- > > > Robert Heller -- 978-544-6933 / [email protected] > > > 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 > > > [email protected] > > > https://lists.sourceforge.net/lists/listinfo/enlightenment-users > > > > > > > > > > > > -- > Robert Heller -- 978-544-6933 / [email protected] > Deepwoods Software -- http://www.deepsoft.com/ > () ascii ribbon campaign -- against html e-mail > /\ www.asciiribbon.org -- against proprietary attachments > > > > -- ------------- Codito, ergo sum - "I code, therefore I am" -------------- The Rasterman (Carsten Haitzler) [email protected] ------------------------------------------------------------------------------ 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 [email protected] https://lists.sourceforge.net/lists/listinfo/enlightenment-users
