Skip to content

Commit

Permalink
minor copy edits and formatting for Getting Started (JuliaLang#26439)
Browse files Browse the repository at this point in the history 
* minor copy edits and formatting for Getting Started

* fredrikekre's autojuliabannergenerator added

* minor copy edits and formatting for Integers and FP

* fixes

* Update integers-and-floating-point-numbers.md
  • Loading branch information
@cormullion @KristofferC
cormullion authored and KristofferC committed Mar 16, 2018
1 parent 30318cf commit 277e6d5
Show file tree
Hide file tree
Showing 2 changed files with 60 additions and 86 deletions.
133 changes: 53 additions & 80 deletions doc/src/manual/getting-started.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,29 +4,19 @@ Julia installation is straightforward, whether using precompiled binaries or com
Download and install Julia by following the instructions at [https://julialang.org/downloads/](https://julialang.org/downloads/).

The easiest way to learn and experiment with Julia is by starting an interactive session (also
known as a read-eval-print loop or "repl") by double-clicking the Julia executable or running
known as a read-eval-print loop or "REPL") by double-clicking the Julia executable or running
`julia` from the command line:

```
$ julia
_
_ _ _(_)_ | A fresh approach to technical computing
(_) | (_) (_) | Documentation: https://docs.julialang.org
_ _ _| |_ __ _ | Type "?help" for help.
| | | | | | |/ _` | |
| | |_| | | | (_| | | Version 0.5.0-dev+2440 (2016-02-01 02:22 UTC)
_/ |\__'_|_|_|\__'_| | Commit 2bb94d6 (11 days old master)
|__/ | x86_64-apple-darwin13.1.0
julia> 1 + 2
3
julia> ans
3
```@eval
io = IOBuffer()
Base.banner(io)
banner = String(take!(io))
import Markdown
Markdown.parse("```\n\$ julia\n\n$(banner)\njulia> 1 + 2\n3\n\njulia> ans\n3\n```")
```

To exit the interactive session, type `^D` -- the control key together with the `d` key or type
`quit()`. When run in interactive mode, `julia` displays a banner and prompts the user for input.
To exit the interactive session, type `CTRL-D` (press the Control/`^` key together with the `d` key), or type
`exit()`. When run in interactive mode, `julia` displays a banner and prompts the user for input.
Once the user has entered a complete expression, such as `1 + 2`, and hits enter, the interactive
session evaluates the expression and shows its value. If an expression is entered into an interactive
session with a trailing semicolon, its value is not shown. The variable `ans` is bound to the
Expand All @@ -42,11 +32,12 @@ command:
$ julia script.jl arg1 arg2...
```

As the example implies, the following command-line arguments to `julia` are taken as command-line
arguments to the program `script.jl`, passed in the global constant `ARGS`. The name of the script
itself is passed in as the global `PROGRAM_FILE`. Note that `ARGS` is also set when script code
is given using the `-e` option on the command line (see the `julia` help output below) but `PROGRAM_FILE`
will be empty. For example, to just print the arguments given to a script, you could do this:
As the example implies, the following command-line arguments to `julia` are interpreted as
command-line arguments to the program `script.jl`, passed in the global constant `ARGS`. The
name of the script itself is passed in as the global `PROGRAM_FILE`. Note that `ARGS` is
also set when a Julia expression is given using the `-e` option on the command line (see the
`julia` help output below) but `PROGRAM_FILE` will be empty. For example, to just print the
arguments given to a script, you could do this:

```
$ julia -e 'println(PROGRAM_FILE); for x in ARGS; println(x); end' foo bar
Expand All @@ -65,19 +56,19 @@ foo
bar
```

The `--` delimiter can be used to separate command-line args to the scriptfile from args to Julia:
The `--` delimiter can be used to separate command-line arguments intended for the script file from arguments intended for Julia:

```
$ julia --color=yes -O -- foo.jl arg1 arg2..
```

Julia can be started in parallel mode with either the `-p` or the `--machine-file` options. `-p n`
will launch an additional `n` worker processes, while `--machine-file file` will launch a worker
for each line in file `file`. The machines defined in `file` must be accessible via a passwordless
for each line in file `file`. The machines defined in `file` must be accessible via a password-less
`ssh` login, with Julia installed at the same location as the current host. Each machine definition
takes the form `[count*][user@]host[:port] [bind_addr[:port]]` . `user` defaults to current user,
takes the form `[count*][user@]host[:port] [bind_addr[:port]]`. `user` defaults to current user,
`port` to the standard ssh port. `count` is the number of workers to spawn on the node, and defaults
to 1. The optional `bind-to bind_addr[:port]` specifies the ip-address and port that other workers
to 1. The optional `bind-to bind_addr[:port]` specifies the IP address and port that other workers
should use to connect to this worker.

If you have code that you want executed whenever Julia is run, you can put it in
Expand All @@ -96,59 +87,41 @@ There are various ways to run Julia code and provide options, similar to those a

```
julia [switches] -- [programfile] [args...]
-v, --version Display version information
-h, --help Print this message
-J, --sysimage <file> Start up with the given system image file
-H, --home <dir> Set location of `julia` executable
--startup-file={yes|no} Load `~/.julia/config/startup.jl`
--handle-signals={yes|no} Enable or disable Julia's default signal handlers
--sysimage-native-code={yes|no}
Use native code from system image if available
--compiled-modules={yes|no}
Enable or disable incremental precompilation of modules
-e, --eval <expr> Evaluate <expr>
-E, --print <expr> Evaluate <expr> and display the result
-L, --load <file> Load <file> immediately on all processors
-p, --procs {N|auto} Integer value N launches N additional local worker processes
"auto" launches as many workers as the number of local cores
--machine-file <file> Run processes on hosts listed in <file>
-i Interactive mode; REPL runs and isinteractive() is true
-q, --quiet Quiet startup: no banner, suppress REPL warnings
--banner={yes|no|auto} Enable or disable startup banner
--color={yes|no|auto} Enable or disable color text
--history-file={yes|no} Load or save history
--depwarn={yes|no|error} Enable or disable syntax and method deprecation warnings ("error" turns warnings into errors)
--warn-overwrite={yes|no} Enable or disable method overwrite warnings
-C, --cpu-target <target> Limit usage of cpu features up to <target>; set to "help" to see the available options
-O, --optimize={0,1,2,3} Set the optimization level (default level is 2 if unspecified or 3 if used without a level)
-g, -g <level> Enable / Set the level of debug info generation (default level is 1 if unspecified or 2 if used without a level)
--inline={yes|no} Control whether inlining is permitted, including overriding @inline declarations
--check-bounds={yes|no} Emit bounds checks always or never (ignoring declarations)
--math-mode={ieee,fast} Disallow or enable unsafe floating point optimizations (overrides @fastmath declaration)
--code-coverage={none|user|all}, --code-coverage
Count executions of source lines (omitting setting is equivalent to "user")
--track-allocation={none|user|all}, --track-allocation
Count bytes allocated by each source line
```

|Switch |Description|
|:--- |:---|
|`-v`, `--version` |Display version information|
|`-h`, `--help` |Print this message|
|`-J`, `--sysimage <file>` |Start up with the given system image file|
|`-H`, `--home <dir>` |Set location of `julia` executable|
|`--startup-file={yes\|no}` |Load `~/.julia/config/startup.jl`|
|`--handle-signals={yes\|no}` |Enable or disable Julia's default signal handlers|
|`--sysimage-native-code={yes\|no}` |Use native code from system image if available|
|`--compiled-modules={yes\|no}` |Enable or disable incremental precompilation of modules|
|`-e`, `--eval <expr>` |Evaluate `<expr>`|
|`-E`, `--print <expr>` |Evaluate `<expr>` and display the result|
|`-L`, `--load <file>` |Load `<file>` immediately on all processors|
|`-p`, `--procs {N\|auto`} |Integer value N launches N additional local worker processes; `auto` launches as many workers as the number of local cores|
|`--machine-file <file>` |Run processes on hosts listed in `<file>`|
|`-i` |Interactive mode; REPL runs and `isinteractive()` is true|
|`-q`, `--quiet` |Quiet startup: no banner, suppress REPL warnings|
|`--banner={yes\|no\|auto}` |Enable or disable startup banner|
|`--color={yes\|no\|auto}` |Enable or disable color text|
|`--history-file={yes\|no}` |Load or save history|
|`--depwarn={yes\|no\|error}` |Enable or disable syntax and method deprecation warnings (`error` turns warnings into errors)|
|`--warn-overwrite={yes\|no}` |Enable or disable method overwrite warnings|
|`-C`, `--cpu-target <target>` |Limit usage of cpu features up to <target>; set to `help` to see the available options|
|`-O`, `--optimize={0,1,2,3}` |Set the optimization level (default level is 2 if unspecified or 3 if used without a level)|
|`-g`, `-g <level>` |Enable / Set the level of debug info generation (default level is 1 if unspecified or 2 if used without a level)|
|`--inline={yes\|no}` |Control whether inlining is permitted, including overriding `@inline` declarations|
|`--check-bounds={yes\|no}` |Emit bounds checks always or never (ignoring declarations)|
|`--math-mode={ieee,fast}` |Disallow or enable unsafe floating point optimizations (overrides @fastmath declaration)|
|`--code-coverage={none\|user\|all}` |Count executions of source lines|
|`--code-coverage` |equivalent to `--code-coverage=user`|
|`--track-allocation={none\|user\|all}` |Count bytes allocated by each source line|
|`--track-allocation` |equivalent to `--track-allocation=user`|

## Resources

In addition to this manual, there are various other resources that may help new users get started
with Julia:

* [Julia and IJulia cheatsheet](http:https://math.mit.edu/~stevenj/Julia-cheatsheet.pdf)
* [Learn Julia in a few minutes](https://learnxinyminutes.com/docs/julia/)
* [Learn Julia the Hard Way](https://github.com/chrisvoncsefalvay/learn-julia-the-hard-way)
* [Julia by Example](http:https://samuelcolvin.github.io/JuliaByExample/)
* [Hands-on Julia](https://github.com/dpsanders/hands_on_julia)
* [Tutorial for Homer Reid's numerical analysis class](http:https://homerreid.dyndns.org/teaching/18.330/JuliaProgramming.shtml)
* [An introductory presentation](https://raw.githubusercontent.com/ViralBShah/julia-presentations/master/Fifth-Elephant-2013/Fifth-Elephant-2013.pdf)
* [Videos from the Julia tutorial at MIT](https://julialang.org/blog/2013/03/julia-tutorial-MIT)
* [YouTube videos from the JuliaCons](https://www.youtube.com/user/JuliaLanguage/playlists)
A curated list of useful learning resources to help new users get started can be found on the [learning](https://julialang.org/learning/) page of the main Julia web site.
13 changes: 7 additions & 6 deletions doc/src/manual/integers-and-floating-point-numbers.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -338,7 +338,7 @@ julia> 10_000, 0.000_000_005, 0xdead_beef, 0b1011_0010

Floating-point numbers have [two zeros](https://en.wikipedia.org/wiki/Signed_zero), positive zero
and negative zero. They are equal to each other but have different binary representations, as
can be seen using the `bits` function:
can be seen using the [`bitstring`](@ref) function:

```jldoctest
julia> 0.0 == -0.0
Expand Down Expand Up @@ -491,9 +491,10 @@ also have adjacent binary integer representations.

### Rounding modes

If a number doesn't have an exact floating-point representation, it must be rounded to an appropriate
representable value, however, if wanted, the manner in which this rounding is done can be changed
according to the rounding modes presented in the [IEEE 754 standard](https://en.wikipedia.org/wiki/IEEE_754-2008).
If a number doesn't have an exact floating-point representation, it must be rounded to an
appropriate representable value. However, the manner in which this rounding is done can be
changed if required according to the rounding modes presented in the [IEEE 754
standard](https://en.wikipedia.org/wiki/IEEE_754-2008).

```jldoctest
julia> x = 1.1; y = 0.1;
Expand Down Expand Up @@ -613,7 +614,7 @@ julia> setprecision(40) do

## [Numeric Literal Coefficients](@id man-numeric-literal-coefficients)

To make common numeric formulas and expressions clearer, Julia allows variables to be immediately
To make common numeric formulae and expressions clearer, Julia allows variables to be immediately
preceded by a numeric literal, implying multiplication. This makes writing polynomial expressions
much cleaner:

Expand Down Expand Up @@ -689,7 +690,7 @@ where syntactic conflicts arise:
* The floating-point literal expression `1e10` could be interpreted as the numeric literal `1` multiplied
by the variable `e10`, and similarly with the equivalent `E` form.

In both cases, we resolve the ambiguity in favor of interpretation as a numeric literals:
In both cases, we resolve the ambiguity in favor of interpretation as numeric literals:

* Expressions starting with `0x` are always hexadecimal literals.
* Expressions starting with a numeric literal followed by `e` or `E` are always floating-point literals.
Expand Down

0 comments on commit 277e6d5

Please sign in to comment.