From 277e6d5570383307d9a22993cc098ca98a3de614 Mon Sep 17 00:00:00 2001 From: cormullion Date: Fri, 16 Mar 2018 08:43:02 +0000 Subject: [PATCH] minor copy edits and formatting for Getting Started (#26439) * 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 --- doc/src/manual/getting-started.md | 133 +++++++----------- .../integers-and-floating-point-numbers.md | 13 +- 2 files changed, 60 insertions(+), 86 deletions(-) diff --git a/doc/src/manual/getting-started.md b/doc/src/manual/getting-started.md index e995f845e24fc..f3c48493edb9d 100644 --- a/doc/src/manual/getting-started.md +++ b/doc/src/manual/getting-started.md @@ -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 @@ -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 @@ -65,7 +56,7 @@ 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.. @@ -73,11 +64,11 @@ $ 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 @@ -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 Start up with the given system image file - -H, --home 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 Evaluate - -E, --print Evaluate and display the result - -L, --load Load 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 Run processes on hosts listed in - - -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 Limit usage of cpu features up to ; 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 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 ` |Start up with the given system image file| +|`-H`, `--home ` |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 ` |Evaluate ``| +|`-E`, `--print ` |Evaluate `` and display the result| +|`-L`, `--load ` |Load `` 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 ` |Run processes on hosts listed in ``| +|`-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 ` |Limit usage of cpu features up to ; 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 ` |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://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://samuelcolvin.github.io/JuliaByExample/) - * [Hands-on Julia](https://github.com/dpsanders/hands_on_julia) - * [Tutorial for Homer Reid's numerical analysis class](http://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. diff --git a/doc/src/manual/integers-and-floating-point-numbers.md b/doc/src/manual/integers-and-floating-point-numbers.md index b1295d1ccccf8..80b00927ca0eb 100644 --- a/doc/src/manual/integers-and-floating-point-numbers.md +++ b/doc/src/manual/integers-and-floating-point-numbers.md @@ -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 @@ -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; @@ -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: @@ -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.