Generated 'Gideros API Reference Manual'

SinisterSoft

I'm working on a Gideros API manual that's completely generated by the existing API documentation. Hopefully this will allow us to see more easily what's missing and if any corrections need to be made. Because it's generated from the data as the data gets updated I can just run the script to make a new version of the manual.

Currently it's missing two things, a html parser to properly format descriptions and a syntax highlighter to colour the examples.

Here it is so far:
https://www.dropbox.com/s/62dtqjtfqsbl2y3/GiderosApi.pdf?dl=0

If you find anything wrong or missing (compared to the online API docs) then please let me know. Don't forget the descriptions might look a little odd because of no formatting and the listings are not yet in colour!

The plan is to have the pdf available as a free download, if possible a free e-book on Amazon and as a paid for paper book on Amazon or Lulu - which ever is the cheaper for people to buy. The paper version hopefully will be available in either b/w or colour.

antix

Looks good but I can't download it

keszegh

how does this relate to @john26's similar idea of a book?

john26

It pretty much replaces it! If @SinisterSoft can auto-generate a book PDF there is really no need for me to publish a book just for the API reference. Instead I should write the second edition of @ar2rsawseen's book, Gideros Mobile App Development. I'm trying to contact Packt to see if they are interested in publishing another edition...

john26

Looks very nice @SinisterSoft and very compact. However, I notice you have not included the Event section at the end of each class and this is very important to put in. Also you should add the constants. So for Sprite you need EVENT.TOUCHES_BEGIN etc and Sprite.ADD etc

john26

I noticed this

"An inactive body is still owned by a [[b2.World]]"

this looks like a wiki cross reference. Ideally you should set cross references as links.

john26

In terms of the HTML, the only thing you really need to respect is the unnumbered list. Syntax highlighting is not really needed IMO, especially when printed out (the book will be in black and white). The reader of the user manual already knows keywords like "local" and "if"

SinisterSoft

I'll look for the events and constants and put them in asap, thanks.

As for links, for the very first version I won't have them as they are both forward and backward references so I'll have to track where they are in the pdf and update on a second pass.

Syntax highlighting will also come later as I'll be making both a 'B/W' and a 'colour edition' - it costs nothing to add them to Amazon as printed books - they print on demand.

john26

Awesome. A color edition would be interesting though i dread to think what it would cost. None of the normal 1000 page programming text books are in color again and you rarely see syntax highlighting in printed programming books

SinisterSoft

yes, colour would be for the people who actually make a bundle using Gideros.

Here is the new version with constants and events added, can you take a look and see if the format for showing events makes sense.

https://www.dropbox.com/s/62dtqjtfqsbl2y3/GiderosApi.pdf?dl=0

john26

Looks very nice, the constants are written very compactly and I agree it's a good idea to have constants and events at the beginning of chapters.

I would prefer to see the Events listed according to their symbolic name eg ENTER_FRAME. In your case you call it the "enterFrame event" but I always think of it as the ENTER_FRAME event or even Event.ENTER_FRAME... Gideros allows two uses

addEventListener(Event.ENTER_FRAME...)
addEventListener("enterFrame"...)

since Event.ENTER_FRAME = "enterFrame"

Personally I always use the former and think it's easier to spot

So I would list the section heading like this
Sprite > ENTER_FRAME event

Then in the function description I would call the function "onEnterFrame" not "enterFrame" to distinguish from the event string name so

function onEnterFrame({deltaTime, time, frameCount})

so just prepend "on" to each one and capitalise the first letter of the next word

SinisterSoft

But you are actually looking up the text string "enterFrame" in the table called "event". Using the string is the real method - and possibly a few cycles faster.

I'll have to think about it, but I think onEnterFrame might just confuse people?

SinisterSoft

Most importantly - can you spot anything missing?

totebo

SinisterSoft said:

But you are actually looking up the text string "enterFrame" in the table called "event". Using the string is the real method - and possibly a few cycles faster.

I'll have to think about it, but I think onEnterFrame might just confuse people?

I'm also a fan of using the symbolic name. I like to ignore the string, because if I use ENTER_FRAME I know it will work, regardless of what value it holds. In fact, for my own constants I tend to just use integers because it feels cleaner somehow.

Also a big fan of "on" in onEnterFrame because it tells you the method is an event handler.

john26

A few more comments: The UrlLoader chapter has some extraneous bold text at the beginning.

string.gsub and .gmatch needs lots of paragraph marks. It's all run together into a single paragraph. Might be other examples in the lua library.

john26

Yes it seems to be complete. Well done!

antix

So what is happening with this?

SinisterSoft

I need to write a syntax parser then I'll re-run the export to make a new pdf. After that it will be available for download AND possibly as a printed book on Amazon.

SinisterSoft

If we are moving to json though please let me know.

antix

I'm pretty sure we are moving to JSON

SinisterSoft

New version of the manual here:
https://www.dropbox.com/s/62dtqjtfqsbl2y3/GiderosApi.pdf?dl=0

I need to put in a html parser for the descriptions and a syntax highlighter for the code examples.

oleg

not all BBcodes work properly

oleg

1 more wishes:
drop 1 more manual but only with the latest changes that have changed in the latest version of Gideros

SinisterSoft

That's a good idea. I could checksum each area and produce a second pdf of just differences/new stuff.

totebo

That's a good idea and would also be an incentive to update the docs for each new feature.