## "Just write," they said, "It doesn't matter what tool you use..."
Writing is the hard part, everything else is just *formatting*. You could scratch your novel into a wall with a rock, or use a modal command line text editor, the point is: *you should be focusing on writing*. Your tool should be a secondary concern.
## ...says the README file trying to sell me on a writing tool...
Right? I'm losing the sale before the customer even drove the car, but Giterary isn't really selling something (it happens to free, open source software, which brings together [other][git], [powerful][markdown], [freely][php] [available][jquery] [tools][showdown]).
So, what does Giterary do as a writing tool? Giterary is a tool that suggests a better way to work, helps you if it can, concentrating on making the hard things easy, and keeping the simple stuff simple. It can get out of the way if you want to *just write*, but it'll make your life less complex down the road.
## "[A first novel won’t be as much work as you think. It will be much more. ][reddit]"
Consider the scale of a novel. For the most part, published writing projects weigh in at around ~50,000 to 100,000 words (and often more). They can take years to write, after which they tend to require extensive editing, re-reads, re-writes, and whatever requisite iterations it takes to make a better product.
Now consider a machine with ~50,000 to 100,000 moving parts. A *novel-machine* that takes a human's attention as input and outputs compelling plot, worthwhile characters, and subtlety. As the engineer/author, it's your job to fabricate the machine parts, construct them correctly, and maybe apply a layer of paint. Sure, maybe it works for you the first time you run it, but when you ask your best friend to take a spin it seizes midway past the second-stage turbine spooling. You walk slowly through the smoldering wreckage. Your friend is alright. Your pride is not. And you forgot to take notes the first time around.
The point is: if *writing* a novel is hard, *maintaining* a novel is complex. The latter of which is overlooked when *just writing* is a primary concern.
**Giterary offers a set of *nice things* to write and maintain a novel**, managing complexity at both ends of the process, and hopefully without you noticing. How does it do this? Well...
## When programmers are lazy, everyone benefits.
Computer programmers look at your machine with 100,000 moving parts and laugh. Software weighs in at **tens of thousands to a few million** lines of source code. They don't even bother to count the words, were there even words to count.
They laugh because they solved the management of that complexity a long time ago. Lo, and they chanted in their sing-song way, *"A hundred people need to work on something with at least a million lines of code. And they should all be able to work at the same time, and be able to detect and communicate their changes efficiently, and maintain detailed histories of their changes, and gracefully solve conflicts, should they arise."* And thus it was so, and they've been improving on this concept ever since.
If your novel were like the programmers' source code, you'd be able to manage your novel with these all-powerful tools of the programmer gods. The thing is, your novel **is** source code, much like its words are part of your *novel-machine*. It's just a matter of *formatting*.
## That's nice. So what does this do, again?
Giterary is a wiki application with a cool synchronization tool. It helps you write, and helps you maintain your novel.
Giterary suggests you write your chapters in Markdown syntax (but you don't absolutely have to). Markdown is a text-based format that lets you do complex formatting by *just writing*, and largely ignoring things like formatting, markup, and tedium. It also extends Markdown's functionality by allowing textual annotations and "wikilinking" between your files, similar to Wikipedia, letting you build a web of references to information you need.
Giterary puts these text-based files into a hierarchical directory structure of your choosing, and manages these files using a git repository. The git repository stores all versions of all files, and Giterary wraps around the git repository to let you easily see information about your files, down to showing you when you swapped out "she said" with "she said, languorously."
The killer feature, though, is git's ability to act as a distributed database. You can take the entirety of your Giterary instance, clone it to any computer, make changes, and then push them back. Need to work offline on the plane, but submit your changes once you're back in civilization? Not a problem.
## Nobody has time for that noise, I just want to write. Why would I need that?
Three reasons:
* **You are forgetting all the time. You just forgot something.**
I barely remember last week. Yesterday's already fuzzy around the edges. Things I wrote a year ago might as well have been written by a different person, with different hopes and dreams. And while I can't talk to that person, using Giterary will let me see what that stranger did, and if they provided notes, see what they were thinking.
Giterary helps you talk to the past, and leave messages for the future.
* **It may not only ever be *you* making the changes.**
You never thought about **that**, did you, hot shot? Well, yeah, I guess maybe you did. The possibility of multiple authors isn't unheard of, but that pales in comparison to the most common case: you will eventually need to turn your things over to an **editor**.
You *can* submit a massive, monolithic Word document via email and hope *Track Changes* does the job. But what do you do while you're waiting for them to send your document back? What if you're still working on a chapter? How do you maintain which is the "master" copy, and which is for edits? Do you **copy-paste** your edits, like the beasts of the wild?
If you feel shame, that's okay. It means the healing can begin. Giterary provides an intelligent system to manage change, and to do so immediately, letting you maintain a sane workflow for you, your potential co-authors, and your editors.
* **Backups are nice. Backed up git repositories are nicer.**
Giterary isn't a backup tool, but this is because other things solve this problem much more reliably and elegantly. Getting automated backups should be a concern of anyone who can't afford to lose files.
However, assume bad things happen: your hard drive craters, your computer is stolen, or you accidentally deletes files. It's fine, because you backed up your files, right? *Right?* Right. But then the question becomes: when was your last backup? Did that have the latest version of X, Y, or Z? You can look at the timestamps on the files, but is that the time when the files were backed up, or when the files were last modified? What if you have two backups, both containing information you need?
With a git repository, you can simply **ask**. And you can synchronize changes between one or more git repositories, even if changes were made at different points in time. And you can do it with freely available tools. Again, Giterary isn't a backup tool, but it *can* make putting the pieces back together much less daunting.
While storing metadata for changes to wording may seem like information overload, you can ignore it until you absolutely need it. The *nice thing* about Giterary is that it gives you a place to do these things while letting you focus on *just writing*.
## Why would I need to organize my information this way?
Sure, everyone has their own way to deal with their information. But there are a few *nice things* to the way Giterary deals.
* **Text files abide by the law of least surprise.**
Text is text is text. Files are files are files. Directories are, well, a bit more complicated, but you see what I mean. File formats change, features come and go, and registration keys get lost. Text files are the most basic way to store your information, and frankly, are hard to screw up. Most important: vast arrays of editing tools are available (far grander than Notepad), and are available *everywhere you will ever turn on a computing device*. You will never have to hunt down a copy of proprietary software that supports your file format (Word), nor worry that other programs won't support the features of the one you wrote in.
* **You maybe should be dividing up your novel anyway...**
*Just saying*. Why wouldn't you try to divide out the pieces of your work into separate files? Or organize your reference documents and glossaries and appendices in a structured way?
The reason I can think of for not doing so is because eventually you'll have to stitch them back together. This is easy for a computer to do, so why can't you work on your smaller pieces, then tell the computer to put them together when you're done? Giterary supports this, both in partitioning out documents into smaller files, as well as automatically creating "collection" files to stitch them back together. Plus, you can modify your collections to change the order of your documents *without changing the underlying documents*.
* **A wiki lets you create information *and* an interface to it at the same time**
This sounds strange, but you see it every time you visit Wikipedia. The content of a document is well and good, but it's the links within a document that lead you to the most interesting things. With a series of wikilinks, you can turn a normal document into a navigational structure. You can build chapter lists, character sheets, TODO lists, glossaries, indexes, whatever you want. And you can do it using the same syntax you use to write your story.
## But what about the Otaku-Neckbeard-Hacker crowd?
I'm not a writer, though I once had hopes and dreams. I am, instead, a programmer who likes words and how they go together. I know writers, though, and editors, too. Though my fervor for the nerdier portions of this project burns bright, their practicality and intolerance tempered Giterary into a finer steel.
That said, there are still some things in here for those who share my mindset and my apathetic facial hair.
* **Minimal system requirements**
The application requires PHP, a web server to serve the PHP scripts, and the git executable. Nothing else. Everything is self-contained. *Everybody fights, nobody quits*.
* **A simple codebase. The kind you'd like to start with, but not have to build yourself.**
Do you like learning an entirely new object model every time you need to modify a project? A grand new set of design decisions and limitations that were made without you, and never documented? Me neither. Use of OO in the PHP backend is limited, preferring a series of functions that wrap around git CLI functionality and display logic. Need complex, stateful logic for something? Great. I hope my functions help when you wrap them into your objects.
There's a simplistic templating engine, a few performance tracking modules, and some file caching, but nothing special. Everything is PHP, Javascript, and CSS, with the necessary parsing and rendering libraries included (Markdown, Showdown, jQuery, Tablesorter, etc.).
* **Edit how you want, git how you want.**
Don't like the Giterary interface? Prefer Notepad++? TextMate? SublimeText? Vim? Emacs? Something with an even greater sense of vague technological elitism? Great! Edit with that. I won't be sad. Edit locally, and upload via your git client. That is, whichever of the dozens of beautiful, full-featured git clients roaming the wild. There is a git post-receive hook that will keep your web application up-to-date, but you can do with it as you like. Decide you hate Giterary and want to set up shop elsewhere? Certainly. It's git, and it's files. Go nuts.
## Okay, but can you do anything to sweeten the deal?
Um, sure? I wasn't going to mention, but since you asked...
* CSV file support, with client-side sorting, default sorting hints, and wikilink syntax, perfect for establishing that timeline of geological events in your world, cross-referenced and tagged according to the events in your novel.
* Being able to show which reversions, which author, and on which date every line of a file was last touched (called "blaming" in git-tongue). **Every line**. We don't skimp.
* Don't particularly care for your editor's last few edits? Well, reconcile your professional relationship by cherrypicking their edits ("canceling" or "restoring" edits, word by word). After you've corrected their obvious errors, drop the results into your editor to really show them the meaning of artistic license!
* Trying to balance dialog versus exposition? Giterary's dialog highlighting detects common "talk-y" looking quotes segments and can highlight them apart from normal text.
* Keep forgetting what's left to do? Insert a "TODO" line in your document, and then come back to it later from a specialized "TODO" search.
* Need to shove a bunch of things into one document? Don't feel like copy-pasting a bunch? Good! It's because you should **never do this to begin with**. Create a document collection, allowing you to render any Giterary files, in any order, and according to each file's specific rendering mechanism (Markdown, CSV, Text-only).
* Have a massive manuscript you need to split apart into workable segments? Document partitioning will allow you to load a document, select "partition boundaries," and even name the new partitions ("Chapter 1," "Chapter 2," etc.). It'll even create a new collection to provide a way to stitch your original document back together.
* Annotate documents and be able to "mouse over" the notes, but only when in "Decorations" mode. In fact, Giterary won't try to "decorate" your document in any way (past your specified formatting) unless you tell it specifically to "Decorate" a document. Nothing is more offensive than [somebody else's bad decorating choices](http://lh4.ggpht.com/_lkfp0Y8ol_U/TUnZ5E_G1RI/AAAAAAAAGVU/UedcGkystMQ/s400/DSC_0290.JPG).
* Annd... ah, well... you can search for things? Searching is fun. There is a search. And you can navigate your directory structures! It's an adventure all to itself.
*(Side note: It can also do things like show you dictionary word counts, auto-generating tables of contents, auto-saving drafts, etc., and other common word processing features, but those are pretty run-of-the-mill, so you can discover those for yourself.)*
## Whether by pity, morbid curiosity, genuine interest, or an intersection thereof, I feel compelled to give it a chance...
That strange compulsion is your keen technological and creative intuition talking. It means he or she is proud of you for getting this far. I, of course, never doubted you for a second.
From here you can:
* View the [[INSTALL|installation instructions]]. They're a little involved, but not insurmountable.
* Look at the [[HELP|help file]] to get a sense of how to use Giterary (it's not too bad).
* Kick around on the [playground](http://playground.giterary.com/) to see the application in its full glory.
* Check out the [[FAQ|Frequently Asked Questions]].
--
Thanks for reading. Happy writing!
[git]: http://git-scm.com/
[php]: http://php.net/
[markdown]: http://daringfireball.net/projects/markdown/
[jquery]: http://jquery.com
[showdown]: https://github.com/coreyti/showdown
[reddit]: http://www.reddit.com/r/writing/wiki/faq
~authorbias# Installation Instructions
The following are general guidelines to getting Giterary running. These instructions are biased towards the Linux side of things, but there is no reason an enterprising individual couldn't get them running on Mac OS or Windows. They also assume you have a basic working knowledge of the components of the Internet, how to configure your systems to run "services" or "daemons," or a certain quantity of patience and a willingness to Google something if you don't understand it.
## Requirements
* **A computer capable of running [PHP 5.3][php] or greater and [git 1.7.X.X or greater][git].**
These are widely available from many different Linux distribution packaging mechanisms (Debian and Ubuntu's apt-get, Centos and Fedora's yum, etc.) Binary packages are also available from their respective sites for all operating systems.
* **Web server software that supports running PHP**
Numerous pieces of web server software support the use of PHP. Popular choices include:
* [Apache][apache] (Available on Linux, Mac OS, and Windows)
* [Nginx][nginx] (Available on Linux, Windows, probably Mac OS)
* [IIS (Windows)][iis] (Available on Windows)
You may not feel up to installing and configuring these yourself. I know: I've had those days, where the weight of the world dictates that you won't look at another config file. But don't despair: these are so popular and ubiquitous that many people sell services, construct virtual machines appliances, and make a ton of tools so that you can get off the ground with a web server and PHP easily. So much so that they've even given these types of setups a clever acronym: [LAMP][lamp] or [WAMP][wamp] ("Linux/Windows, Apache, MySQL, and PHP", minus the MySQL in our case). Do a couple of Google queries for "LAMP server" or "LAMP appliance" and you'll see what I mean: tons of step by step guides, virtual machine appliances, and hosting services, all waiting for your time and patience (or money, potentially).
Unfortunately, those steps are beyond the scope of this document. We provide verification steps later here to make sure things are working, but getting to that point has been documented and solved much better by smarter people than the author of this document. No matter if you're installing on your daily-driver laptop, or a fully-redundant cloud server, I would invite you to learn about such things, as they are valuable things to be knowledgeable about, will teach you about the underpinnings of the Internet at large, and makes you a blast at parties).
* **OPTIONAL: An SSH server program (if you are doing git-over-SSH synchronization, which is recommended)**
git has the ability to push and pull from multiple sources, and using multiple network protocols. The most reliable and conventionally accepted appears to be SSH, which provides encryption as well as authentication. If you plan on "synchronizing" another computer with your Giterary instance, you will want to have an SSH server or git-capable equivalent to provide access to your Giterary repository.
* [OpenSSH][ssh] is widely supported on Linux, Mac OS, and on Windows.
* **OPTIONAL: A git GUI client**
You will need the command line git client installed. However, there are a number of GUI clients (graphical user interfaces) that are a lot more friendly to human eyes.
It is highly recommended that you keep a git client handy, just in case you don't like how Giterary does something, or that you have to do something Giterary doesn't. These tools let you interact with your Giterary repository in lots of nice ways. They also provide a more forgiving git learning tool than the command line, man pages, and frustrated Google searches. I recommend the following:
* [TortoiseGit][tortoisegit] (for Windows)
* [SourceTree][sourcetree] (for MacOS)
These requirements may seem out of control, but they're not so bad, and in fact, are pretty common among web applications (though hidden by the fact that you only need a web browser to use them successfully). I can give a few recommendations, pointers, and places to get started with hosting your own Giterary instance.
*(I'll always advocate running your own servers before "going to the cloud." It means that you own your hardware and your data, and you have to worry slightly less about how your novel will fare after the zombie apocalypse. However, starting from scratch, the learning curve for "rolling your own" is admittedly steep and having other services available to jumpstart your progress is too useful to leave it unmentioned. Plus, setting up and maintaining highly redundant, highly available server hardware is expensive and time consuming, and some people just don't value geek cred as much as I do :) )*
Here are a few things to look into if you're a) installing your own server, b) exploring options for your own server, or c) curious about how to become a hit at parties:
* [Ubuntu][ubuntu] happens to be my favorite "I don't care about the details, I just want to use something" flavor of Linux. Its package system tends to have everything, and if you're wanting/needing it, it has a well-supported desktop environment, and a large user community.
* [Amazon's EC2 (Elastic Compute Cloud)][amazonec2] is a cheap and quick way to get hosted in the "cloud," and they can bill at cents per hour, if you're wanting to be economical.
* [TurnKey Linux][turnkey] is a collection of tested, pre-configured virtual machine appliances that can get you set up and running with what you want in just a few minutes. They have a [pre-configured LAMP stack][lampstack], and partner with Amazon's EC2 to provide cheap virtual machine hosting on their [Turnkey Hub service][turnkeyhub].
* [prgrmr][prgrmr]'s tagline is *"We don't assume you are stupid."* Which is pretty great. However, they aren't for the faint of heart. In fact, you may or may not have to send in a photo of your neckbeard for verification before you can be sold anything.
Another option is to call up or email that computer-savvy person you know, or, make friends with one you don't. Honestly: we live for this stuff. Memorize the following phrase (phonetically, if you have to): "I want to set up an Apache server with git and SSH, and have it sync with my laptop." If you work in a business that has an Information Technology department, you can walk into the middle of their work area and shout that above the server noise. Any geek worth their salt will venture out of their cube to ask further questions. Best case: they set it up for you. Worst case: you learn who to talk to next time something is really broken.
There are also [Linux User Groups][lugs] in pretty much every major city, state, and university campus. They like to be able to serve their community, and installing something like Giterary is an easy and straightforward task for them.
[lamp]: http://en.wikipedia.org/wiki/LAMP_(software_bundle)
[wamp]: http://en.wikipedia.org/wiki/WAMP
[lampstack]: http://www.turnkeylinux.org/lampstack
[turnkeyhub]: https://hub.turnkeylinux.org/
[prgrmr]: http://prgrmr.com
[ubuntu]: http://www.ubuntu.com/download/server
[amazonec2]: http://aws.amazon.com/ec2/
[lugs]: http://en.wikipedia.org/wiki/Linux_user_group
## Latest Version
Grab the latest version of Giterary from:
* HTTP Download
TODO: Hosting?
* git clone
TODO: Github? Bitbucket?
## Verify PHP versus Your Web Server
Every web server has a directory into which you can put files, and it will serve those files, for better or for worse.
Much of the configuration headache for web servers is getting the names, access rules, and pointers to the right directories into place. We leave it up to the reader to maintain their own security, but take heed when we say that the intent of a web server is to *put things on the Internet*. Be sure that you check to see if things are exposed that should not be (for instance, if your Giterary instance is exposed to whoever happens to be sitting next to your at the airport terminal).
Most important to establishing this "hosted directory" is ensuring that PHP is configured correctly. Within your "hosted" directory, place a file called *test.php*, which has only these contents.
phpinfo(); ?>
Afterwards, using your web browser, browse to a URL referencing your host and the *test.php* file, for instance:
If you plan to be accessing Giterary from only your own machine:
http://localhost/test.php
If you are installing to a separate server:
http://myserver/test.php
If you are installing Giterary to a place other than the URL's "root" (referring to the "/giterary/" portion of the URL not being at the "root" of the path after the *myserver* host specification.)
http://myserver/giterary/test.php
This page should contain an output from the *phpinfo* function that lists all of the compilation, configuration, and dependency information for your PHP installation. It will be purple.
If this is running successfully, then you have a working PHP configuration for your web server. *Good job!*
## The Easy Way, or The Hard Way (install.sh)
There is Linux install script that tries to walk you through your various configuration necessities (names, paths, usernames, passwords, etc.). It isn't particularly sophisticated, and isn't particularly platform agnostic (has only been ran on Ubuntu), but it's a lot easier than wading through all this mess.
It is located in the root directory of the source code, called *install.sh*.
If successful, it sets you up with a Giterary instance with:
* A working git repository
* Reasonable directory structure for git repository, cache, temp, draft, and session information:
/var/lib/giterary
/var/lib/giterary/repos/your_repo_name
/var/lib/giterary/caches/your_repo_name
/var/lib/giterary/temps/your_repo_name
/var/lib/giterary/temps/your_repo_name/drafts
/var/lib/giterary/temps/your_repo_name/sessions
* Initializes your git repository, sets an anonymous user for the repository (required from operating from a web application like Giterary), and other small git repository configurations.
* A "passfile.csv" configuration, where a special CSV is added to Giterary that contains your username, git user information, and hashed password (pointed to with the *config/auth.php* config file). It is then configured as a "sensitive" file that only only be edited by the username your enter (with the *config/permissions.php* config file).
* Adds your DEFAULT_FILE to the repository with a welcoming message.
This is a fairly straightforward and secure configuration out of the box.
## Verify Git Is Working
From your operating system's command line (any terminal in Linux, Terminal in MacOS, the *cmd* MS-DOS prompt in Windows), attempt to execute the following command.
git --version
It should print out something like this:
git version 1.7.4.1
Alternatively, if your environment paths are somehow incorrect, you may need to be explicit in the path to your git executable.
To find your explicit path on Linux and MacOSX, you can issue the following command:
which git
...which should return the explicit path. In my case, it returns this:
/usr/local/git/bin/git
On Windows you may have to search the filesystem for *git.exe* and use the explicit path it returns.
With your explicit path, run the following command (but with your explicit path):
/usr/local/git/bin/git --version
This should give you version information for your installation of git.
Verify the security configuration on your system for your git client. **It needs to be executable by the user that is running your web server**. This is critical for Giterary to function.
Note this path value, as this is the path you will need to use later in the Giterary configuration.
## Create Giterary directories
Giterary needs a few directories to run:
1. **The directory of the git repository.**
This is a directory that will need to be readable/writable, and will store the git repository and its working directory. Recommended locations:
Linux or MacOSX:
/var/lib/giterary/repos/NAME_OF_YOUR_REPO
On Windows:
c:\programdata\giterary\repos\NAME_OF_YOUR_REPO
2. **The directory for Giterary to store "cache" information to make the application speedier.**
This is a directory that will need to be readable/writable, and will store the Giterary cache files to help make browsing via Giterary speedier. Recommended locations:
Linux or MacOSX:
/var/lib/giterary/caches/NAME_OF_YOUR_REPO
On Windows:
c:\programdata\giterary\caches\NAME_OF_YOUR_REPO
3. **The directory for Giterary to store "session" information that allows you to be logged in to the application.**
This is a directory that will need to be readable/writable, and will store the PHP session files that allow you to log in. Recommended locations:
Linux or MacOSX:
/var/lib/giterary/sessions/NAME_OF_YOUR_REPO
On Windows:
c:\programdata\giterary\sessions\NAME_OF_YOUR_REPO
4. **The directory for Giterary to store "temp" data, like draft files and file comparison inputs.**
This is a directory that will need to be readable/writable, and will store the PHP session files that allow you to log in. Recommended locations:
Linux or MacOSX:
/var/lib/giterary/temp/NAME_OF_YOUR_REPO
On Windows:
c:\programdata\giterary\temp\NAME_OF_YOUR_REPO
These locations are relatively arbitrary, and you could potentially combine the cache and session directories into one (but never the repository directory, that must remain apart from everything).
## Oh, the config files...
There are a series of configuration files necessary to getting Giterary up and running. They are all PHP files, and can be edited using any text editor. They are located within the *include/config/* directory of the Giterary source. They are situated such that one could have multiple instances of Giterary, but with different *include/config* directories, and the instances would be able to run simultaneously.
###### base.php
* **base.php**
*base.php* is the largest configuration file, as it contains references to the most basic portions of Giterary that are necessary to run ("Where is my repository?", "What is my name?", etc.). Below is a line-by-line description of the configuration values within *base.php*.
The following are **required** fields.
*SITE_NAME* and *SHORT_NAME* are display values for showing on the Giterary interface which instance of Giterary is running. This is where you put a name for the "title" of Giterary.
define('SITE_NAME', "My New Story");
define('SHORT_NAME', "New Story");
The *BASE_URL* is the base HTTP URL that will be used to navigate to your Giterary instance. This is used in link generation.
define('BASE_URL',"http://myserver/giterary/");
The *DEFAULT_FILE* gives the name of the first file to be created within your Giterary instance, and the default file to be displayed when no file is specified (likely the first file that will be displayed with accessing your Giterary instance).
define('DEFAULT_FILE', 'Home' );
*SRC_DIR* is the filesystem location of the source files for Giterary.
define('SRC_DIR',"/var/lib/wwwroot/giterary/");
*GIT_PATH* is the filesystem path to the command line git client on your server.
define('GIT_PATH',"/usr/local/bin/git");
*GIT\_REPO\_DIR* is the path to the readable/writable directory that contains the git repository for this instance of Giterary.
define('GIT_REPO_DIR',"/var/lib/giterary/repos/NAME_OF_YOUR_REPO/");
*CACHE_DIR* is the readable/writable directory for maintaining caches of certain data within Giterary.
define( 'CACHE_DIR','/var/lib/giterary/caches/NAME_OF_YOUR_REPO/' );
*CACHE_ENABLE* is a value of 1 or 0, 1 being that use of the cache is enabled, 0 is that it is disabled.
define( 'CACHE_ENABLE', 0 );
*TMP_DIR* is the temporary directory for temporary files generated by Giterary. It can be under the same directory as the Giterary cache.
define('TMP_DIR','/var/lib/giterary/temp/NAME_OF_YOUR_REPO/' );
*DRAFT_DIR* is the directory for storing draft files within Giterary. It can be under the directory as the Giterary cache.
define('DRAFT_DIR','/var/lib/giterary/temp/NAME_OF_YOUR_REPO/' );
*SESS_PATH* is the directory for storing cookie information for interacting with your browser.
define('SESS_PATH', '/var/lib/giterary/sessions/NAME_OF_YOUR_REPO/');
The following are **optional** fields.
*STYLESHEET* and *CSS_DIR* are relative URL references to the default CSS to be used by the Giterary application.
define('STYLESHEET', "simpler.css");
define('CSS_DIR', "css/");
The following are variables for configuring cookie information for communicating login session information with your web browser.
define('COOKIE_DOMAIN', 'www.YOUR_DOMAIN_HERE.com');
define('COOKIE_PATH', '/');
define('COOKIE_EXPR_TIME', 86400);
define('SESS_NAME', 'GITERARYSESSION');
###### permissions.php
* **permissions.php** and **permissions.lib.php**
*permissions.php* is the configuration file for how users are permitted to perform certain actions within Giterary. *permissions.lib.php* is a set of common permission settings, defined as named classes, and usable as objects to be "registered" within *permissions.php*.
A common, starting instance is "AllPlay", where all users can perform all functions without limit.
require_once( dirname( __FILE__ ) . '/permissions.lib.php' );
$registered_auth_calls = array();
register_auth_call( new AllPlay(), "can" );
?>
For a more "private" Giterary experience, the MustBeLoggedIn class defines that in order to view any portions of the site, you must have successfully logged in to the site.
require_once( dirname( __FILE__ ) . '/permissions.lib.php' );
$registered_auth_calls = array();
register_auth_call( new MustBeLoggedIn(), "can" );
?>
For a "mixed" Giterary experience, SensitiveFiles allows you to define certain files which are considered "sensitive," in that you must belong to a set of defined users otherwise you can neither read nor write to the files.
require_once( dirname( __FILE__ ) . '/permissions.lib.php' );
$registered_auth_calls = array();
register_auth_call(
new SensitiveFiles(
array(
"passfile.csv" => array( "jrhoades" )
)
),
"can"
);
?>
###### auth.php
* **auth.php** and **auth.lib.php**
Similar to *permissions.php* and *permissions.lib.php*, *auth.php* and *auth.lib.php* provide the configuration and the common case library for defining *how people log in to Giterary*. Essentially, how the user list is determined, and how passwords will be stored.
Currently there are two common configurations, *StaticUserList* and *PasswordFile*.
In a *StaticUserList* configuration, a class is defined in *auth.lib.php* that describes the user list, their properties, and their passwords. Editing the StaticUserList class in *auth.lib.php* is necessary for this configuration. This method is not necessarily recommended, though, is common due to the ease of maintenance.
require_once( dirname( __FILE__ ) . '/auth.lib.php' );
$registered_login_calls = array();
register_login_call( new StaticUserList(), "validate_login" );
?>
In a *PasswordFile* configuration, a CSV is referenced that defines username, user git properties, and a [hashed](http://en.wikipedia.org/wiki/Hash_function#Hashing_with_cryptographic_hash_functions) password. This file can exist within your a repository (and be editable from the Giterary interface), or be outside of your repository and be edited manually, it is up to your security requirements. A *permissions.lib.php* class is defined specifically for this type of file called "SensitiveFiles," which requires specific user credentials to be able to edit a file.
require_once( dirname( __FILE__ ) . '/auth.lib.php' );
$registered_login_calls = array();
register_login_call(
new PasswordFile(
'/var/lib/giterary/repos/my_repo/passfile.csv'
),
"validate_login"
);
?>
A "passfile" is a CSV formatted file that contains names, emails, and password information for users to log in with. An example file might look like this:
Username,GitUser,Password
jimmy,"Jimmy ",6f1ed002ab5595859014ebf0951522d9
The file is a CSV, and as such, can be edited using the Giterary interface (and will render as a table when viewing). However, you don't want just anyone on your Giterary instance viewing and/or editing your password file. In these cases, you want to use *permissions.php* to flag your *passfile.csv* as "Sensitive," and only viewable/editable by a small set of users.
**WARNING:** Just because the Giterary interface restricts access to such a file doesn't mean that people with access to your git repository won't. Anyone who can read information from git can read your passfile. While efforts are taken to make sure your passwords are obfuscated, it's important to know that git itself doesn't do "security." If you want to use a passfile, but **not** have the file be located in your git repository, simple move your passfile to somewhere that isn't in your git repository. You will have to edit this file by hand.
Finally, you might be asking yourself, "Who wants to enter in '6f1ed002ab5595859014ebf0951522d9' as a password?" The answer is: *absolutely nobody*. Nor do they. This is a "hash" of your password, a mathematical algorithm performed on your password to make it difficult to guess its original contents. When you log in to Giterary, the password you enter is ran through this same algorithm, and if the two "hashed" results are equal, you have successfully entered your password and you are allowed to log in. It's a clean and useful way of storing passwords without having to store them at all.
However, the question becomes how to generate these password hashes. On Linux, the following commands are available:
md5sum
sha256sum
sha512sum
...And others, which let you pipe in arbitrary text (ie, your password) and return a hashed result. For example, for the password "blah" (which is a terrible password which you should never use):
echo -n "blah" | md5sum
...will return the following:
6f1ed002ab5595859014ebf0951522d9 -
**NOTE**: You **must** include the "-n" portion of the echo command, otherwise echo will emit a newline character, which will invalidate your hash value.
The 6f1...22d9 value is what you paste into your Giterary *passfile.csv*. However, Giterary assumes that unless you specify your hashing algorithm, it will just use the MD5 algorithm. This is fine if you only ever generated hashes with MD5, but some people want a more cryptographically hardened hash value. If you want to do a SHA256 hash, you would have to put in the following:
"sha256$8b7df143d91c716ecfa5fc1730022f6b421b05cedee8fd52b1fc65a96030ad52"
Or, for SHA512:
"sha512$39ca2b1f97...(long, long result )...1c2fa54b7"
The important part being the "xxxx$" prefix. Anything before the "$" in the password fields is treated as a hashing *hint,* to suggest to Giterary which hashing algorithm is used. The "xxxx" hash hint can be anything that is supported by [PHP's hash() function][php.hash].
[php.hash]: http://php.net/manual/en/function.hash.php
###### dict.php
* **dict.php**
The *dict.php* file defines the path to the "dictionary" file, as well as sets of configurable groupings of words for calculating document metrics (the "Statistics" page).
*DICTIONARY_PATH* is the path to a file that consists of 1 word per line. On Linux, this path is normally */usr/share/dict/words*.
define( 'DICTIONARY_PATH', '/usr/share/dict/words' );
The following are the lists that define the groupings for which words are to be considered conjunctions, "non-counted" words (common words you don't want counted as "words" for your stats), past tense verbs, and present tense verbs.
$conjunctions = array(
/* ...for, and, not, nor... */
);
# http://en.wikipedia.org/wiki/Most_common_words_in_English
$non_counted_words = array(
/* ...the, be, to, of... */
);
$past_tense_verbs = array(
/* ...was, wasn't, did, didn't... */
);
$present_tense_verbs = array(
/* ...is, isn't, am, are... */
);
###### perf.php
* **perf.php**
A flag for whether to calculate performance stats and include a "performance report" in the HTML comments of every Giterary page. Enabled by default.
define( 'PERF_STATS', 1 );
?>
* **time.php**
Defines the default timezone to be used when making changes from the Giterary interface.
date_default_timezone_set ( 'America/Anchorage' );
?>
* **conventions.php**
The *conventions.php* file defines the basic "conventional" assumptions Giterary makes when defining things. Examples of conventions are:
* The suffix used for "dirified" directory names (*dir* by default).
define( 'DIRIFY_SUFFIX', "dir" );
* Default character encoding for the Giterary instance (*UTF-8* by default).
define( 'ENCODING', "UTF-8" );
* Regular expressions to determine the valid filename and file path patterns used on the site.
$wikiname_pattern = '-_a-zA-Z0-9\.\s';
$wikifile_pattern = "@^([$wikiname_pattern]+)(\\/[$wikiname_pattern]+)*$@";
$wikilink_pattern = "@(\\\)?\[\[([$wikiname_pattern]+(\\/[$wikiname_pattern]+)*)(\|([\w\s\.\,\\/-]+))?\]\]@";
$functionlink_pattern = "@(\\\)?\[\[([a-zA-Z]+):(([^\]|,]+=[^\]|,]+)(,[^\]|,]+=[^\]|,]+)*)?(\|([\w\s\.\,\"/-]+))\]\]@";
###### html.php
* **html.php**
*html.php* defines parameters for dealing with the HTML generation within Giterary.
The *$allowed_tags* configuration variable defines which tags are allowed to be used for final rendering within Giterary.
$allowed_tags = array(
/* ...'

', '', '

', '', '

'... */
);
The default list provided with Giterary is a good subset of HTML which provides a wide range of HTML dipslay elements while avoiding potential security risks by disallowing the inclusion of Javascript from a page. You, however, may want to change this at some point, which is entirely up to you and your security requirements. However, this is by no means recommended, and likely will be more of a pain to manage than the functionality gained by allowing such features to be embedded within documents. Proceed at your own risk.
###### themes.php
* **themes.php**
*themes.php* defines the names and paths responsible for rendering the various pieces of Giterary. This file is not necessary to edit in an initial configuration, but is important if you want to add your own elements as "overrides" to the default theme.
*DEFAULT_THEME* is the name of the "default" theme to be used for your Giterary instance. This theme must be the name of a array key within the *$themes* configuration variable later on (and is by default).
define('DEFAULT_THEME', 'default');
The *$renderables* array is a list of name-to-path associations for 'well-known' renderable files, responsible for rendering anything from page layouts to reusable widgets or error messages withing Giterary.
$renderables = array(
'default_layout' => 'theme/default/renderable/layout/standard.php',
'edit_layout' => 'theme/default/renderable/layout/edit.php',
'show_layout' => 'theme/default/renderable/layout/show_layout.php',
'note' => 'theme/default/renderable/note.php',
'gen_error' => 'theme/default/renderable/gen_error.php',
'gen_header' => 'theme/default/renderable/gen_header.php',
'gen_history' => 'theme/default/renderable/gen_history.php',
/* ... */
'not_logged_in' => 'theme/default/renderable/not_logged_in.php',
'gen_csv' => 'theme/default/renderable/gen_csv.php'
);
The *$themes* array defines as the keys the names of available themes, and as the values of those keys, arrays that describe "overrides" of the *$renderables* definitions for the named renderables. This allows a theme author to make as much use of the default theme as possible, and only define their theme as "exceptions" to the default theme as necessary.
$themes = array(
'default' => array(),
);
Note again that editing this file is not required, but we're just providing a description here for documentation purposes.
## Initialize your git repository
Your git repository needs to be "primed," so to speak, before being used by Giterary. First off, within your repository directory (perhaps */var/lib/giterary/repos/your_repo*), do the following command:
git init
This will initialize an empty directory for you to work with (and creates the "hidden" files that git uses alongside your own).
You also need to inform git "who you are," though, this isn't really your name, as the Giterary application provides your committing information for you. However, git still squawks when this is unavailable. To silence this, we set a temporary, "anonymous" user for the repository. The name doesn't particularly matter, nor does the email address have to be valid.
git config user.name "Anonymous User"
git config user.email "anonymous@anonymous.com"
*(Once the Giterary authors figure out how to get around this, we will likely be able to skip this step.)*
## That was horrific. Am I done?
Well, I think so. At least the Giterary part anyway. You should browse to your Giterary instance with your web browser, loading up *index.php* to see if it displays the editing screen for the file indicated by the file name configured with *DEFAULT_FILE* in *base.php*.
http://localhost/giterary/index.php
If the page loads, and you're able to save your file successfully, then you've succeeded in installing and configuring Giterary.
## It didn't work. I have shamed myself and my family.
*No!* Not at all. We are human, we must err, or, do things which cause error messages.
As we get more people performing installations we will include "common" errors and hopefully provide reasonable solutions.
## Optional Pieces
I say "optional," but really I mean "very cool, but if it's already 2am and you've got stuff to do in the morning, it's alright if you come back later."
The following are the *cool things* around which Giterary was based: being able to use your own favorite editing tools, and being able to synchronize from any source, and in any direction.
### Being able to push/pull from Giterary
I can't recommend enough being able to push and pull from a setup external to the one running your Giterary instance. This is bread and butter of why you would use git for something like this in the first place. Unfortunately, unless you've worked with a version control system before, or have written programs collaboratively before, it's unlikely that you've been a part of this kind of workflow.
The first part of being able to push/pull using git is probably to learn more about git itself. There are a ton of sources out there to learn how to use Git.
* [gittutorial][gittutorial], git's own tutorial (admittedly dense).
* [git-scm's documentation and videos][git-scm], particularly their ["Distributed Git" section][dist]
* [Github's 15 minute tutorial][git-code-school]
Honestly, I learned git by way of Googling, man pages, and more furious Googling. The resources are out there. [Stackoverflow][stackoverflow] is rife with questions on git and its usage, and usually has great answers for some of the more subtle use cases around git. They may not be obvious, and the verbs are sometimes a little odd, but there are some amazing things you can do with git. Pushing and pulling is just the start.
[gittutorial]: http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html
[git-scm]: http://git-scm.com/documentation
[git-code-school]: http://try.github.com/levels/1/challenges/1
[dist]: http://git-scm.com/book/en/Distributed-Git
[stackoverflow]: http://stackoverflow.com/
What you first want to be able to do is use a git client to be able to *clone* your Giterary repository, and use it as one of its "origins." From there, you can see your Giterary files as they truly exist: in files and folders, named as close as could get to how they're represented in Giterary.
From there, you can open any file in your git repository working directory in your favorite text editor. You may or may not have the live-preview of Markdown, or whichever file format you're editing, but you also have a suite of tools available to you that are difficult or otherwise impossible to do from a web interface (multiple selections, column edits, search and replace, pattern recognition, intelligent spellchecking, etc.).
Save the file, and then use your git client to "commit." This is an important step in the git workflow. Committing to your repository informs git that "Yes, indeed, I intended to make those changes, and I think I'm ready to save these." Certain git clients smooth this over, informing you of changes and automatically adding them to your commit, which saves a bit of time. However, "true" git considers your working directory to be just that: *a work in progress*. It may be that you aren't done yet, but you may have *portions* of your work you want to commit. Or, you can stage your changes and swap out your entire working directory to focus on something else entirely. git, like Giterary, tries to help you with the hard stuff, but also tries to get out of your way when you just want to work.
After committing, you can "push" back to your Giterary origin. Depending on your Giterary setup (and the presence of your *post-receive git server hook* (as described later), you should see your updates reflected in the Giterary interface. If not, be sure that you clear the cache of the edited documents in question.
### Post-receive git server hook
git gives you the ability to push and pull from whatever repository you like. A recommended setup with Giterary is to synchronize a copy of your Giterary repository to a separate computer (your daily driver laptop, etc.), and synchronize via SSH.
This creates a problem, however. Potentially, you can push to your Giterary server repository, and while your push may succeed, the files in the working directory on the server may be out of sync.
To solve this, we use a feature of git called "hooks." In particular, there is a hook called the *post-receive* hook, which allows you to perform arbitrary user action on the server after successfully receiving your commits.
Put the following into */path/to/your/repo/.git/hooks/post-receive* to enable this feature:
#!/bin/bash
echo "Refreshing server's working tree";
/usr/local/bin/git --git-dir=/path/to/your/repo/.git --work-tree=/path/to/your/repo/ reset --hard;
exit 0;
Additionally, git takes issue with pushing into non-bare repositories. While normally this would be for good reason, Giterary needs to be able to push into a non-bare repository in order to synchronize its files for display on the Giterary interface.
git config receive.denyCurrentBranch ignore
----
[git]: http://git-scm.org/
[php]: http://php.net/
[apache]: http://httpd.apache.org/
[nginx]: http://nginx.org/
[iis]: http://www.iis.net/
[turnkey]: http://www.turnkeylinux.org/
[ssh]: http://openssh.com
[tortoisegit]: http://code.google.com/p/tortoisegit/wiki/Download
[sourcetree]: http://www.sourcetreeapp.com/# Giterary User Manual
The following document is a user's manual of sorts for day-to-day user interaction with a working Giterary instance. If you're having issues with configuration or installation, you should look at the [[INSTALL]] document.
This document takes you through basic understanding of the function of Giterary as a wiki, how to navigate and interact with document objects within the application, and how to create, modify, and view the change history of them.
## Giterary Concepts
Giterary 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](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. They vary in ubiquity and in features, given special use cases, extensibility, and popularity. Giterary's wiki features are inspired largely by [Mediawiki](http://www.mediawiki.org/wiki/MediaWiki) and [MoinMoin](http://moinmo.in/) (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 (":"), slash or 'solidus' ("/"), and non-printing characters (newline characters, etc.).
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.
#### Relative Paths
While descriptive, it is sometimes tedious to detail the full path for a file. Given a large or complicated enough structure (or even just a lengthy directory or file name), having to specify the full path to something can be redundant. This can also be a pain when file or directory renames occur, as the file links prior to a structural move can be broken (and usually as great scale, given how many files were moved).
To help with this, the concept of *relative paths* is available. These are useful to help your structures remain intact across renaming, as well as reduce repetition when creating document references. For instance, if you're viewing the following file:
Working Title/Bookmaking/Book1
...It is possible to create a link with the path specified like so:
[[./Act2/Scene3|Book 1, Act 2, Scene 3]]
Note the `./` prefix at the beginning of the path. The `./` prefix refers to the *current* document being viewed/rendered, replacing the `./` with the path prefix `Working Title/Bookmaking/Book1`. This is translated on the fly, and as it is relative to the document the link is generated from, it will survive a rename of your story from "Working Directory" to whatever you choose.
Another relative path function exists, which is to "go up" a directory. For instance, in the same `Book1` document, one could have the following link:
[[../Book2|Next Book]]
...which will translate the file path to be effectively the following:
[[Working Title/Bookmaking/Book2|Next Book]]
This `../` prefix can be repeated multiple times to "go up" as many directories as is necessary. However, note that you cannot "go up" past the root of the directory, and is considered an invalid path specification.
Relative paths can work where the question can be answered "What document am I viewing currently?" This means that all document links and all function links being rendered in a document can use relative paths rather than absolute paths.
### 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.
myusername/jot/2013/01/21-Mon
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.
There are also a number of ways that external portions of Giterary make use of the searching interface. For example, there are two special searches you can perfrom:
* From a given document display, you can select **Other Options > Search for ...What Links Here**, and return all documents that have wikilinks pointing to this page.
* From the top navigation "TODO" hyperlink when logged in, you can view a list of documents that contain special "TODO" flags within them that indicate work needing done at certain parts of a document. These work for both "TODO" and "TBD" patterns found within documents.
## 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:
* [[index:file=HELP,as=text|Plain text]]
* [[index:file=HELP&as=wrap|Hard-wrapped plain text]]
### 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, or Tables (*.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: