Gideros Reference Manual

john26

Dear All

I am thinking of publishing a new physical book on Gideros, namely a Gideros Reference Manual and I would like to gauge interest in this. The manual will contain a description of all of Gideros's 500+ API functions including all plugins and Lua standard libraries. The information is the same as you can find here on this site (in the API reference) but obviously set in a nice book form and with everything gathered in one place.

I prepared a version of this book in 2014 as a reward for a Kickstarter campaign but this version will need to be updated as many more features have been added to Gideros. So it will be the "second edition". Currently the book is 460 pages long nominally on A4 paper (though the paper size could be shrunk a fair bit without compromising readability).

I attach some samples from the book as it exists so far.

So I would like your comments! In particular:

Would this book interest you?
How much would you want to pay for such a book?
Do you prefer a printed book or e-book?
What do you think of the formatting presented in the samples?

Many thanks for your advice on this!

antix

@John26 those are very nice. I always thought the documentation could be way better. Just looking at other SDK's there are many other ways the information could be better presented.

My only hesitation on purchasing something like this is the speed at which Gideros is moving forwards. Personally I feel as more new things are added I would be having to go back to the online documentation still, which kind of defeats the purpose of having a book that contains everything. If they shared the same format that would be grand.

Maybe if it were an E-Book with free updates it might work (for me at least)

As for the format and such, it's pretty good.
- I would get rid of the "available since" lines because I feel they are irrelevant when looking up a function/params/syntax..
- The main heading (Chapter 81) is cool but I'm not fond of 81.1, 81.2, etc. Maybe just a horizontal line that separates the different functions?

It brings back fond memories of flicking through my Amiga Hardware Reference Manuals :bz

SinisterSoft

I prefer paper books. They are good for presents too.

Apollo14

Gotta be a great book! I want it bad!

Please publish ebook together with paper version. Some users like me prefer to avoid spending extra money on paper&delivery, and postal service is very slow in poor countries, it takes up to 2-3 months to get paper book from amazon or other us/eu shop.

SinisterSoft

The best tech books I ever read where the (official) Amiga reference manuals - especially the hardware manual. Download them (pdf) then base it on those and it's a winner.

john26

Thanks very much for the comments. @antix, yes, I think you are right subsection numbering is overkill and it's probably better to just number chapters. It does mean cross-referencing is less specific, so I can only refer to the correct chapter but perhaps that is ok (note: there are no hyperlinks in a printed book so you have to have some numbering)

I'm not sure how important "available since" is I guess most people will be using a version of Gideros which is newer than the manual to it's kind of irrelevant as all features are available. What do other people think?

@SinisterSoft, Yes, I also prefer a hefty physical book next to me when I am programming, it's quicker to flick through and means I don't have to use up precious screen area.

I'd like to hear more from people who got the book as a Kickstarter reward...

antix

@john26 I always used sticky notes to mark important parts of my hard copy books. Even then some of them I used to chop up into chapter sized sub-books (graphics, sound, etc) because I found I was always looking at one chapter more than the others

For more screen real estate... get another monitor :bz

totebo

I like the idea of a "real" book, although I don't personally use books for reference. I tend to think the online version is quicker (and up to date).

Maybe one option would be a new Gideros book (Arturs' is a bit dated), which includes a reference?

SinisterSoft

I think an set of books would be good:

API
Lua (Our flavour)
Beginners (everyday gfx and sfx)
Shaders
LiquidFun
Monitisation (ads and payments)

etc...

hgy29

I find it easier to lookup the reference manual online. To me a book would more useful if it had two parts: a guide/tutorial part with examples, how-to's, pictures and explanations about several aspects of gideros, and a second part with the API reference itself.

keszegh

i also prefer the online manual. we should put more energy to make it up-to-date. e.g. some plugins are missing like require, there are errors like the li's on http://docs.giderosmobile.com/reference/gideros/TextureBase#TextureBase
and other small errors like on http://docs.giderosmobile.com/reference/gideros/Mesh/setTextureCoordinateArray#Mesh:setTextureCoordinateArray there is color written instead of texture coordinate and same as above is actually the SAME as above.

antix

I really don't find the online documentation very friendly. Not being able to expand a bunch of sections at the same time is hyper frustrating, as such I venture there very rarely. Many other SDKs have way better documentation systems. Just a standard tree that you can expand and collapse would be far better IMHO.

@hgy29 I'm a bit the same and why I chop my books up into logical sections. @john26 please leave blank pages between chapters so it's easy to dismember please :bz

john26

Thanks for all your comments! I can see most people prefer to use online documentation for the API so perhaps a printed text is not really essential. @SinisterSoft, I completely agree with the list of books you have written above but who to write them all? Here's who I think:

Beginners (everyday gfx and sfx)
@ar2rsawseen perhaps could update his book to a second edition to take account of 3D graphics and new Sprites classes like Path2D and Pixel. He already has a publisher which is a bonus.

Shaders
@hgy29 coded all this up so is best placed to write a book on the subject. This is a complex topic definitely worthy of a book in itself. I'd be happy to proofread the English if needed...

Monetisation (ads and payments)
I'd pay for this book! The whole subject of ads, facebook, achievements etc is very complex and (to me) mysterious with no systematic documentation on basic concepts. You really need to trawl this forum to get an introduction (it's kind of assumed everyone has a compsci degree and knows all about online shopping concepts, internet protocols etc). @SinisterSoft I think you are well placed to write this.

The others you mention (Lua extensions and Liquidfun) IMO don't need a book to themselves.

oleg

a paper book can be bought and given to the school.
as an promotional event

SinisterSoft

I think books are an ideal present for someone.

Ninjadoodle

Hi John26

I LOVE books, but I kinda have to agree with some of the others. With the ever improving Gideros Studio, I wonder whether it would be better to have an online resource that can be updated when changes happen.

I mean, this could also be monetised ...

- members only sections
- access to downloads
- patreon
- ads

etc.

Again, I love books, but like some of the others have said - I find it easier to just open a webpage on a second monitor + there is the updates issue.

Just my thoughts

MobAmuse

I've looked at the above and all comments to date.

I think the documentation is lacking given gideros has been updated so many times and many features I for one skip, as I have no idea how to use them in the past.

A printed book would be superb and hopefully would contain some tutorials for both noobs and even more seasoned users perhaps.

I like the idea though of being able to get at the book online and also in print so one can crib sheet code clips from the tutorials without having to type in much.

I would certainly pay for a printed book and I think the online version should come free along with the purchase of the printed version.

Personally I also think gideros has now evolved more than enough features for most (perhaps with the exception of textured 3D shapes which is damn hard to actually do currently) and a book would cement that at last.

Alongside the book gideros really only needs work when there are known bugs to fix and new hardware that breaks it's end functions perhaps.

All very well adding new features in endless fashion, but as I said doing that will soon break any book and a lot of new features probably go unused due to lack of solid documentation.

Gideros is superb engine and all it needs is polish and refinement of what is already there without massive changes. That way a book would mesh with it perfectly both now and in future.

Just my 2cents.

SinisterSoft

@john26 If you publish though Amazon directly then you can have the option of supplying an e-book version (kindle, etc) and/or a printed version - they are printed on demand.

SinisterSoft

@MobAmuse You can do textured 3D. I just chose not to do textures in RetroStar to make it look more retro. There is a textured 3D horse demo in the examples.

SinisterSoft

I printed a couple of copies of the original API (from the kickstarter by John) book using Lulu ages ago. At the local primary I help an hour a week in a 'code club' and we taught some of the year 6 pupils Lua/Gideros. For the end of the year I organised a competition, the winner won a copy of the book. The kids loved it and the child who won was so please he had the book. So that's kind of why I think a printed version (as well as an ebook version) would be best.

ar2rsawseen

Hello guys,

unfortunately don't have time myself to participate much, but just to share, that the most common feedback for the first book, was disappointment that some difficult topics, like plugin creation were not included (decision by the publisher).
So if this book would contain one, I think it would also improve the situation of users who want plugins, willing to try make one themselves, starting with simple step by step guides and evolving from them.

When I started working on plugins, it was really hard at first and @atilim helped me all the way through it. Now, after some pause, actually I think it would feel like starting over again, as there are still not enough documentation about this and memory is not flawless
But if you will need some help on it, explaining bits or answering questions what is what, I can try and help

MobAmuse

@Sinistersoft Yes but the texture in that demo looks like alias wavefront export jobby and trying to do the same with blender or even export converter on a custom object no worky with gideros currently. Ended up just doing textureless shapes myself when last played with it some months back.

MobAmuse

UV mapping is all wrong with blender objects in gideros.

antix

After all this time using Gideros I still haven't got my head round plugins, it's still not made for dummies like me :bz

totebo

I think plugins need to be easy to make and use. And, ideally, to sell and buy! Plugins are great, and mean Gideros is infinitely expandable. Go plugins!

We made a plugin for my multiplayer engine Liten, but that was only easy because it uses LuaSocket as a base. Agree with that it has to be easy.