1. minimanual.pdf -- comments requested

I wrote a 30 page "minimanual" the could serve as an introduction to oE.

It now needs editing and fresh eyes.

You can look or download from google docs:

https://drive.google.com/file/d/0B4wfRhusHmUbeGZudWFHOUJReGc/view?usp=sharing

_tom

new topic     » topic index » view message » categorize

2. Re: minimanual.pdf -- comments requested

Please lose the "oE" abbreviation. Every time I see it, I think someone stumped a toe. It has a very negative visual appeal - rendered in the text with the bold "E", it looks as if it was drawn by a child with a black magic marker.

I do appreciate your effort to produce a mini-manual. I'll read it carefully tonight and try to offer more substantive comments.

Ken Rhodes

new topic     » goto parent     » topic index » view message » categorize

3. Re: minimanual.pdf -- comments requested

Thanks for taking the time to take a look.

This is a version without the graphic oE:

miniman2.pdf

https://drive.google.com/file/d/0B4wfRhusHmUbSmFWcHZGVTktSjQ/view?usp=sharing

This is the creole formatted text file (46K) used to make the pdf. Anyone can edit this file directly at google docs-- miniman2.txt

https://drive.google.com/file/d/0B4wfRhusHmUbTnJneDgyd3gwQmc/view?usp=sharing

_tom

new topic     » goto parent     » topic index » view message » categorize

4. Re: minimanual.pdf -- comments requested

First, GREAT JOB! Anything that follows is an attempt to help, not criticize.

  • The mongoose logo is the wrong color.
  • The display example needs some more explanation as to why example 4 produces numbers and examples 1-3 produces text.
  • For the file IO section, st2 should have details as to what valid values are.
  • I've never installed the packages for OpenEuphoria. I've only installed from source. So, does WEE/GTK come with OpenEuphoria? If not should the minimanual make a reference as to how to get them?
  • If this manual is for 4.1 should it make mention of memstructs?
  • Should the minimanual link to the online manual for more detail on specif topics?

-xecronix

new topic     » goto parent     » topic index » view message » categorize

5. Re: minimanual.pdf -- comments requested

printf needs 3 arguments: where,format,what

Nevermind, never knew you didn't need the format argument.

From the manual: "This way, printf() always takes exactly 3 arguments, no matter how many values are to be printed."

new topic     » goto parent     » topic index » view message » categorize

6. Re: minimanual.pdf -- comments requested

That is better, but I still don't like "oE", even in plain text. I can only assume it is pronounced like a child being sick! Why not just use Euphoria? On a fresh install, can you not just double-click on wee.exw? The opening example is five times too complicated. Start with message_box("This is Euphoria","My first program",MB_OK), or won't that work on Linux? Maybe puts(1,"Welcome to programming in Euphoria") any_key(), or string name = prompt_string("Enter your name") puts(1,"Hello "&name) any_key().

I don't like "converted into a binary application". I would say something like "of course you can share the source code of your application, but then it can only be run where openEuphoria has already been installed. Use Run|Bind from the Wee menu to create a standard/standalone executable application (intro on Linux, intro.exe on Windows) that anyone can run. I'd also drop the "A compiler makes a better performing application" from the Flexible section: it screams that interpretation is horribly slow, and it's not usually the real reason for compiling (distribution is).

oE is powerful. I get it, but a) it is just bragging and b) it is not really communicating anything. Perhaps a better approach is to say something like some languages are deliberately designed to be difficult, some have so many ways of doing things they inadvertently become difficult. Euphoria keeps things simple so you can concentrate on the problem you are trying to solve, rather than add a whole new layer of problems as part of the solution. There are many freely available examples that prove keeping things simple does not have to sacrifice being powerful and flexible.

It no longer works to promote Eu as "not OOP". Rather Eu provides many of the benefits of OOP but in a much simpler way. For instance it is easy to place some data and all the routines that can operate on it in a separate file, and limit what routines (or data) can be invoked (or seen) from the rest of the application. You can easily attach any routine_id to any data; there is no need to declare a class or carefully construct a complicated hierarchy of inheritance just to get the right routines to be associated with some particular data.

The lack of an index/table of contents limits the usefulness of this severely, imo.

page 7 "que". "9/5* C +32" (wierd spacing)
Page 13: spurious !
Page 16: "& str[6]" should probably be "& str[6..6]" or better yet "& str[6..$]"
Page 22: end if/print wrong indent *2

You can get your own back by reviewing my effort, if you can handle chm format files: https://bitbucket.org/petelomax/phix then navigate source -> docs -> phix -> phix.chm

Pete

new topic     » goto parent     » topic index » view message » categorize

7. Re: minimanual.pdf -- comments requested

_tom said...

I wrote a 30 page "minimanual" the could serve as an introduction to oE.

It now needs editing and fresh eyes.

You can look or download from google docs:

https://drive.google.com/file/d/0B4wfRhusHmUbeGZudWFHOUJReGc/view?usp=sharing

That's pretty neat. Would you consider contributing this to usingEuphoria instead of distributing a PDF? I am trying to get that site back online and could use some contributions from other users. You are free to sign up and start creating wiki articles as you see fit.

-Greg

new topic     » goto parent     » topic index » view message » categorize

8. Re: minimanual.pdf -- comments requested

xecronix said...

First, GREAT JOB! Anything that follows is an attempt to help, not criticize.

Critics are welcome and needed. This is already the third re-write of the minimanual.

xecronix said...
  • The mongoose logo is the wrong color.

Does the logo have to be brown?

The eyes have gone from brown to green; this corrects the problem that on the website the eyes look red and bloodshot on some monitors. (This was an old forum request.)

Next was an experiment in changing the banner for the oE website. The idea was that reducing the number of colors makes for a cleaner banner.

At one time orange and blue was suggested as official colors. The wordmark in the manual is now brown. It's time choose colors for oE4.1

The wordmark is also using a different font. The offical workmark is using a commercial font. I am using the closest open font I could find.

Graphic artists, please help out.

xecronix said...
  • The display example needs some more explanation as to why example 4 produces numbers and examples 1-3 produces text.

Good point. Needs elaboration.

xecronix said...
  • For the file IO section, st2 should have details as to what valid values are.

Not sure which section.

xecronix said...
  • I've never installed the packages for OpenEuphoria. I've only installed from source. So, does WEE/GTK come with OpenEuphoria? If not should the minimanual make a reference as to how to get them?

This minimanual assumes that Wee is bundled with oE. That means the euGTK engine is available on a Linux install.

Another assumption is that oE will be part of a special Linux package. Puppy Linux is GTK2 so Wee will not work. Porteus Linux does work with Wee. The odd thing about Porteus Linux is that the pdf reader does not read all of the graphics in my minimanual. I think a small download and quick burn to a USB drive will make for compelling demonstration.

xecronix said...
  • If this manual is for 4.1 should it make mention of memstructs?

It doesn't help that I don't understand memstructs. But, the idea was to go to 25-30 pages maximum.

Would memstructs "scare off" someone who is virtually new to programming and sees oE for the first time? Does this suggest an advanced minimanual targeted to advanced users?

xecronix said...
  • Should the minimanual link to the online manual for more detail on specif topics?

I'm not sure that the toolchain Creole|Wkhtmltopdf can be made to link between files.

I now mention the full Reference Manual in the first paragraph. The Library Sampler chapter also refers to the full Reference manual.

new topic     » goto parent     » topic index » view message » categorize

9. Re: minimanual.pdf -- comments requested

Notice that I am using print and printf (instead of the traditional print and puts).

The full manual needs a re-write. The minimanual is my first step in getting there.

new topic     » goto parent     » topic index » view message » categorize

10. Re: minimanual.pdf -- comments requested

ghaberek said...

That's pretty neat. Would you consider contributing this to usingEuphoria instead of distributing a PDF? I am trying to get that site back online and could use some contributions from other users. You are free to sign up and start creating wiki articles as you see fit.

-Greg

We can do a copy paste to your site. The more exposure the better.

_tom

new topic     » goto parent     » topic index » view message » categorize

11. Re: minimanual.pdf -- comments requested

petelomax said...

Pete

Lots of good points. I will take the time to think them all through.

Documentation in chm is a problem. Even Microsoft has deprecated this format because it has a security flaw. Making a chm in Linux is painful. Reading a chm in Linux is doable.

I have settled on Creole|Wkhtmltopdf since the fancy external tools are too much work or not Euphoria based.

_tom

The challenge is to convert you, and everyone else, to Linux.

new topic     » goto parent     » topic index » view message » categorize

12. Re: minimanual.pdf -- comments requested

evanmars said...

printf needs 3 arguments: where,format,what

Nevermind, never knew you didn't need the format argument.

From the manual: "This way, printf() always takes exactly 3 arguments, no matter how many values are to be printed."

That says the manual is wrong. RTFM means "redact the fine manual"

new topic     » goto parent     » topic index » view message » categorize

13. Re: minimanual.pdf -- comments requested

_tom said...
xecronix said...
  • If this manual is for 4.1 should it make mention of memstructs?

It doesn't help that I don't understand memstructs. But, the idea was to go to 25-30 pages maximum.

Is memstructs in 4.1 yet? I think the concensus was that there was no reason to leave it out, but I haven't seen any commits suggesting that it has actually put into the mainline yet.

mattlewis logged in less than an hour ago. As the original author of this feature, it'd be really nice to hear his thoughts about this.

_tom said...

Would memstructs "scare off" someone who is virtually new to programming and sees oE for the first time? Does this suggest an advanced minimanual targeted to advanced users?

Memstructs is mostly for interfacing to C and other external libraries. This has generally been considered an 'advanced' topic in the past, but at the same time I can see plently of newbies anting to (for example) interface Euphoria with their favorite game library or something.

A newbie/beginner oriented memstructs guide would not be a bad thing.


Forked into: mattlewis? Has anyone heard from him on the memstructs issue yet?

new topic     » goto parent     » topic index » view message » categorize

14. Re: minimanual.pdf -- comments requested

_tom said...

Does the logo have to be brown?

Absolutely not! The logo can be whatever color you want. The reason to keep it brown is all about brand recognition and first impressions.

_tom said...
xecronix said...
  • For the file IO section, st2 should have details as to what valid values are.

Not sure which section.

Maybe consider adding more details about st2?

fn = open(st1, st2) -- open file name st1 with mode st2 
                    -- e.g. "r" for read 
_tom said...
xecronix said...
  • If this manual is for 4.1 should it make mention of memstructs?

It doesn't help that I don't understand memstructs. But, the idea was to go to 25-30 pages maximum. Would memstructs "scare off" someone who is virtually new to programming and sees oE for the first time? Does this suggest an advanced minimanual targeted to advanced users?

This feature is a big deal in my opinion. Some introduction I think is warranted because the feature helps OpenEuphoria standout from other high level languages.

new topic     » goto parent     » topic index » view message » categorize

15. Re: minimanual.pdf -- comments requested

_tom said...

The eyes have gone from brown to green; this corrects the problem that on the website the eyes look red and bloodshot on some monitors. (This was an old forum request.)

I didn't realize the eyes were not supposed to be red. In the story, his eyes turned red when he was battling the snakes. Because a mongoose is a snake killer, I thought the red eyes were appropriate.

new topic     » goto parent     » topic index » view message » categorize

16. Re: minimanual.pdf -- comments requested

In general, all of your comments are valuable and will end up fixing the re-write of the MiniManual.

petelomax said...

On a fresh install, can you not just double-click on wee.exw?

The Linux (bound|compiled) version does not open a terminal to execute a program. If you launch WEE from a terminal then at least you have that terminal to display output. Got to complain about this...

petelomax said...

You can easily attach any routine_id to any data; there is no need to declare a class or carefully construct a complicated hierarchy of inheritance just to get the right routines to be associated with some particular data.

I have tried to come up with a short demo to show this:

First an included file: temp.e

namespace temp 
 
export atom New, Set, Get, Show, Convert   -- actions 
export enum Temp, Units                    -- data-objects 
export enum C, F                           -- fixed values 
 
-- these subroutines are hidden from the end user 
 
function set( object entity, integer item, object value ) 
    entity[2][item] = value 
    return entity 
end function 
    Set = routine_id( "set" ) 
 
function get( object entity, integer item ) 
    return entity[2][item] 
end function 
    Get = routine_id( "get" ) 
     
procedure show( object entity, integer item ) 
        if item = 1 then 
            printf(1, " %g", entity[2][1] ) 
        else 
            printf(1, entity[2][2] ) 
        end if 
end procedure 
    Show = routine_id( "show" ) 
 
 
function convert( object entity ) 
    if entity[2][2] = C then 
        entity[2][1] = entity[2][1] * 9/5 + 32 
        entity[2][2] = F 
    else 
        entity[2][1] = (entity[2][1] - 32 ) * 5/9 
        entity[2][2] = C 
    end if 
    return entity 
end function 
    Convert = routine_id( "convert" ) 
 
function new() 
    return { {New,Set,Get,Show,Convert}, {Temp,Units} } 
end function 
    New = routine_id( "new" ) 
 
-- this one function calls the desired subroutine when needed 
export function T( object action, object entity = "", integer item = 0 , object value = "") 
    if action = New then 
        return call_func( New, {} ) 
    elsif action = Set then 
        return call_func( Set, { entity, item, value } ) 
    elsif action = Get then 
        return entity[2][item] 
    elsif action = Show then 
        if item = 1 then 
            printf(1, " %g", entity[2][1] ) 
        elsif item = 2 then  
            if entity[2][2] = C then 
                printf(1, " oC" ) 
            else 
                printf(1, " oF" ) 
            end if 
        end if 
    elsif action = Convert then 
        return call_func( Convert, {entity} ) 
    end if 
    return 0 
end function 

Then the main file: hotness.ex

include temp.e 
 
printf(1, "First entity is inside a room\n" ) 
    sequence room = T(New) 
        room = T(Set,room,Temp,15) 
        room = T(Set,room,Units,C) 
    T(Show,room,Temp) T(Show,room,Units) 
        room = T(Convert, room ) 
    printf(1, "\n after temperature conversion\n" ) 
    T(Show,room,Temp) T(Show,room,Units) 
 
printf(1, "\nSecond entity is outside the building\n" ) 
    sequence outside = T(New) 
        outside = T(Set,outside,Temp,-5) 
        outside = T(Set,outside,Units,C) 
    T(Show,outside,Temp) T(Show,outside,Units) 

Ideas for short demos are welcome.

petelomax said...

The lack of an index/table of contents limits the usefulness of this severely, imo.

How are you looking at the PDF? On Linux Mint the default viewer shows a "table of contents" as a side pane automatically--no work required.

An index is going to take some work, but I can try.

Thanks, _tom

new topic     » goto parent     » topic index » view message » categorize

17. Re: minimanual.pdf -- comments requested

I realize not all forks will get acceptance, but memstruct is a fork. I would document what is in the main branch, and not add memstructs into an introductory manual of Euphoria.

new topic     » goto parent     » topic index » view message » categorize

18. Re: minimanual.pdf -- comments requested

SDPringle said...

I realize not all forks will get acceptance, but memstruct is a fork. I would document what is in the main branch, and not add memstructs into an introductory manual of Euphoria.

Alternatively, we could merge memstructs into the main branch.

I haven't heard any objections to this idea, other than my own.

new topic     » goto parent     » topic index » view message » categorize

19. Re: minimanual.pdf -- comments requested

You could count my objection here. I am finding bugs faster than they are getting fixed in 4.0.

new topic     » goto parent     » topic index » view message » categorize

20. Re: minimanual.pdf -- comments requested

SDPringle said...

You could count my objection here. I am finding bugs faster than they are getting fixed in 4.0.

I'm surprised. The 4.0.x line shouldn't have changed all that much since the last release....

new topic     » goto parent     » topic index » view message » categorize

21. Re: minimanual.pdf -- comments requested

jimcbrown said...
SDPringle said...

You could count my objection here. I am finding bugs faster than they are getting fixed in 4.0.

I'm surprised. The 4.0.x line shouldn't have changed all that much since the last release....

In real life, for every bug you see in your house, there are nine you don't see. You know software is like this with very few exceptions. Features are analogous to crumbs, they bring in more bugs. Bugs can hide in code for years. In particular, in file_copy the code has not been changed since its initial release, yet there is a bug involving eating file handles.

S.D. Pringle

new topic     » goto parent     » topic index » view message » categorize

22. Re: minimanual.pdf -- comments requested

SDPringle said...
jimcbrown said...
SDPringle said...

You could count my objection here. I am finding bugs faster than they are getting fixed in 4.0.

I'm surprised. The 4.0.x line shouldn't have changed all that much since the last release....

In real life, for every bug you see in your house, there are nine you don't see. You know software is like this with very few exceptions. Features are analogous to crumbs, they bring in more bugs. Bugs can hide in code for years. In particular, in file_copy the code has not been changed since its initial release, yet there is a bug involving eating file handles.

S.D. Pringle

Sounds like a reason to drop 4.0.6 and focus all our efforts on 4.1.0, instead of having to find and fix the same bugs in two codebases.

new topic     » goto parent     » topic index » view message » categorize

23. Re: minimanual.pdf -- comments requested

jimcbrown said...

Sounds like a reason to drop 4.0.6 and focus all our efforts on 4.1.0, instead of having to find and fix the same bugs in two codebases.

Jim, you really have to lock your computer when you walk away from the keyboard. Look at the kind of ignorant things get posted in your name.

new topic     » goto parent     » topic index » view message » categorize

24. Re: minimanual.pdf -- comments requested

SDPringle said...
jimcbrown said...

Sounds like a reason to drop 4.0.6 and focus all our efforts on 4.1.0, instead of having to find and fix the same bugs in two codebases.

Jim, you really have to lock your computer when you walk away from the keyboard. Look at the kind of ignorant things get posted in your name.

I really am leaning towards the view that we should focus all efforts into 4.1.0 and not into 4.0.6.


Forked into: 4.0 vs. 4.1

new topic     » goto parent     » topic index » view message » categorize

Search



Quick Links

User menu

Not signed in.

Misc Menu