From 13cd3c8c0dfc58eec753621139be50fc731b0543 Mon Sep 17 00:00:00 2001 From: "C. Guy Yarvin" Date: Tue, 20 Oct 2015 16:50:53 -0700 Subject: [PATCH 1/3] Various fixes and improvements. --- pub/docs/dev.mdy | 2 +- pub/docs/theory/whitepaper.mdy | 24 ++++++++++++------------ pub/docs/user.mdy | 2 +- pub/docs/user/dojo.mdy | 2 +- pub/docs/user/intro.mdy | 2 +- pub/docs/user/talk.mdy | 29 ++++++++++++++--------------- 6 files changed, 30 insertions(+), 31 deletions(-) diff --git a/pub/docs/dev.mdy b/pub/docs/dev.mdy index ad30e924c..0048e1f79 100644 --- a/pub/docs/dev.mdy +++ b/pub/docs/dev.mdy @@ -20,7 +20,7 @@ internals, but again it helps. But you need to know Hoon. Don't worry, Alas, the developer doc is still under construction. We'll have -more soon, starting with Nock. +more soon. diff --git a/pub/docs/theory/whitepaper.mdy b/pub/docs/theory/whitepaper.mdy index 154ab182f..2fd7b44b9 100644 --- a/pub/docs/theory/whitepaper.mdy +++ b/pub/docs/theory/whitepaper.mdy @@ -6,7 +6,7 @@ sort: 0 Urbit: an operating function ============================ -
This is Urbit whitepaper DRAFT 41K. Some small details +
This is Urbit whitepaper DRAFT 40K. Some small details remain at variance with the codebase.
Abstract @@ -1049,17 +1049,17 @@ is easier than it looks. Languages do need to be read out loud, and the conventional names for punctuation are clumsy. So Hoon replaces them: - ace [1 space] dot . pan ] - bar | fas / pel ) - bis \ gap [>1 space, nl] pid } - buc $ hax # ran > - cab _ ket ^ rep ' - cen % lep ( sac ; - col : lit < tar * - com , lus + tec ` - das - mat @ tis = - den " med & wut ? - dip { nap [ zap ! + ace [1 space] gal < pel ( + bar | gap [>1 space, nl] per ) + bas \ gar > sel [ + buc $ hax # sem ; + cab _ hep - ser ] + cen % kel { soq ' + col : ker } tar * + com , ket ^ tec ` + doq " lus + tis = + dot . pam & wut ? + fas / pat @ zap ! For example, `%=` sounds like "centis" rather than "percent equals." Since even a silent reader will subvocalize, the length diff --git a/pub/docs/user.mdy b/pub/docs/user.mdy index e4d089ae9..930c6bb9b 100644 --- a/pub/docs/user.mdy +++ b/pub/docs/user.mdy @@ -17,7 +17,7 @@ For power users, the [appliance handbook](appliance) explains your apps and how to control them. The [filesystem handbook](clay) explains the Urbit filesystem and how to sync it with Unix. Finally, the [:dojo manual](dojo) and [:talk manual](talk) -reveal the fine points of our shell and messenger respectively. +explore the fine points of our shell and messenger respectively. diff --git a/pub/docs/user/dojo.mdy b/pub/docs/user/dojo.mdy index b497a6c1f..8961885a5 100644 --- a/pub/docs/user/dojo.mdy +++ b/pub/docs/user/dojo.mdy @@ -161,7 +161,7 @@ Every finished line is parsed into one `++dojo-command`: == :: Each kind of `++dojo-command` is an action that depends on one -noun thproduction, a `++dojo-recipe`. We describe first the +noun production, a `++dojo-recipe`. We describe first the commands, then the recipes. ##### `[%show p=dojo-recipe]` diff --git a/pub/docs/user/intro.mdy b/pub/docs/user/intro.mdy index ced46bf51..7bad0a793 100644 --- a/pub/docs/user/intro.mdy +++ b/pub/docs/user/intro.mdy @@ -12,7 +12,7 @@ on a functional operating system, Arvo, written in a strict, typed functional language, Hoon, which compiles itself to a combinator interpreter, Nock, whose spec gzips to 340 bytes. -What is this for? Most directly, Urbit is designed as a +What is Urbit for? Most directly, Urbit is designed as a personal cloud server for self-hosted web apps. It also uses HTTP APIs to manage data stuck in traditional web applications. diff --git a/pub/docs/user/talk.mdy b/pub/docs/user/talk.mdy index f4179699e..e120e2893 100644 --- a/pub/docs/user/talk.mdy +++ b/pub/docs/user/talk.mdy @@ -59,18 +59,18 @@ And hit return. Don't worry, no one but you will see this. The It's boring to post to yourself. Let's join a station: - ~tasfyn-partyv: ;join /urbit-test + ~tasfyn-partyv: ;join /urbit-meta -(`/urbit-test` is a federal station, meaning it's hosted by your +(`/urbit-meta` is a federal station, meaning it's hosted by your star (for `~tasfyn-partyv`, `~doznec`). The `/` notation is just -an abbreviation for `~doznec/urbit-test`.) +an abbreviation for `~doznec/urbit-meta`.) You'll see: - ---------:talk| %porch subscribed to /urbit-test, called `>` - ---------:talk| rules of /urbit-test: + ---------:talk| %porch subscribed to /urbit-meta, called `>` + ---------:talk| rules of /urbit-meta: ---------:talk| test posts only. no shitposting. no pedos/nazis. - ~doznec> ~tasfyn-partyv admitted to %urbit-test + ~doznec> ~tasfyn-partyv admitted to %urbit-meta ~tasfyn-partyv:talk> Notice the character assignment - stations you're subscribed to are @@ -78,7 +78,7 @@ assigned [consistent ASCII glyphs](#-station-glyphs), which you'll see in the log when you hear from these stations, and on the prompt when you're talking to them. -Post a line to `/urbit-test`: +Post a line to `/urbit-meta`: ~tasfyn-partyv:talk> hello, world @@ -86,18 +86,18 @@ You'll see, echoed back at you through `~doznec`: ~tasfyn-partyv:talk> hello, world -And of course, anyone else in `/urbit-test` will see it as well. -But you don't care about `/urbit-test`, so leave it: +And of course, anyone else in `/urbit-meta` will see it as well. +But you don't care about `/urbit-meta`, so leave it: ~tasfyn-partyv:talk> ;leave You'll see: - ---------:talk| %porch has left /urbit-test, called `>` + ---------:talk| %porch has left /urbit-meta, called `>` Everyone else will see: - ~doznec> ~tasfyn-partyv has left %urbit-test + ~doznec> ~tasfyn-partyv has left %urbit-meta Now you're ready to use `:talk` for real! List the federal @@ -140,7 +140,7 @@ glyph. Posts to a station use that station's glyph. You can see a list of glyph bindings with `;what`. Write `;what >` to see what station `>` is bound to, or -`;what /urbit-test` to see if `/urbit-test` has a binding. +`;what /urbit-meta` to see if `/urbit-meta` has a binding. ### Audience selection @@ -157,14 +157,13 @@ Otherwise, the audience is shown in parens: `:talk` works fairly hard to get the audience right and minimize manual switching. But to manually set the audience, the command is simply `;station` - eg, `;~wictuc-folrex` for a direct post; -`/urbit-test` or `~doznec/urbit-test` to post to a federal +`/urbit-meta` or `~doznec/urbit-meta` to post to a federal station, `%mystation` to post to a station on your own ship. For a station bound to a glyph, `;` then the glyph; eg, `;>`. You can post a line and set the audience in one command, eg: -;~wictuc-folrex this is a private message - + ;~wictuc-folrex this is a private message You can configure your audience in a number of ways, which are applied in priority order. From strongest to weakest: From 2587354648b6c3d1ec70b0018432e9f0ce599575 Mon Sep 17 00:00:00 2001 From: "C. Guy Yarvin" Date: Tue, 20 Oct 2015 16:51:50 -0700 Subject: [PATCH 2/3] Moar commit. --- pub/docs/theory/whitepaper.mdy | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pub/docs/theory/whitepaper.mdy b/pub/docs/theory/whitepaper.mdy index 2fd7b44b9..562423284 100644 --- a/pub/docs/theory/whitepaper.mdy +++ b/pub/docs/theory/whitepaper.mdy @@ -1,5 +1,5 @@ --- -title: Urbit Whitepaper +title: Urbit whitepaper sort: 0 --- From 01e3ac5537ab35adaaad547aaa050b9df84b654f Mon Sep 17 00:00:00 2001 From: "C. Guy Yarvin" Date: Wed, 21 Oct 2015 10:39:19 -0700 Subject: [PATCH 3/3] Various fixes and improvements. --- pub/docs/user/dojo.mdy | 160 ++++++++++++++++++++++------------------ pub/docs/user/start.mdy | 33 ++++----- pub/docs/user/talk.mdy | 70 +++++++++--------- 3 files changed, 139 insertions(+), 124 deletions(-) diff --git a/pub/docs/user/dojo.mdy b/pub/docs/user/dojo.mdy index 8961885a5..39266ae72 100644 --- a/pub/docs/user/dojo.mdy +++ b/pub/docs/user/dojo.mdy @@ -6,39 +6,42 @@ next: true # `:dojo` manual -The dojo is a typed functional shell. Its prompt is: +The dojo is a typed functional shell. Assuming our default +plot `~fintud-macrep`, - ~urbit-name:dojo> +Its prompt is: + + ~fintud-macrep:dojo> ## Quickstart To print a Hoon expression or other recipe: - ~urbit-name:dojo> (add 2 2) + ~fintud-macrep:dojo> (add 2 2) To save a recipe as a variable `foo`: - ~urbit-name:dojo> =foo (add 2 2) + ~fintud-macrep:dojo> =foo (add 2 2) To save as a unix file (`$pier/.urb/put/foo/bar.baz`): - ~urbit-name:dojo> .foo/bar/baz (add 2 2) + ~fintud-macrep:dojo> .foo/bar/baz (add 2 2) To save as an urbit file (`/===/foo/bar/baz`): - ~urbit-name:dojo> *foo/bar/baz (add 2 2) + ~fintud-macrep:dojo> *foo/bar/baz (add 2 2) A noun generator with ordered and named arguments: - ~urbit-name:dojo> +make one two three, =foo (add 2 2), =bar 42 + ~fintud-macrep:dojo> +make one two three, =foo (add 2 2), =bar 42 A poke message to an urbit daemon: - ~urbit-name:dojo> :~urbit-name/talk (add 2 2) + ~fintud-macrep:dojo> :~fintud-macrep/talk (add 2 2) A system command to `:hood`: - ~urbit-name:dojo> |reload %vane + ~fintud-macrep:dojo> |reload %vane ## Manual @@ -52,10 +55,18 @@ applies this product in a side effect -- show, save, or send. ### Theory -The dojo is not just a Hoon interpreter. Hoon is a purely -functional language; dojo recipes are *conceptually* functional, -but they often use concrete actions or interactions. A simple -Hoon expression is only one kind of recipe. +In the quickstart we learned a crude interpretation of the dojo +in terms of "expressions, generators and operations." While +nothing in the quickstart section is inaccurate, it's not the way +the system works internally. + +*All* dojo lines are commands. An operation uses a *recipe* +to create a noun, which the command uses in its side effect. +Just printing the noun is a trivial case of a command. + +Recipes are *conceptually* functional, but often use concrete, +stateful action sequences. A simple Hoon expression (*twig*) is +purely functional, but it's only one kind of recipe. A recipe can get data from an HTTP GET request or an interactive input dialog. It can also query, even block on, the Urbit @@ -71,7 +82,8 @@ network. And each session's state is independent. (If you want to work on two things at a time, connect two console sessions to your dojo.) -Once you've built your product noun, you show, save, or send it. +Once you've built the product of your recipe, you show, save, +or send it. You can pretty-print the product to the console. You can save it -- as a dojo variable, as a revision to the Urbit filesystem, or @@ -84,19 +96,19 @@ language, but the dojo is a dynamic interpreter. The nouns you build in the dojo are dynamically typed nouns, or "cages". A cage actually has two layers of type: "mark," a network label -(like a MIME type), and "range," a Hoon language type. When a +(like a MIME type), and "span," a Hoon language type. When a cage is sent across the Urbit network, the receiving daemon validates the noun against its own version of the mark, and -regenerates the range. +regenerates the span. Of course, sometimes a recipe produces a noun with mark `%noun`, -meaning "any noun," and range `*`, the set of all nouns. We have +meaning "any noun," and span `*`, the set of all nouns. We have no choice but to do the best we can with mystery nouns, but we prefer a formal description. -Marks let us perform a variety of formal typed operations on -nouns: validation of untrusted data, format conversion, even -patch and diff for revision control. +A mark is also called a "format." Marks let us perform a variety +of formal typed operations on nouns: validation, translation, +even patch and diff for revision control. ### Other resources @@ -112,20 +124,20 @@ of it as pseudocode -- the meaning should be clear from context. To use the dojo, type a complete command at the dojo prompt. The simplest command just prints a Hoon expression: - ~urbit-name:dojo> (add 2 2) + ~fintud-macrep:dojo> (add 2 2) Hit return. You'll see: > (add 2 2) 4 - ~urbit-name:dojo> + ~fintud-macrep:dojo> Similarly in tall form, - ~urbit-name:dojo> %+ add 2 2 + ~fintud-macrep:dojo> %+ add 2 2 > %+ add 2 2 4 - ~urbit-name:dojo> + ~fintud-macrep:dojo> An incomplete command goes into a multiline input buffer. Use the up-arrow (see the console history section) to get the last @@ -133,14 +145,14 @@ command back, edit it so it's just `%+ add 2`, and press return. You'll see: > %+ add 2 - ~urbit-name/dojo< + ~fintud-macrep/dojo< Enter `2`. You'll see: > %+ add 2 2 4 - ~urbit-name/dojo> + ~fintud-macrep/dojo> The full command that parses and runs is the concatenation of all the partial lines, with a space inserted between them. To clear @@ -168,20 +180,20 @@ commands, then the recipes. To print the product, the command is just the recipe: - ~urbit-name:dojo> (add 2 2) + ~fintud-macrep:dojo> (add 2 2) ##### `[%verb p=term q=dojo-recipe]` To save the product to a variable `foo`: - ~urbit-name:dojo> =foo (add 2 2) + ~fintud-macrep:dojo> =foo (add 2 2) `foo` goes into your Hoon subject (scope) and is available to all expressions. To unbind `foo`: - ~urbit-name:dojo> =foo + ~fintud-macrep:dojo> =foo The dojo has a set of special variables, some read-write and some read-only: `dir`, `lib`, `arc`, `now`, `our`. @@ -203,17 +215,17 @@ filesystem paths.) To save: - ~urbit-name:dojo> *%/numbers/four (add 2 2) + ~fintud-macrep:dojo> *%/numbers/four (add 2 2) To edit: - ~urbit-name:dojo> -%/numbers/four (add 2 2) + ~fintud-macrep:dojo> -%/numbers/four (add 2 2) A save (`*`) overwrites the current (if any) version of the file with a new version of any mark. The save command above will work (if you want `/numbers/four` at your current path). -An edit (`-`) produces a diff whose mark has to match the diff +An edit (`-`) applies a diff whose mark has to match the diff mark for the current version of the file. The edit command above will not work, because evaluating a Hoon expression like `(add 2 2)` just produces a `%noun` mark, ie, an arbitrary noun. @@ -225,48 +237,49 @@ change since the version specified, the command will fail. ##### `[%unix p=path q=dojo-recipe]` - ~urbit-name:dojo> ./numbers/four (add 2 2) + ~fintud-macrep:dojo> ./numbers/four (add 2 2) The product is saved as a Unix file (its mark is translated to MIME, and the MIME type is mapped as the extension). ##### `[%poke p=goal q=dojo-recipe]` -A poke is a one-way transactional request. It either succeeds -and returns no information, or fails and produces an error dump. +A poke or *order* is a one-way transactional request. It either +succeeds and returns no information, or fails and produces an +error dump. -Every poke is sent to one daemon on one urbit. The default urbit -is your urbit. The default daemon is the system daemon, `:hood`. -The following syntactic forms are equivalent: +Every order is sent to one daemon on one urbit. The default +urbit is your urbit. The default daemon is the system daemon, +`:hood`. The following syntactic forms are equivalent: - ~urbit-name:dojo> :~urbit-name/hood (add 2 2) - ~urbit-name:dojo> :hood (add 2 2) - ~urbit-name:dojo> :~urbit-name (add 2 2) - ~urbit-name:dojo> : (add 2 2) + ~fintud-macrep:dojo> :~fintud-macrep/hood (add 2 2) + ~fintud-macrep:dojo> :hood (add 2 2) + ~fintud-macrep:dojo> :~fintud-macrep (add 2 2) + ~fintud-macrep:dojo> : (add 2 2) Urbit pokes do not have a separate verb. The mark of the message defines the semantics of the operation. You don't call a method `foo` whose argument is a noun in mark `bar` -- you poke a noun in mark `bar`. The mark is the protocol is the method. -If the poke succeeds, you'll see an `>=` line. If not, you'll +If the order succeeds, you'll see an `>=` line. If not, you'll see an error report, typically with a stack trace. It's common (but not necessary) to use a custom generator for the daemon you're talking to. (For generators, see below.) Hence - ~urbit-name:dojo> :~urbit-name/fish +fish/catch (add 2 2) + ~fintud-macrep:dojo> :~fintud-macrep/fish +fish/catch (add 2 2) It's irritating to type "fish" twice, just because we're using a fish generator to talk to a fish daemon. Hence a shortcut: - ~urbit-name:dojo> :~urbit-name/fish|catch (add 2 2) + ~fintud-macrep:dojo> :~fintud-macrep/fish|catch (add 2 2) If we combine all these defaults, we get the "system command" shortcut: - ~urbit-name:dojo> :~urbit-name/hood +hood/reload %ames - ~urbit-name:dojo> |reload %ames + ~fintud-macrep:dojo> :~fintud-macrep/hood +hood/reload %ames + ~fintud-macrep:dojo> |reload %ames This is the most common poke, a generated message to your own hood. @@ -275,11 +288,11 @@ hood. The Web has its own poke, unfortunately in two flavors. To POST, - ~urbit-name:dojo> +http://website.com (add 2 2) + ~fintud-macrep:dojo> +http://website.com (add 2 2) To PUT: - ~urbit-name:dojo> -http://website.com (add 2 2) + ~fintud-macrep:dojo> -http://website.com (add 2 2) As with a poke, you'll get a >= for success, or an error report. @@ -289,7 +302,7 @@ But wait, what's a recipe? Simplifying the actual code slightly: ++ dojo-recipe :: functional build $% [%ex p=twig] :: hoon expression - [%as p=mark q=dojo-recipe] :: conversion + [%as p=mark q=dojo-recipe] :: format conversion [%do p=twig q=dojo-recipe] :: apply gate [%ge p=dojo-script] :: generator [%ur p=purl] :: get url @@ -317,7 +330,9 @@ A twig produces the trivial mark `%noun`, except in two cases where the dojo can do better. The dojo analyzes the twig to detect two trivial cases where direct evaluation gives us a mark: a variable reference like `foo` that matches a dojo variable, or -an urbitspace dereference like `.^(/cx/~urbit-name/main/1/foo)`. +an urbitspace dereference like `.^(/cx/~fintud-macrep/main/1/foo)`. +In either case, if we executed these through Hoon, we'd get the +same noun with the same span. ##### `[%tu p=(list dojo-recipe)]` @@ -340,7 +355,7 @@ arguments are recipes. The path specifies a Hoon source file in For the path `/fun/make`, the ordered arguments `1`, `2` and `3`, and the named arguments `foo` and `bar`, the syntax is: - ~urbit-name:dojo> +fun/make 1 2 3, =foo (add 2 2), =bar 42 + ~fintud-macrep:dojo> +fun/make 1 2 3, =foo (add 2 2), =bar 42 Unless this non-closed form is the end of a command, it needs to be surrounded by `[]` to make it play well with others. @@ -360,8 +375,8 @@ recipe, we can chain them to make a conversion pipeline. To convert a recipe, just precede it with the converison form, `&mark`: - ~urbit-name:dojo> &noun (add 2 2) - ~urbit-name:dojo> &md (add 50 7) + ~fintud-macrep:dojo> &noun (add 2 2) + ~fintud-macrep:dojo> &md (add 50 7) ##### `[%do p=twig q=dojo-recipe]` @@ -369,8 +384,8 @@ To convert a recipe, just precede it with the converison form, `&mark`: Its syntax is a hoon expression preceeded by `_`: - ~urbit-name:dojo> _lore 'hello\0aworld' - ~urbit-name:dojo> _|=(a=@ (mul 3 a))} (add 2 2) + ~fintud-macrep:dojo> _lore 'hello\0aworld' + ~fintud-macrep:dojo> _|=(a=@ (mul 3 a))} (add 2 2) ##### `[%ur p=purl]` @@ -410,7 +425,7 @@ if the user specifies `=foo 42`, your `opt` is replaced with Bear in mind that dojo syntax is list-centric, so your `arg` will always end with a `~`. For instance, - ~urbit-name/dojo> +fun/make 1 2 3 + ~fintud-macrep/dojo> +fun/make 1 2 3 will generate an `arg` of `[1 2 3 ~]`. Yes, this is the only place in Urbit where we do list-centric arguments. @@ -418,27 +433,21 @@ place in Urbit where we do list-centric arguments. Note also that script configuration is typed. The user's command will fail if there's a type mismatch. But `arg` does not have to be a homogeneous list -- just a tuple with `~` on the end. Also, -you can use `arg=*` and sort out the nouns by hand. - -You can also use `*` anywhere if you're not interested in the -system context, or in +you can use `arg=*` and sort out the nouns by hand. Any value +you don't care about can simply be `*`. #### Generators -There are three kinds of generators: builders (with no special -I/O), dialogs (which read console input), and scrapers (which -pull data from the webs). Any generator can use `.^` to both -read from and block (wait for remote or delayed results) on -the Urbit global namespace. +There are four kinds of generators: builders (with no special +I/O), dialogs (which read console input), scrapers (which pull +data from the webs), and synthesizers (which produce another +generator). Any generator can use `.^` to both read from and +block (wait for remote or delayed results) on the Urbit global +namespace. A generator produces a cell whose tail is the configuration gate, -and whose head is either `%say` for a builder, `%ask` for a -dialog, or `%get` for a scraper. - -(If you want to write one generator which both prompts the user -and scrapes the web, don't. Write two, and configure the second -with the result of the first. We pay a price for keeping things -stupid.) +and whose head is `%say` for a builder, `%ask` for a dialog, +`%get` for a scraper, and `%con` for a constructor. #### Builders @@ -522,3 +531,8 @@ A scraper is much like a dialog, except instead of `sole-lo` and `++sole-at` takes a `purl` request url, and a gate through which to slam the result `httr`. + +#### Synthesizer + +A synthesizer simply produces another recipe. Its + diff --git a/pub/docs/user/start.mdy b/pub/docs/user/start.mdy index 5a35ca459..1e0cd27ac 100644 --- a/pub/docs/user/start.mdy +++ b/pub/docs/user/start.mdy @@ -6,8 +6,7 @@ next: true # Quickstart -To start your already-launched urbit, run with the pier name -(we'll call it `$PIER`): +To start your already-launched urbit, run with `$PIER`: urbit fintud-macrep urbit mycomet @@ -48,8 +47,8 @@ You'll see: ### Dojo expressions, generators and operators `:dojo` is of course a command-line REPL or shell. But it -remains functional in spirit. There are three kinds of `:dojo` -commands: expressions, generators, and operators. +remains functional in spirit. To simplify a little, there are +three kinds of `:dojo` lines: expressions, generators, commands. Dojo *expressions* are like `(add 2 2)` -- they simply compute and print a value, without any side effects, from a twig of Hoon. @@ -60,22 +59,22 @@ fact, GET requests are one data source for generators. Others include the Urbit namespace, prompting the user, etc. A generator command line always starts with `+`, as in `+ls`. -Operators are all other commands. Lines normally start with `|`, -as in `|mount %`, or `:`, as in `:hood +hood/mount %`. The +Commands are all other lines. Command lines normally start with +`|`, as in `|mount %`, or `:`, as in `:hood +hood/mount %`. The latter is just an abbreviation for the former. -An operator command is always a *poke* to some local or remote -appliance. A poke is a transactional message: like a -request-response pair, but a success response is empty. -A failure response is a stacktrace or other error dump. +A command is generally an *order* to some local or remote +appliance. An order is a transactional message: like a +request-response pair, but a success response is empty, whereas a +failure contains an error report. -So operator commands have no output unless they fail. If they -fail, they print an error trace. If they succeed, they just -print a demure `>=`. +Orders have no output unless they fail. If they fail, they print +an error trace. If they succeed, they just print a demure `>=`, +confirming that the receiving appliance did as it was told. For instance, in Unix, the `rm` and `ls` commands both run a -process. In Urbit, `|rm` is an operator command; it changes your -filesystem. `+ls` is a generator command; it produces a value. +process. In Urbit, `|rm` is a command; it changes your +filesystem. `+ls` is a generator; it produces a value. ## Converse: your `:talk` appliance @@ -144,9 +143,9 @@ All planets, stars and galaxies are exposed to the web at `planet.urbit.org`. (This should work via a direct DNS binding, but at present uses a central proxy, so use it gently.) -In a last resort, Urbit's own official planet `~winsen-pagdel` is +In a last resort, Urbit's own official planet `~magwyd-lorsug` is also bound to just plain `urbit.org`, and hosts the public docs -here. Always trust content from `~winsen-pagdel`! +here. Always trust content from `~magwyd-lorsug`! But assuming it's `localhost:8080`, the Urbit docs are at diff --git a/pub/docs/user/talk.mdy b/pub/docs/user/talk.mdy index e120e2893..16759a016 100644 --- a/pub/docs/user/talk.mdy +++ b/pub/docs/user/talk.mdy @@ -41,37 +41,41 @@ active Urbit stars cooperate to federate, manage and mirror a collectively-managed namespace, very like Usenet. These "federal" stations are generally public-access boards. +Right now, the only public federal station is `urbit-meta`. +Because the party always starts in the kitchen. + ## Quickstart Let's post something! At the default `:talk` prompt - ~tasfyn-partyv:talk: + ~fintud-macrep:talk() type the message: - ~tasfyn-partyv:talk: hello, world. + ~fintud-macrep:talk() hello, world. And hit return. Don't worry, no one but you will see this. The `:` means you're posting to yourself. You'll get the post: - ~tasfyn-partyv: hello, world. - ~tasfyn-partyv:talk: + ~fintud-macrep: hello, world. + ~fintud-macrep:talk() It's boring to post to yourself. Let's join a station: - ~tasfyn-partyv: ;join /urbit-meta + ~fintud-macrep: ;join /urbit-meta (`/urbit-meta` is a federal station, meaning it's hosted by your -star (for `~tasfyn-partyv`, `~doznec`). The `/` notation is just +star (for `~fintud-macrep`, `~doznec`). The `/` notation is just an abbreviation for `~doznec/urbit-meta`.) You'll see: ---------:talk| %porch subscribed to /urbit-meta, called `>` ---------:talk| rules of /urbit-meta: - ---------:talk| test posts only. no shitposting. no pedos/nazis. - ~doznec> ~tasfyn-partyv admitted to %urbit-meta - ~tasfyn-partyv:talk> + ---------:talk| don't be rude + ---------:talk| urbit-meta is politically correct and safe for work + ~doznec= ~fintud-macrep admitted to %urbit-meta + ~fintud-macrep:talk= Notice the character assignment - stations you're subscribed to are assigned [consistent ASCII glyphs](#-station-glyphs), which you'll @@ -80,16 +84,16 @@ when you're talking to them. Post a line to `/urbit-meta`: - ~tasfyn-partyv:talk> hello, world + ~fintud-macrep:talk= hello, world You'll see, echoed back at you through `~doznec`: - ~tasfyn-partyv:talk> hello, world + ~fintud-macrep:talk= hello, world And of course, anyone else in `/urbit-meta` will see it as well. But you don't care about `/urbit-meta`, so leave it: - ~tasfyn-partyv:talk> ;leave + ~fintud-macrep:talk= ;leave You'll see: @@ -97,13 +101,13 @@ You'll see: Everyone else will see: - ~doznec> ~tasfyn-partyv has left %urbit-meta + ~doznec= ~fintud-macrep has left %urbit-meta Now you're ready to use `:talk` for real! List the federal groups currently available with - ~tasfyn-partyv:talk> ;list + ~fintud-macrep:talk= ;list For general discussion about Urbit, we recommend `/urbit-meta`. @@ -148,22 +152,22 @@ Audience selection is important in a multiplexed communicator! The audience is always shown in your prompt. If there's a glyph for it, it's shown as the glyph: - ~tasfyn-partyv:talk> + ~fintud-macrep:talk= Otherwise, the audience is shown in parens: - ~tasfyn-partyv:talk(~wictuc-folrex) + ~fintud-macrep:talk(~dannum-mitryl) `:talk` works fairly hard to get the audience right and minimize manual switching. But to manually set the audience, the command -is simply `;station` - eg, `;~wictuc-folrex` for a direct post; +is simply `;station` - eg, `;~dannum-mitryl` for a direct post; `/urbit-meta` or `~doznec/urbit-meta` to post to a federal station, `%mystation` to post to a station on your own ship. For a station bound to a glyph, `;` then the glyph; eg, `;>`. You can post a line and set the audience in one command, eg: - ;~wictuc-folrex this is a private message + ;~dannum-mitryl this is a private message You can configure your audience in a number of ways, which are applied in priority order. From strongest to weakest: @@ -189,13 +193,13 @@ between source and content. The conventional example is a URL. When you post a URL: - ~tasfyn-partyv:talk> http://foobar.com/moo/baz + ~fintud-macrep:talk= http://foobar.com/moo/baz This will appear in the flow as: - ~tasfyn-partyv>_foobar.com + ~fintud-macrep>_foobar.com -meaning that `~tasfyn-partyv` posted a link to `foobar.com`, +meaning that `~fintud-macrep` posted a link to `foobar.com`, on the station or conversation whose glyph is `>`. The effect of activating a post depends on the post. For a link, @@ -229,15 +233,15 @@ offline. Use the `;nick` command to assign or look up nicknames. `;nick` with no arguments lists all nicknames; `;nick -~tasfyn-partyv` looks up a nickname; `;nick curtis` searches in -reverse; `;nick ~tasfyn-partyv curtis` creates a nickname. +~fintud-macrep` looks up a nickname; `;nick plato` searches in +reverse; `;nick ~fintud-macrep plato` creates a nickname. All nicknames must be 14 characters or less, lowercase. Of course, nicknames are strictly local - like the names on entries in a phonebook. Sometimes in a post you want to mention -someone you know by a nickname. Just type `~curtis`, and `:talk` -will replace it magically with `~tasfyn-partyv` (or beep if no -`~curtis` is bound). +someone you know by a nickname. Just type `~plato`, and `:talk` +will replace it magically with `~fintud-macrep` (or beep if no +`~plato` is bound). ### Presence @@ -252,8 +256,7 @@ lists everyone in that station. If one or more urbits in your audience is typing, `:talk`'s presence system will detect it and change the prompt: - ~tasfyn-partyv [~wictuc-folrex...]> - + ~fintud-macrep [~dannum-mitryl...]= ### Creating and managing stations @@ -266,22 +269,21 @@ To create your own mailbox, party, journal or board: etc. Every form of station has an exception list; to block -`~wictuc-folrex` from your default mailbox `%porch`, +`~dannum-mitryl` from your default mailbox `%porch`, - ;block %porch ~wictuc-folrex + ;block %porch ~dannum-mitryl To invite people to `%myfunparty`: - ;invite %myfunparty ~wictuc-folrex, ~sondel-forsut + ;invite %myfunparty ~dannum-mitryl, ~lagret-marpub To ban from `%bizarre-board`: - ;banish %bizarre-board ~wictuc-folrex + ;banish %bizarre-board ~dannum-mitryl To appoint a coauthor of `%serious-journal`: - ;author %serious-journal ~sondel-forsut - + ;author %serious-journal ~lagret-marpub #### Station glyphs