# So, What's All This, Then?

So, you know what a wiki is, right? It's one of those, with a few
little twists. I'll walk through by doing:

# Just A Wiki

The data model of a wiki is basically that you have some kind of
rich text structure—so you have some formatting primitives, like
bolding or lists or whatnot—as well as the notion of _links_,
which are references to other pages which you can follow. Each
link references a page—or, sometimes, a point within a page—but
each page is basically that.

Commonplace has a bit more structure. It refers to pages as
_scraps_, for reasons we'll see in just a little bit. You
create a new scrap and use Commonplace's mildly idiosyncratic,
LaTeX-inspired markup language to write a page:

~~~~
\strong{Welcome} to this new page! We can link to an outside
page like so: \link{http://gdritter.com|my home page}.
We can also link to \there{foo|a wiki page that doesn't exist}.
~~~~

That link will render a different color to indicate that it's a
_broken_ link, as the page it references doesn't yet exist. If
we follow it, we'll have the opportunity to create that page.

~~~~
This is now our \em{Foo} page.
~~~~

Okay, now that we've done that, we can go back and notice that
the link color has changed: we can click on it and it'll take
us to our newly created _foo_ page. There's a little twist on what
Commonplace allows us to do, though. Let's change the initial
page a little bit:

~~~~
\strong{Welcome} to this new page! We can also link to
\link{foo|another page}. However, we can also do this:

\here{foo}
~~~~

If we look at the page now: look! The entirety of the _foo_ scrap
is now _embedded_ within the larger scrap. We don't just link, we
also _compose_ scraps into larger pages. We can do this to a greater
depth, too:

[image here]

although there is a cut-off depth. Commonplace is also aware of
recursive pages, and will be intelligent about representing them:

[image here]

# Transparent Editing

Now let's try something a little different:

~~~~
This is an outer page.

\page {
  This is an inner page.
}
~~~~

Now when we render this, we get this:

[image here]

Notice how we wrote a single page, but when we view it, it appears
to be a scrap embedded within another! What has happened is Commonplace
understands the `\page { ... }` construct to mean, "Create a new scrap
and embed it directly here." This means that we can still have a finer,
more granular structure but without you having to edit all the scraps
individually. The editing view gives you the ability to select a deeper
view (which lets you edit embedded scraps inline) or a shallower view
(which lets you see the `here {...}` references.)

This could be useful in paper-editing: you can write your paper with each
subsection in its own `\page { ... }` block, but later can rearrange
those subsections by switching to a higher-level editing view and then
rearranging the `\here { ... }` references.

# Deeper Structure

All the above pages have been unstructured text, but Commonplace also
understands _structured_ scraps. We've actually already seen one, but
haven't realized it: the `\link { ... }` element. That appeared to be
a markup element, but behind-the-scenes, links work like embedded
`\page { ... }` elements, storing their contents in a separate
scrap. Notice that links have two parts: the actual URL and the
description text.

~~~~
An external link to \link{http://www.example.com|an example site}.
~~~~

This implies that we can, like scraps, edit a link _individually_,
outside of the context of the page in which it appears. And if we do:

[image here]

It has a separate _named_ field for each part of the link. If we
modify it here, we can see the changes appear back in the page where
we used that link:

[image here]

This can give us tremendous flexibility: if we use a link throughout
our wiki, but the site to which we're linking goes down, we can
transparently replace the link everywhere it appears with an
[Internet Archive version] of the same thing.

Links are only one kind of type, and one with relatively little
structure. A good example of a more deeply-structured type is a