Merge pull request #2 from ellemenno/master

v2

README.md

@@ -1,19 +1,20 @@
 # jailang
 
-> unofficial documentation of the jai programming language
+> unofficial documentation of the jai programming language <br>
+> https://pixeldroid.github.io/jailang/
 
-Jai is a computer programming language being developed by Jonathan Blow and team at [Thekla][thekla-web].
+Jai is a computer programming language being developed by Jonathan Blow and team at [Thekla, Inc.][thekla-web].
 
-This site attempts to form a language reference out of the hours and hours of video information presented by Jonathan Blow on his youtube channel: [A Programming Language for Games].
+This site attempts to form a searchable language reference out of the hours and hours of video information presented by Jonathan Blow on his youtube channel: [A Programming Language for Games].
 
 Other unofficial jai summaries:
 
-- http://www.mrphilgames.com/jai/
+- https://www.mrphilgames.com/jai/
 - https://github.com/BSVino/JaiPrimer/blob/master/JaiPrimer.md
 - https://inductive.no/jai/
 
 
 
 [A Programming Language for Games]: https://www.youtube.com/playlist?list=PLmV5I2fxaiCKfxMBrNsU1kgKJXD3PkyxO "video playlist introducing the jai language and its motivations"
 [thekla-twitter]: https://twitter.com/Thekla_Inc "Thekla, Inc. on Twitter"
-[thekla-web]: http://the-witness.net/news/ "Thekla, Inc on the web"
+[thekla-web]: http://the-witness.net/news/ "Thekla, Inc. on the web"

docs/_config.yml

@@ -3,7 +3,7 @@ project:
   name: jailang
   owner: pixeldroid
   repo: https://github.com/pixeldroid/jailang
-  version: 1
+  version: 2
 collections:
   overview:
     output: true
@@ -15,13 +15,20 @@ collections:
     permalink: "/:collection/:path/"
     title: Features
     tab-order: 2
+  stdlib:
+    output: true
+    permalink: "/:collection/:path/"
+    title: StdLib
+    tab-order: 3
   examples:
     output: true
     permalink: "/:collection/:path/"
     title: Examples
-    tab-order: 3
+    tab-order: 4
 code_indent: "  "
 highlighter: rouge
+include:
+- "#*.md"
 kramdown:
   footnote_backlink: '⮌'
 permalink: pretty

docs/_data/videos.yaml

@@ -0,0 +1,45 @@
+##
+##  Videos referenced in the documentation
+##    MLA style format: "Title of Video." YouTube, uploaded by Username, Date, URL (without the http://).
+##    from: https://libanswers.snhu.edu/faq/48006
+##
+
+ideas_20140919:
+  mla: |-
+    “Ideas about a new programming language for games.” _YouTube_, uploaded by Jonathan Blow, Sep 19, 2014
+  url: https://youtu.be/TH9VCN6UkyQ
+
+ideas_20140926:
+  mla: |-
+    “A Programming Language for Games, talk #2.” _YouTube_, uploaded by Jonathan Blow, Sep 26, 2014
+  url: https://youtu.be/5Nc68IdNKdg
+
+demo_20141031:
+  mla: |-
+    “Demo: Base language, compile-time execution.” _YouTube_, uploaded by Jonathan Blow, Oct 31, 2014
+  url: https://youtu.be/UTqZNujQOlA
+
+demo_20141210:
+  mla: |-
+    “Demo: Iteration and arrays, uninitialized values, enums.” _YouTube_, uploaded by Jonathan Blow, Dec 10, 2014
+  url: https://youtu.be/-UPFH0eWHEI
+
+demo_20141211_qa:
+  mla: |-
+    “Q&A for Iteration and arrays, uninitialized values, enums.” _YouTube_, uploaded by Jonathan Blow, Dec 11, 2014
+  url: https://youtu.be/K45J_9jns7w
+
+demo_20150121:
+  mla: |-
+    “Data-Oriented Demo: SOA, composition.” _YouTube_, uploaded by Jonathan Blow, Jan 21, 2015
+  url: https://youtu.be/ZHqFrNyLlpA
+
+reboot_2017:
+  mla: |-
+    “Reboot Develop 2017 - Jonathan Blow, Thekla Inc. / Making Game Programming Less Terrible.” _YouTube_, uploaded by Reboot Develop, May 22, 2017
+  url: https://youtu.be/De0Am_QcZiQ
+
+gamelab_2018:
+  mla: |-
+    “#Gamelab2018 - Jon Blow's Design decisions on creating Jai, a new language for game programmers.” _YouTube_, uploaded by Social Gamelab, Jul 13, 2018
+  url: https://youtu.be/uZgbKrDEzAs

docs/_features/Anti-features.md

@@ -0,0 +1,54 @@
+---
+layout: page
+title: Anti-features
+
+footnotes:
+ -
+    label: no-exceptions
+    video: ideas_20140919
+    time:  2379
+    text:  exceptions are silly at best, and horribly damaging at worst.
+ -
+    label: no-garbage-collection
+    video: ideas_20140919
+    time:  407
+    text:  you can't build a sufficiently low-level system with sufficiently high performance characteristics in a garbage collected language.
+ -
+    label: no-header-files
+    video: ideas_20140919
+    time:  4484
+    text:  no god damn header files.
+ -
+    label: no-preprocessor
+    video: demo_20141031
+    time:  4058
+    text:  directives are part of the language; there is no preprocessor system.
+ -
+    label: no-smart-pointers
+    video: ideas_20140919
+    time:  2718
+    text:  we're not afraid of pointers in the game industry. we need to use them.
+ -
+    label: no-template-metaprogamming
+    text:  'FIXME: find this video reference'
+
+---
+
+
+# {{ page.title }}
+
+Jai is designed to _**not**_ include the following:
+{:.larger.text}
+
+- header files [^no-header-files]
+- garbage collection [^no-garbage-collection]
+- exceptions [^no-exceptions]  (see Multiple return values instead)
+- preprocessor [^no-preprocessor]  (directives are part of the language)
+- smart pointers [^no-smart-pointers]  (see [Memory management] instead)
+- template metaprogramming [^no-template-metaprogamming]  (see Polymorphism instead)
+{:.larger.text}
+
+
+{% include footnotes.liquid references=page.footnotes %}
+
+[Memory management]: {{site.baseurl}}/features/Memory-management/#/features/ "The language design focuses on making it easier to manage memory"

docs/_features/Build-routines.md

@@ -0,0 +1,86 @@
+---
+layout: page
+title: Build routines
+
+footnotes:
+ -
+    label: build-example
+    video: demo_20141210
+    time:  251
+    text:  this `#run` directive says that at compile time when this run directive is hit, we're going to run this function and anything else that needs to get compiled to make that function work.
+ -
+    label: build-options
+    video: demo_20141210
+    time:  1759
+    text:  #FIXME: provide text
+ -
+    label: build-options-struct
+    video: reboot_2017
+    time:  1759
+    text:  you have a struct that defines the build options, and you apply those build options to the compiler workspace.
+ -
+    label: build-routine
+    video: demo_20141031
+    time:  3859
+    text:  using the `#run` directive to run a build routine at compile time.
+ -
+    label: code-modification
+    video: reboot_2017
+    time:  2571
+    text:  you can modify compile-time data structures and resubmit them.
+ -
+    label: compiler-does-everything
+    video: ideas_20140919
+    time:  5166
+    text:  you shouldn't need wacky different tools on every operating system. you should need the compiler and your source code and that's all.
+
+---
+
+
+# {{ page.title }}
+
+
+The Jai compiler will handle all the aspects of building an executable: compiling (in parallel), linking, etc.[^compiler-does-everything]
+{:.larger.text}
+
+The compiler provides an api to work with build configuration options.[^build-routine] [^build-options] [^build-options-struct]
+
+For example:[^build-example]
+
+```cpp
+build := () {
+    printf("In build (at compile time).\n");
+
+    build_options.optimization_level = Optimization_Level.DEBUG;
+    build_options.emit_line_directives = false;
+    build_options.executable_name = "traveller.jai";
+
+    update_build_options();
+
+    printf("build_options.executable_name = %s\n", build_options.executable_name);
+    printf("build_options.output_path = %s\n", build_options.output_path);
+
+    printf("Building from file %s, line %d.\n", #file, #line);
+    printf("filepath is: %s\n", #filepath);
+
+    set_build_file_path(#filepath);
+
+    add_build_file("misc.jai");
+    add_build_file("invaders.jai");
+    add_build_file("checks.jai");
+    add_build_file("levels.jai");
+}
+
+#run build();
+```
+
+This also lets you re-use more code, and make build activities arbitrarily complex (code analysis, correctness checks, house rules, etc.) by using a general purpose programming language instead of various specialized build languages.
+
+You can write programs that modify or generate code during compilation to use in a later part of the compilation process.[^code-modification]
+
+```cpp
+value_table: [] float = #run generate_expensive_values(); // #run invokes the compile time execution
+```
+
+
+{% include footnotes.liquid references=page.footnotes %}

docs/_features/Compile-time-code-execution.md

@@ -0,0 +1,26 @@
+---
+layout: page
+title: Full compile-time code execution
+
+footnotes:
+ -
+    label: run-in-compiler
+    video: reboot_2017
+    time:  1526
+    text:  full compile-time execution.
+
+---
+
+
+# {{ page.title }}
+
+There are no limitations, the compiler knows how to _run_ the intermediate representation of the programming language.[^run-in-compiler]
+{:.larger.text}
+
+This lets you simplify your project:
+
+- no make, build, or properties files in other arbitrary languages; everything is written in the same main language.
+- cross-platform. exactly the same code works on every platform.
+
+
+{% include footnotes.liquid references=page.footnotes %}

docs/_features/Concurrency.md

@@ -0,0 +1,21 @@
+---
+layout: page
+title: Concurrency
+
+footnotes:
+ -
+    label: concurrency
+    video: ideas_20140919
+    time:  4810
+    text:  concurrency is huge. It's going to get huger for games.
+
+---
+
+
+# {{ page.title }}
+
+CPU clock speeds aren't getting that much faster anymore, but we are getting more processors. So concurrency is hugely important for games. [^concurrency]
+{:.larger.text}
+
+
+{% include footnotes.liquid references=page.footnotes %}

docs/_features/Directives.md

@@ -0,0 +1,27 @@
+---
+layout: page
+title: Directives
+
+footnotes:
+ -
+    label: no-preprocessor
+    video: demo_20141031
+    time:  4058
+    text:  directives are part of the language; there is no preprocessor system.
+
+---
+
+
+# {{ page.title }}
+
+There is no preprocessor for Jai; directives are just part of the language. [^no-preprocessor]
+{:.larger.text}
+
+See the following entries in the [standard library](#/stdlib) for more details:
+
+{% assign collection = site.collections | where:"title","StdLib" | first %}
+{% for d in collection.docs %}
+- [{{ d.title }}]({{site.baseurl}}{{d.url}}#/stdlib) - {{ d.description }}
+{% endfor %}
+
+{% include footnotes.liquid references=page.footnotes %}

docs/_features/Factorability.md

@@ -0,0 +1,45 @@
+---
+layout: page
+title: Factorability
+
+footnotes:
+ -
+    label: capture-for-any-block
+    video: ideas_20140926
+    time:  3344
+    text:  i can just apply a capture to any block.
+ -
+    label: code-maturation
+    video: ideas_20140926
+    time:  2171
+    text:  your programming language should be designed to support the transition from humble beginnings to final product.
+ -
+    label: factorability-drudge
+    video: ideas_20140926
+    time:  1837
+    text:  we want to avoid meaningless syntactic changes that create drudge work as I gradually factor my program from its beginning state into its final state.
+ -
+    label: factorability-lift
+    video: ideas_20140926
+    time:  3549
+    text:  we have this whole sequence of stages we can lift a block of code on.
+
+---
+
+
+# {{ page.title }}
+
+Code has a maturation cycle; you don't just write the final thing initially, because you don't know what it should be. You work your way there. [^code-maturation]
+{:.larger.text}
+
+Scalars and functions do not require meaningless syntax changes when changing scope, capturing scope [^capture-for-any-block], or switching between being named or unnamed.[^factorability-drudge] [^factorability-lift]
+
+```cpp
+                                 { ... } // Anonymous code block
+                       [capture] { ... } // Captured code block
+     (i: int) -> float [capture] { ... } // Anonymous function
+f :: (i: int) -> float [capture] { ... } // Named function (local or global)
+```
+
+
+{% include footnotes.liquid references=page.footnotes %}

docs/_features/Foreign-Function-Interface.md

@@ -0,0 +1,24 @@
+---
+layout: page
+title: Foreign Function Interface
+
+footnotes:
+ -
+    label: ffi-printf
+    video: demo_20141031
+    time:  1599
+    text:  a straight-forward foreign function interface allows things like calling out to C for `printf`.
+
+---
+
+
+# {{ page.title }}
+
+Jai provides a straight-forward foreign function interface.
+{:.larger.text}
+
+- `printf()` - calls out to C's printf [^ffi-printf]
+- OpenGL
+
+
+{% include footnotes.liquid references=page.footnotes %}