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

TODO

* 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

TODO

* Basic search capabilities.

## Dealing with Files in Giterary

There are some things to know about dealing with files within Giterary.

### File extensions

If a file has an extension (*MyFile.txt*, *MyTable.csv*, *MyNotes.md*, etc.) that extensions handling (as determined by Giterary) will be used by default when displaying the page (*txt* or *text* for purely textual documents, *md* or *markdown* for Markdown syntax documents, *csv* for Comma Separated Values formatted files, and so on).

For files with no extension (*Chapter1*, *01-Wednesday*, *HelpFile*) a default renderer is chosen, and that renderer is configured to be the Markdown renderer by default.

You can also override the renderer by specifying different "as=someextensionname" on the URL of a document. This is useful for rendering something as its underlying source code (*as=text*), readable text (*as=wrap*). For instance, this document as:

* [[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]]

### Markdown, and then some

[Markdown syntax](http://daringfireball.net/projects/markdown/syntax) is a useful way to write without having to worry about syntax.

To quote the author:

> *Markdown is intended to be as easy-to-read and easy-to-write as is feasible.*

> *Readability, however, is emphasized above all else. A Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions.*

This usage document is written in Markdown format. You can view its contents by selecting **Other Options > ...Readable Text** when displayed in Giterary.

There are many great features to Markdown for document formatting. It is highly recommended you familiarize yourself with its function.

**Additional Note**: One of Markdown's features is that it will allow HTML tags to be embedded within it (to provide features that Markdown can't provide). Giterary supports this "HTML pass-through," however, only for a limited subset of HTML (for security reasons).

### Decorations

* SimilarIn addition to annotation highlighting, documents can also detect [[jrhoades/jot/2012/11/17-Sat|dialog-looking text elementsthe formatting provided by Markdown syntax and highlight them]].other HTMl formatting tags, Giterary also provides additional "decorations" to a document. These decorations are "hidden" by default, but are present in the Giterary interface by selecting the "Decorations" checkbox at the top of a document display, or by hitting the letter "d."

###* Annotations

#### Annotations

Annotations in documents are ways to highlight and provide notes to a document without necessarily changing it. This is useful for editing and document feedback, providing additional information for other authors, or being able to refer to other portions of your Giterary repository without disrupting the document's readability.

**Note**: Annotations are "hidden" by default, and only appear when you enable decorations. If you are browsing from Giterary, hit the "Decorations" button at top, or hit "d" to enable the examples below.

<annotate>This text is annotated.<comment>This text is "annotating" the original text.</comment></annotate>

Renders to this:

> <annotate>This text is annotated.<comment>This text is "annotating" the original text.</comment></annotate>

Note that with the above syntax, you need not put the "comment" tags at the end of the "annotate" content.

There is also a simplified syntax for this that allows you to provide minimally disruptive annotation syntax in your content, and specify your annotation text either explicitly next to the annotate or later in the document (allowing for a "reference" section, similar to the Markdown feature of allowing the definition of a URL to be apart from its usage.

\{The quick brown fox jumped over the lazy dog.}(This is my note.)

...or...

\{The quick brown fox jumped over the lazy dog}[referencetag]

...and elsewhere in the document...

\{reference_tag}: This is my note.

Would generate the following:

> {This is some annotated text.}(This text is annotating)

> ...or...

> {This is some annotated text.}[referencetag]

{referencetag}: This text is annotating.

### Tables of Contents

Giterary takes it upon itself to create a table of contents based on the elements within your documents. In Markdown, if you have a line that looks like this:

Header Title

------------

...or like this...

Header Title

============

...or like this...

## Header Title

...you have specified that there should be a "header" element with the text *Header Title*. This will generate the appropriate HTML element (the h1, h2, h3, h4, h5, or h6 tags) according to the "level" of header. Refer to the Markdown syntax documentation for more complex header generation.

Each of these header elements are then detected by Giterary upon rendering, and can be turned into "bookmarks" as part of an automatically generated table of contents. Depending on your screen geometry (window width of your browser), this table of contents will appear either at the top of your document, or to the right of your document.

Giterary makes one departure from Markdown's normal "header" output, in that it treats the h6 (header level 6) elements differently. Rather than displaying h6 elements like the rest of the headers, they will be invisible, but still be treated as "bookmarking" elements. With this, you can treat h6 headings as invisible placemarkers within larger documents. This is useful if you want to maintain bookmarks within a document, but not disrupt the formatting of the document with headings.

For example:

###### This is a hidden heading

Will generate a *This is a hidden heading* table of contents item, but not render within the document (as you should not see below)

###### This is a hidden heading

* [[jrhoades/jot/2012/11/14-Wed|Automatic tableAs part of contents generation]]the decorations functionality, enabling decorations on a document with invisible headings will display the headings at their position within the document.

### CSVs

### Collections

* 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.

### 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.

### 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.