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.
Giterary Components
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 interface. The most famous wiki being “Wikipedia.” 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. They vary in ubiquity and in features, given special use cases, extensibility, and popularity. Giterary’s wiki features are inspired largely by Mediawiki and MoinMoin (both excellent examples of full featured and extensible wiki software).
File Structures and naming
Giterary employs a hierarchical structure to its file naming conventions, allowing for the user to organize their file content in logical folder structures while being relatively lax with regards to file name formats (compared to other wikis).
Naming Files
File names can include almost any normal filesystem character (alphanumerics, slash, underscore, spaces) minus a colon (":"), solidus ("/"), and non-printing characters.
Like files on your computer, all files exist within directories. You can choose to operate without directories, but this guide recommends you take advantage of this feature in order to organize your content.
All files can be referenced using a file path. This file path refers to the “path” one must traverse through the directory structure of your Giterary repository in order to get to your actual file. Examples would be like the following:
Home (the "home page" for your wiki)
bobby (the "user page" for the user "bobby")
My Story/Chapters/Chapter1 (Chapter 1 of many chapters of "MyStory")
bobby/jot/2013/01/19-Sat (user bobby's "jot" for 2013/01/19)
Files, Directories, and “Dirification”
There comes a dilemma when creating a hierarchical wiki document naming scheme.
Let’s say you have a directory structure like this:
My Story/Chapters/Chapter 1
My Story/Chapters/Chapter 1/Notes
My Story/Chapters/Chapter 1/Citations
The question becomes: What type of object is the thing called Chapter 1?
Chapter 1 is certainly a file, but it’s referred to in the paths to Notes and Citations as a directory path component.
Giterary solves this problem with the concept of “directorification” or “dirification.” It is an abuse of file paths to make it seem like Chapter 1 is both a file and a directory. By way of “dirification” Giterary will treat the following two file paths as equivalently referencing the exact same file:
My Story/Chapters/Chapter 1/Notes
My Story.dir/Chapters.dir/Chapter 1.dir/Notes
In the first file path, it is implied that the path components My Story, Chapters, and Chapter 1 have the suffix “.dir” appended to them because they are being treated as a directory. In the second file path, the “.dir” suffixes are explicit, but refer to the true, “dirified” path.
In this way, there can still be two objects with the “same name,” but only by a quick sleight of hand on Giterary’s part. In this way, you can ask to edit My Story/Chapters/Chapter 1 and My Story/Chapters/Chapter 1/Notes and have it do the right thing.
Creating New Files and Directories
Per wiki software convention, the most common way to create a new file is to edit an existing one with a link to the new page, and then navigating to that link. Giterary tries to adopt this convention, erring on the side of good organizational structure rather than simplicity of just creating a new file. That said, there is nothing to stop a user from just looking at the URL of the file referenced in their browser window and change it to their desired new filename.
An alternate route exists, however: if you browse to any directory, a text input is available, pre-populated with a data structure relevant to the currently viewed directory, and something akin to NewFile appended at the end. This will allow you to easily create files under known directory structures.
Additionally, one can hit the “Jot” button when logged in, which immediately puts the user in the editor for a file that is date-stamped to the current date. This is another way to quickly write in a new file while retaining some information about when that file was created.
A final note on creating new files: if a new file references a path component that does not exist, when finally committing that file Giterary will create all necessary directories in order to place that file on the path specified. For instance, in a blank repository, edits and submits the file “My Story/Chapters/Chapter 5/Notes” it will create the following directories:
My Story.dir
My Story.dir/Chapters.dir
My Story.dir/Chapters.dir/Chapter 5.dir
File structures can be moved and deleted, so mistakes made during this process are not the end of the world.
Searching
The search bar at top left can search on both file name, file path, and file contents. The search page will indicate the type of match next to the search results.
Types of Objects within Giterary
There are some things to know about dealing with files, directories, and navigating them within Giterary.
File types are determined by extension
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. See later in this document for explanations of Markdown.
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:
Directories are for browsing
On every document, there is a tab called “Directory” that will go to a page listing the contents of the directory with that document’s same “dirified” name. For instance, viewing My Story and clicking on “Directory” will list anything under the directory called My Story.dir.
This is useful for navigation your organizational document structures.
Document Decorations
In addition to the formatting provided by Markdown syntax and 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.”
The decorations currently available are:
- Annotations (described in the Editing section)
- Dialog highlighting (described in the Editing section)
- Invisible headings (these will be described in the Table of Contents section).
Document Tables of Contents
Giterary takes it upon itself to create a table of contents based on the elements within your documents. These help to navigate within documents (particularly in the case of large documents). In Markdown format, 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
As part of the decorations functionality, enabling decorations on a document with invisible headings will display the headings at their position within the document.
Comma Separated Values Files (*.csv files)
A CSV file (Comma Separated Value) file is a file whose content consists of tabular data stored in a text document, with line of text representing a “row” of data, and different columns specified by a list of fields, separated by commas.
For example:
Year,Month,'Day of Month',Note
2013,01,18,'Today I drank beer. Perhaps I drank too much.'
2013,01,19,'Today I drank tea. It's not the same as coffee.'
These files will be rendered as dynamic tables within your document, like so:
| Year | Month | Day of Month | Note |
|---|---|---|---|
| 2013 | 01 | 18 | Today I drank beer. Perhaps I drank too much. |
| 2013 | 01 | 19 | Today I drank tea. It's not the same as coffee. |
These CSVs will assume the first row of data is “header” data. It will then put it in an HTML table that can be sorted by the user.
One can also specify default sorting methods with the following syntax:
- !Year sorts the column “Year” in least-to-greatest order.
- ^Year sorts the column “Year” in greatest-to-least order.
- !#Year sorts the column “Year” in least-to-greatest order, treating all elements as numbers.
- !@Year sorts the column “Year” in least-to-greatest order, treating all elements as strings.
You can mix and match the sorting “hints” as you wish.
Collections
Collections have the purpose of rendering multiple documents within your Giterary repository at once. This is done as a special rendering of the collection or collect file extensions. Contents of these files are simply lists of other file paths (MyFile, Wherever/I/Put/My/File.txt).
For example:
/DarkAndStormyNight/Chapters/Chapter1
/DarkAndStormyNight/Chapters/Chapter2
/DarkAndStormyNight/Chapters/Chapter3
Will render the files Chapter1, Chapter2, and Chapter3 in succession on a single page. This is useful for stitching together a larger document (the entirety of a book, for instance), of which you have broken into smaller, more manageable pieces (chapters, in this case).
By editing the collection, you can re-order its component parts by changing the order of the paths referenced in the collection document. For instance, if you decided to put Chapter3 before Chapter 2:
/DarkAndStormyNight/Chapters/Chapter1
/DarkAndStormyNight/Chapters/Chapter3
/DarkAndStormyNight/Chapters/Chapter2
Time travel novels are notoriously difficult to write, but this should help to order your components without having to change the underlying contents.
You can also use the collection documents to include an entire subtree of your Giterary repository. For instance, for the user “jrhoades,” they may have a collection that contains the following:
jrhoades/jot/201*/*
Use of the asterisk wildcard lets you match all documents matching the collection query. Documents will be rendered in order of directory traversal, and in alphanumeric order. The above example will render all “jot” files for the user “jrhoades” for the years 2010-2019.
Document Statistics
Document statistics are your basic “word count"—types of metrics that Giterary will calculate for you. For instance, you can view the statistics for this very help file.
Statistics calculations also work on collection files, such that the statistics will be calculated for the collection document after all of the components of the collection have been collected.
Document Import
Currently there are no “import” tools for Giterary. This is because there are hundreds of tools that can do a better job than Giterary can for the hundreds of files and formats people use outside of Giterary.
For the time being, Giterary maintains that simply rendering your documents into text is sufficient to copy and paste your documents into Giterary. Using tools like OpenOffice, Pandoc, or the two in conjunction to generate Markdown syntax is one successful conversion path used by the author, however, some experimentation may be in order.
Partitioning
If you do manage to get your document into a textual format suitable for Giterary, it is likely that this document is sufficiently large (in the case that you’re submitting a manuscript, or something of that scale).
It may be the case that you want to split up this document into smaller parts for you, your co-authors, or your editors to work on. In this case, Giterary does have a tool for easily “partitioning” files that makes this type of organization much easier.
Partitioning works by finding “potential boundaries” by determining where there are blank lines (or lines with only whitespace) within the body of work. As these blank lines have no content, they are likely things like spaces between paragraphs, chapters, etc.
The partitioning interface presents these boundaries, and allows you to select which boundaries you want to use. It then provides you with a summary of your new partitions, and allows you to name according to the Giterary filename semantics.
To see an example, try to partition this file.
Document Editing
Editing a document is probably the most critical and common activity within Giterary. The editor attempts to be straightforward while giving as close to immediate feedback on the things that you’re editing as possible.
The editor
While logged in to Giterary, viewing any object (except for directories) there will be an “Edit” tab at the top of the document. This link will take you to an editor for that particular page. An editor does generally what you expect: it shows you the text contents of a file, and allows you to modify the contents, and save your changes. There are, however, a few things to note about the editor. 1. The editor is *contextually aware. That is, the editor detects the type of file that you are editing, and attempts to show an editing interface that is tailored for that type of file. The most apparent (and at time of writing, the most developed) of these contextually aware editing interfaces is that for Markdown. When editing a Markdown file, the interface will display the source text and a “live preview” side-by-side. However, for more generic files, the editor will display a “plain” editing interface without the live preview. 2. The editor tries to minimize the amount of scrolling you have to do. Both the Markdown and generic editors attempt to “synchronize” the editing and preview windows to the best of their ability: * The generic editor attempts to show the approximately similar scroll distance between both the editing window and the preview window. * The Markdown interface attempts to always highlight the *bounding element* which you are editing. For instance: if your editing is in a paragraph, it will highlight that paragraph, if you are editing an item in a list, it will highlight that item in the list. This works for both keyboard navigation as well as mouse clicks within the editing area. The editor will also “save your place” in the editing window, allowing you to quickly preview a document without having to scroll back to your place. 3. The editor is aware of the version of the file you were originally acting against, and tries to help accordingly. With the possibility of multiple users operating on the same Giterary instance, there is the possibility that two users can edit the same file at the same time. This has the potential to cause conflicts, as well as lost work due to one person’s edits overwriting another’s. If ever the editor detects that the file has changed out from underneath you, it will display an error and refuse to save. It does, however, keep your edited contents in the editing window, as well as saves a draft of your edits. Unfortunately, it is up to you to resolve the conflicts occurring from the Giterary interface, but we would rather err on the side of caution by not ever unintentionally overwriting another’s work.
Giterary-specific SyntaxWorking within the Editor
The editor allows you to write whatever textual contents you wish. However, learning a few syntactical tricks can help to create sharp, well-structure documents very quickly.
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:
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:
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.
The editor has a helper function to quickly generate wikilinks. While highlighting a section of text, clicking on the “Link Selected Text” hyperlinks will prompt you for your wikilink target.
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…
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:
This text is annotated. This text is “annotating” the original text.
Note that with the above syntax, you need not put the “comment” tags at the end of the “annotate” content, nor are you limited to one comment tag within the annotation.
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...
{referencetag}: This is my note.
Would generate the following:
This is some annotated text. This text is annotating …or…
This is some annotated text. This text is annotating.
The editor has a helper function to quickly generate annotations. While highlighting a section of text, clicking on the “Annotate Selected Text” hyperlinks will prompt you for your annotation comments.
Dialog Highlighting
Dialog highlighting attempts to show a user the approximate balance between dialog content and non-dialog content in a document.
Dialog content generally follows the format of:
“Something something,” she said.
Which consists of:
- Content with double quotes, and…
- The quoted content ending with a punctuation mark (commas, periods, exclamation point, question mark, ellipsis,etc.), and…
- Not part of a “list” ("Item 1,” “Item 2,” and “Item 3").
Note that these are very generic and unsophisticated dialog detection mechanisms, meant to be useful only in common cases. Some consideration is taken for different quoting characters (UTF-8 left quotes and right quotes), but it can only guess as to the different ways you may write dialog.
### Markdown, and then some#### Markdown
Markdown syntax is a useful way to write without having to worry about syntax. Markdown is the default syntax when not specifying a file extension as part of its name.
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 usageHelp 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).
### Live Preview
Commit Notes
On every editor there will be a “commit notes” field. This field consists of plain text, without any formatting or special syntaxes. This is because this field is intended to record the reasons or reasoning behind your current modifications. Feel like you’re using the word “bustle” too many times? Put it in the notes. Moving some things around to sound more punchy? Put it in the notes. Did it start snowing while you were writing? Put it in the notes. Why do this because even if 1 in 10 notes are actually useful, it still means that 1 in 10 notes will be useful to you in the future. Over the course of a project you may have hundreds or thousands of edits. If you ever need to sleuth back through your history, you will want to be able to have your notes indicate what your intents were at the time, or, whatever valuable information you can think to include that is valuable to display along with the changes. Additionally, if annotations do not suffice, the commit notes can serve as a place for your editor to put their notes to describe their overall intent for a change. However, if meticulous notekeeping isn’t your style, you can keep your commit notes blank, and Giterary will report on the added or subtracted word count from your previous version. This is sufficient for small, piecemeal edits.
Preview vs. Submit
While the commit notes for editing are not mandatory, an immmediate preview of your document is. This is for a few reasons: * You should be reviewing your edits to make sure your intended edits render correctly (sometimes Markdown syntax is a tricky business). * There may be in the future elements in the editor that require server-side processing (and therefore, require a “Preview” to be able to see the render properly). * To make sure the file hasn’t changed out from under you.
Drafts
When editing a document, a timer will periodically trigger to determine if you have made significant changes in the editor. If so, it will send a “draft” portion back to the Giterary server, containing the contents and the commit against which the draft was being written.
These drafts can be used to recover writing lost after the disruption of an Internet connection, power failure, or a failure to distinguish “Control-W” from “Control-Q” as a keyboard command.
These commits can be recovered by logging in and visiting the “My Drafts” page, which will list all recent unsaved drafts. Clicking on “edit” for a draft from here will load the editor page with the last known draft contents against the document you were editing.
The Wonderful World of Version Control
TODO
Terms from git
- repository
- commit
- clone
- push
- pull
History
TODO
Comparing Different Versions, or “Diffs”
TODO
Blame
TODO
Cherrypicking
TODO
Reversion
- The ability to view global history, as well as history specific to one or more files.
- See intuitive, helpful "diff” page, demonstrating the capabilities of the backend difference engine.
- Building from the “diff,” you can also "cherrypick" changes (keeping some, discarding others), and use them to build a new version of your document.
- 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.