diff --git a/doc/site/control-flow.markdown b/doc/site/control-flow.markdown index b484849b..c1f10c53 100644 --- a/doc/site/control-flow.markdown +++ b/doc/site/control-flow.markdown @@ -2,7 +2,7 @@ ^category language Control flow is used to determine which chunks of code are executed and how -many times. *Branching* statements deciding whether or not to execute some code +many times. *Branching* statements decide whether or not to execute some code and *looping* ones execute something more than once. ## Truth @@ -94,9 +94,9 @@ single statement: ## For statements While statements are useful when you want to loop indefinitely or according to -some complex condition. But in most cases, you're looping through a -[list](lists.html), a series of numbers, or some other "sequence" object. -That's what `for` is for. It looks like this: +some complex condition. But in most cases, you're looping through +a [list](lists.html), a series of numbers, or some other "sequence" object. +That's what `for` is, uh, for. It looks like this: :::wren for (beatle in ["george", "john", "paul", "ringo"]) { @@ -159,7 +159,7 @@ series of numbers. ## The iterator protocol Lists and ranges cover the two most common kinds of loops, but you should also -be able to define your own sequences. To enable that, the semantics of a `for` +be able to define your own sequences. To enable that, the semantics of `for` are defined in terms of an "iterator protocol". The loop itself doesn't know anything about lists or ranges, it just knows how to call two particular methods on the object that resulted from evaluating the sequence expression. diff --git a/doc/site/core/num.markdown b/doc/site/core/num.markdown index 7f4875ba..41e058ce 100644 --- a/doc/site/core/num.markdown +++ b/doc/site/core/num.markdown @@ -127,7 +127,7 @@ It is a runtime error if `other` is not a number. ### **..**(other) operator -Creates a [Range](core/range.html) representing a consecutive range of numbers +Creates a [Range](range.html) representing a consecutive range of numbers from the beginning number to the ending number. :::wren @@ -138,7 +138,7 @@ from the beginning number to the ending number. ### **...**(other) operator -Creates a [Range](core/range.html) representing a consecutive range of numbers +Creates a [Range](range.html) representing a consecutive range of numbers from the beginning number to the ending number not including the ending number. :::wren diff --git a/doc/site/core/range.markdown b/doc/site/core/range.markdown index 88545166..f7b3e2e2 100644 --- a/doc/site/core/range.markdown +++ b/doc/site/core/range.markdown @@ -1,7 +1,8 @@ ^title Range Class ^category core -**TODO** +A range defines a bounded range of values from a starting point to a possibly +exclusive endpoint. [Here](../range.html) is a friendly introduction. Extends [Sequence](sequence.html). @@ -9,24 +10,49 @@ Extends [Sequence](sequence.html). ### **from** -**TODO** +The starting point of the range. A range may be backwards, so this can be +greater than [to]. + + :::wren + (3..5).min // 3. + (4..2).min // 4. ### **to** -**TODO** +The endpoint of the range. If the range is inclusive, this value is included, +otherwise it is not. + + :::wren + (3..5).min // 5. + (4..2).min // 2. ### **min** -**TODO** +The minimum bound of the range. Returns either `from`, or `to`, whichever is +lower. + + :::wren + (3..5).min // 3. + (4..2).min // 2. ### **max** -**TODO** +The maximum bound of the range. Returns either `from`, or `to`, whichever is +greater. + + :::wren + (3..5).min // 5. + (4..2).min // 4. ### **isInclusive** -**TODO** +Whether or not the range includes `to`. (`from` is always included.) + + :::wren + (3..5).isInclusive // true. + (3...5).isInclusive // false. ### **iterate**(iterator), **iteratorValue**(iterator) -**TODO** +Iterates over the range. Starts at `from` and increments by one towards `to` +until the endpoint is reached. diff --git a/doc/site/getting-started.markdown b/doc/site/getting-started.markdown index fb8f02e4..20bc33ab 100644 --- a/doc/site/getting-started.markdown +++ b/doc/site/getting-started.markdown @@ -1,24 +1,26 @@ ^title Getting Started -Getting Wren up and running on your machine should be pretty straightforward. -Tiny C programs with few dependencies are nice that way. "Wren" encompasses two -separate artifacts: +Getting Wren running on your machine is straightforward. Tiny C programs with +few dependencies are nice that way. "Wren" encompasses two separate artifacts: * **The virtual machine.** This is the core chunk of C that executes Wren source code. It is just a library, not a standalone application. It's - designed to be [embedded][] in a larger host application. It has no dependencies beyond the C standard library. You can is use as a static library, shared library, or simply compile the source into your app. + designed to be [embedded][] in a larger host application. It has no + dependencies beyond the C standard library. You can is use as a static + library, shared library, or simply compile the source into your app. * **The command line executable.** Wren also ships with a CLI wrapper around the VM. This gives you a way to run Wren code from the command-line, and - also includes modules for talking to the operating system. It depends on - [libuv][] for that. + also includes modules for talking to the operating system—file IO, + networking, stuff like that. It depends on [libuv][] for that + functionality. [embedded]: embedding-api.html [libuv]: http://libuv.org/ If you're on a Unix or Mac and you can rock a command line, it's just: - :::bash + :::sh $ git clone https://github.com/munificent/wren.git $ cd wren $ make @@ -29,24 +31,24 @@ The release build of the CLI goes right into the repo's top level directory. Binaries for other configurations are built to `bin/`. Static and shared libraries for embedding Wren get built in `lib/`. -For Mac users, there is also an XCode project under `project/xcode`. For -Windows brethren, `project/msvc2013` contains a Visual Studio solution. Note +For Mac users, there is also an XCode project under `util/xcode`. For +Windows brethren, `util/msvc2013` contains a Visual Studio solution. Note that these may not have the exact same build settings as the makefile. The makefile is the "official" way to compile Wren. If you only want to build the VM, you can do: - :::bash + :::sh $ make vm -This will compile the VM to static and shared libraries. It will not even -download libuv since it isn't needed. +This compiles the VM to static and shared libraries. It does not even download +libuv since it isn't needed. ## Interactive mode -The above instructions will drop you into Wren's standalone interpreter in -interactive mode. You can type in a line of code, and it will immediately -execute it. Here's something to try: +If you just run `wren` without any arguments, it starts the interpreter in +interactive mode. You can type in a line of code, and it immediately executes +it. Here's something to try: :::wren System.print("Hello, world!") @@ -62,7 +64,7 @@ your computer to the ground and storm off. ## Running scripts The standalone interpreter can also load scripts from files and run them. Just -pass the name of the script to wren. Create a file named "my_script.wren" in +pass the name of the script to `wren`. Create a file named "my_script.wren" in your favorite text editor and paste this into it: :::wren @@ -88,7 +90,7 @@ your favorite text editor and paste this into it: Now run: - :::bash + :::sh $ ./wren my_script.wren Neat, right? You're a Wren programmer now! The next step is to [read more diff --git a/doc/site/performance.markdown b/doc/site/performance.markdown index 81527120..a0dd074d 100644 --- a/doc/site/performance.markdown +++ b/doc/site/performance.markdown @@ -230,8 +230,8 @@ makes its job harder. Lua also tries very hard to be compatible across a wide range of hardware and compilers. If you have a C89 compiler for it, odds are very good that you can run Lua on it. -Wren cares about compatibility, but it requires C99 and IEEE double precision -floats. That may exclude some edge case hardware, but makes things like NaN -tagging, computed gotos, and some other tricks possible. +Wren cares about compatibility, but it requires C99 or C++98 and IEEE double +precision floats. That may exclude some edge case hardware, but makes things +like NaN tagging, computed gotos, and some other tricks possible. diff --git a/doc/site/style.scss b/doc/site/style.scss index b88ec121..eed083c7 100644 --- a/doc/site/style.scss +++ b/doc/site/style.scss @@ -325,12 +325,13 @@ table { // Bar charts on the performance page. table.chart { + margin: 4px 0 0 0; padding: 5px 0 5px 25px; td, th { line-height: 14px; margin: 0; - padding: 0; + padding: 1px 0; } th { diff --git a/doc/site/syntax.markdown b/doc/site/syntax.markdown index 833520ee..129b57c1 100644 --- a/doc/site/syntax.markdown +++ b/doc/site/syntax.markdown @@ -7,7 +7,9 @@ while being a bit simpler and more streamlined. Scripts are stored in plain text files with a `.wren` file extension. Wren does not compile ahead of time: programs are run directly from source, from top to bottom like a typical scripting language. (Internally, programs are compiled to -bytecode for efficiency, but that's an implementation detail.) +bytecode for [efficiency][], but that's an implementation detail.) + +[efficiency]: performance.html ## Comments @@ -16,12 +18,23 @@ Line comments start with `//` and end at the end of the line: :::wren // This is a comment. -Block comments start with `/*` and end with `*/`. They can span multiple lines -or be within a single one. Unlike C, block comments can nest in Wren: +Block comments start with `/*` and end with `*/`. They can span multiple lines: + + :::wren + /* This + is + a + multi-line + comment. */ + +Unlike C, block comments can nest in Wren: :::wren /* This is /* a nested */ comment. */ +This is handy because it lets you easily comment out an entire block of code, +even if the code already contains block comments. + ## Reserved words Some people like to see all of the reserved words in a programming language in diff --git a/doc/site/values.markdown b/doc/site/values.markdown index c5465eb8..38ca64d4 100644 --- a/doc/site/values.markdown +++ b/doc/site/values.markdown @@ -68,7 +68,7 @@ Strings are instances of class [String](core/string.html). ## Ranges -A range is a little object that represents a consecutive range of integers. +A range is a little object that represents a consecutive range of numbers. They don't have their own dedicated literal syntax. Instead, the number class implements the `..` and `...` [operators](expressions.html#operators) to create them: diff --git a/doc/site/variables.markdown b/doc/site/variables.markdown index cea03cf9..2e39d1a8 100644 --- a/doc/site/variables.markdown +++ b/doc/site/variables.markdown @@ -1,8 +1,8 @@ ^title Variables ^category language -Variables are named slots for storing values. You can define a new variable in -Wren using a `var` statement, like so: +Variables are named slots for storing values. You define a new variable in Wren +using a `var` statement, like so: :::wren var a = 1 + 2 diff --git a/util/generate_docs.py b/util/generate_docs.py index 67b91f77..cc6c7dec 100755 --- a/util/generate_docs.py +++ b/util/generate_docs.py @@ -91,7 +91,7 @@ def format_file(path, skip_up_to_date): else: contents = contents + line - html = markdown.markdown(contents, ['def_list', 'codehilite']) + html = markdown.markdown(contents, ['def_list', 'codehilite', 'smarty']) modified = datetime.fromtimestamp(os.path.getmtime(in_path)) mod_str = modified.strftime('%B %d, %Y')