The following document is a set of usage examples for the features available in Giterary. They are provided as "suggestions" for how to manage and use the features, but by no means are the extent of how to use the features.

## The Structure of Giterary

The first thing you should know is that Giterary is a wiki, or rather, belongs to a family of computer software that calls themselves "wikis."

### What is a wiki?

A wiki is an application that lets you navigate and edit a web of documents and document references from a single interace. The most famous wiki being "[Wikipedia](http://wikipedia.org)." You may have heard of them.

Wikis are powerful tools because they allow you to efficiently organize and navigate your information while providing multiple users the ability to update and maintain the content.

#### Wikilinks

Wikilinks are a special syntax that you include in the text of your document that allow you to generate a hyperlink to a different document when your original document is rendered.

For example:

\[[ANameOfYourDocument]]

Turns into something like this:

> [[ANameOfYourDocument]]

You can also specify "display" text along with your link, like so:

\[[ANameOfYourDocument|Click here to view my document]]

Which turns into something like this:

> [[ANameOfYourDocument|Click here to view my document]]

Depending on whether that document *exists* (that is, is present in the latest and greatest version of your wiki content), the link may be colored differently. This is to show which pages you can expect to see content from when clicking on them, and if you would expect to create new content when clicking on them.

#### Functional Links

In addition to "wiki"-style links, you can use "functional" linking syntax to generate links that perform functions around Giterary. These involve using a known "prefix" based on Giterary functions, and specifying the parameters that would be used within that link. For instance, determining the "diff" between two commits within Giterary might look like this.

\[[diff:commit_before=HEAD^,commit_after=HEAD,plain=yes|Changes caused by HEAD commit]]

Would render to...

> [[diff:commit_before=HEAD^,commit_after=HEAD,plain=yes|Changes caused by HEAD commit]]

### File Structures and naming

* This is a link to a [[Coulton/Jonathan/Artificial_Heart/Nemeses|test document]] (song lyrics). Note that it is cognizant of the "path" hierarchy, treating path elements as directories, both aesthetically but also stored as such on the backend (useful for organizing documents into sane directory structures).

* The ability to [[move:file=Coulton/Jonathan/Artificial_Heart/Nemeses|move]] documents with relative ease.

### Searching

* Basic search capabilities.

## Dealing with Files in Giterary

### Markdown, and then some

### Tables of Contents

* [[jrhoades/jot/2012/11/14-Wed|Automatic table of contents generation]]

### CSVs

### Collections

### Drafts

* A 10-second timer saves a temporary draft of your edit to the server in the event you lose connectivity. To recover the draft, either return to edit the page you were editing prior, or hit "Drafts" to see a list of unsaved drafts.

### Decorations

* Have the ability to render [[Coulton/Jonathan/Artificial_Heart/All_Songs.collection|collections of documents]], to help with the overall organization of a body of work, and to allow for easy re-ordering without changing the contents of the component documents.

* Similar to annotation highlighting, documents can also detect [[jrhoades/jot/2012/11/17-Sat|dialog-looking text elements and highlight them]].

* Documents can be written and will be rendered by default in [Markdown syntax](http://daringfireball.net/projects/markdown/syntax), however nothing ties you to a specific format. Different syntax engines can be added, as well as default rendering can be overridden to display in alternate formats. See: [[index:file=jrhoades/jot/2012/11/17-Sat,as=text|Plain text]], [[index:file=jrhoades/jot/2012/11/17-Sat&as=wrap|Hard-wrapped plain text]]

### Annotations

* If a [[Coulton/Jonathan/Artificial_Heart/Good_Morning_Tuscon|document is annotated]], it can be read normally by keeping the mouse "out" of the document display area. However, when enabling decorations with the "Decorations" checkbox, the style will change to highlight annotations in yellow, and upon hovering over the annotations, show the annotated comments on the highlighted areas. This is to allow for external comments without necessarily disrupting readability.

### Statistics

* [[stats:file=jrhoades/jot/2012/11/17-Sat|Document Statistics]] (also works on aggregated [[stats:file=Coulton/Jonathan/Artificial_Heart/All_Songs.collection|collection documents]])

## The Wonder World of git

* The ability to view [[history:|global history]], as well as history [[history:file=Home|specific to one or more files]].

* See intuitive, helpful [[diff:commit_before=9b587a7e9accf5adf697903cf740acaf53cbce9b,commit_after=2cbf089170ce780bb6406f226727f05b495192ee|"diff" page]], demonstrating the capabilities of the backend difference engine.

* Building from the "diff," you can also [[cherrypick:commit_before=9b587a7e9accf5adf697903cf740acaf53cbce9b,commit_after=2cbf089170ce780bb6406f226727f05b495192ee|"cherrypick"]] changes (keeping some, discarding others), and use them to build a new version of your document.

* [[Coulton.dir/Jonathan.dir/Artificial_Heart.dir|Directory listings]] to help with navigating document organizational trees.

* A nice feature, though hard to demonstrate here, is that the system supports a very powerful "offline" mode, using the ability of the backend versioning system (Git) to act as a distributed file database. A computer, external to the system and with no local installation of the Giterary tool, can clone the Giterary repository to its filesystem, make edits with a user's favorite text editor, and push them back to the server without a) fear of losing work due to Internet connectivity, or b) having to be concerned with making edits that have to be "shoehorned" back into the main editing system.