Add examples

[JLPLabs]

Perhaps you will find value in adding examples for new users? I'm interested in preparing a handful of such examples, and have included this pull request to demonstrate what "Examples" could look like.

[github-actions[bot]]

Teal Playground URL: https://651--teal-playground-preview.netlify.app

[hishamhm]

Hi! Thanks for the initiative!

I wouldn't mind at all having some examples in the repo. My immediate thought goes towards long-term maintenance, though, so there are a few things that I'd like to see:

• use .md instead of .rst for consistency with the rest of the docs
• let's not use png screenshots of the sources; it would be difficult to maintain it consistently. Code snippets, even with the imperfect coloring of triple-backquote lua are fine. (But having the entire source code duplicated both inline and as a standalone file is a concern for long-term consistency.)
• we'd need some sort of CI integration to check that the examples continue to work as the compiler/language changes

Apart from those items which I'd consider more-or-less blockers, there are other minor stylistic things that I'd probably change:

• coding style of the examples; I'd make them more similar to the compiler's own coding style (spacing around operators, no run-in if then ... else ... end lines, etc)
• I'd skip the "Exercises" section as in general the docs/ section is not aimed at someone new to programming, or even Lua. The Teal docs pretty much assume you already know Lua; we're not teaching people all the way from the basics such as how to manipulate files here, that would be a larger pedagogical undertaking than I'm willing to make.

Another possible avenue for learning-Teal-by-example would be to have larger well-commented examples added to the https://github.com/teal-language/teal-playground/ dropdown at https://teal-playground.netlify.app!

[JLPLabs]

Thanks for the thoughtful reply and your consideration of my offer.

I'll make an attempt to update according to your feedback over the next 2 days.

[JLPLabs]

I think this latest update covers all but one of the bullet items you had. I do not know how to do the CI integration of the example code. Other than that, is this more of what you think is a good fit that is easier to maintain?

[hishamhm]

@JLPLabs sorry it took me a long time to properly get to this. I have merged it manually, squashing the commits, removing the PNG file and reworking the example a bit (I made my changes on a separate commit for ease of diffing — should make it a lot easier to see what kind of changes I had in mind to get this merged; I thought I'd take the time and do them myself instead of asking for more changes).

But it's merged now! So I'll close this PR manually. Thanks again!!