Merge changes from loren into master

loren authored
revision 12047c856f5a1ce7f15e48b018f8bf596fa4ec1c
Contents
About.txt
getting-started/GeneralOverview.txt
getting-started/ProjectTypes.txt
getting-started/versions.md
writing/Markdown.txt
writing/syntax-highlighting.txtections.md
writing/mathjax.md

writing/keyboard-shortcuts.md
writing/syntax-highlighting.txt
working-offline/WorkingOffline.txt
working-offline/SSHkeys.md
getting-started/versions
# Versions and Tags

First, what is **version control**? If you aren't familar with the concept, version control is simply a way to manage changes over time. If you've ever saved multiple versions of a document (like a *rough draft* and *final draft*), then you've hacked together your own version control system. Congrats! The problem with that is that it's fragile, inconvenient and difficult to manage - especially for long term projects with multiple collaborators.

Penflip handles all of this for you, so you can focus on writing.

### Versions

You can **think of a version like a copy of the project**. Versions change over time, and a Penflip project can have multiple versions. When you create a project, there's only a **master version**. The master version is the main version of the project, and only you can make changes to this version.

When collaborators join your project, a new version is created for each of them, automatically. For example, when your friend Tim joins your project, a new version will be created called 'tim'. When Tim makes changes to the project, those changes are only made on his version. The master version isn't updated until he submits his changes for approval.

When a collaborator edits your project, they will see a message like this:

![Screen_Shot_2014-01-23_at_12.29.17_PM.png](images/Screen_Shot_2014-01-23_at_12.29.17_PM.png)


### Submitting changes

After a collaborator makes changes on their version, they submit them for your approval, describing the changes they've made:

![submit_changes.jpg](images/submit_changes.jpg)

----
![submit_changes_dialog.jpg](images/submit_changes_dialog.jpg)

### Accepting changes

As the project owner, you will be notified of submitted changes via email, with a link to view the changes. From there, you can choose to accept or ignore the changes. If you accept the changes, the master version of the project will be updated with the new changes.

This is convenient because you can send a project link to your peers, request feedback, and only integrate the feedback you want to accept - all with the click of a button, in the browser.

### Tags

When you're editing your project, you can create tags. You can **think of a tag like a checkpoint or reference point** - marking a project in its current state at a specific time. For example, after you've released the first version of a book, you can create a 'version1' tag. You can continue making updates and changes to your book, but you can always go back to 'version1' to see how the book looked at that time.

Create a tag by clicking on the 'Save' icon while editing, then typing a tag name under 'Tag this version':

![tagging.jpg](images/tagging.jpg)

### Viewing versions and tags

On a project page, you see the master version by default. You can switch to any version or tag using a toggle in the bottom right corner. You can also download the project with any version or tag after you've switched.

![switch-version.jpg](images/switch-version.jpg)

*Note: this will not display unless there are multiple versions or tags.*






images/screen-shot-2014-09-08-at-43139-pm
working-offline/WorkingOffline
# Working Offline with Git

Internally, Penflip uses [Git](http://git-scm.com) to manage versions, changes, and merges. By using Git or a Git-enabled tool, you can sync writing projects on your computer with Penflip. This allows you to work offline (using any text editor you want), then _push_ your changes to Penflip with a single click.

### Using command-line Git

If you are familiar with using Git from the command-line, you can have at it. The clone URL to use is available from your project's "Settings" page.

If you want to work offline with command-line Git on a version of another's project, here are some pointers to make it work:

1. Get the clone link of the project. This is the link you see on top of the page of the project + .git. For example with this project you do

git clone https://www.penflip.com/Penflip/help.git

2. Work locally
3. Push to your version branch, for example user `loren` would do

git push origin master:loren


### Using the GitHub desktop app

_Note: I'll be using the Mac app here, but the steps should be similar for the Windows app._

**1) Download and install the GitHub desktop app**

For Mac: http://mac.github.com/

For Windows: http://windows.github.com/


**2) Create a project on Penflip**

If you don't have a project yet, create a project here: http://www.penflip.com/projects/new


**3) Download your project**

You can download your project and add it to the GitHub app at the same time.

For Mac, type this in your browser:

**github-mac://openRepo/PENFLIP-LINK-TO-YOUR-PROJECT**

For Windows, type this in your browser:

**github-windows://openRepo/PENFLIP-LINK-TO-YOUR-PROJECT**

Make sure to include the full link to your Penflip project. For example:

github-mac://openRepo/http://www.penflip.com/loren/how-to-work-offline

The GitHub app will open. Select where you want to download your project to, and click 'Clone'.

![Screen_Shot_2013-09-28_at_2.32.08_PM.png](images/Screen_Shot_2013-09-28_at_2.32.08_PM.png)

You now have a copy of your project on your computer, including the full history of changes you (and your collaborators) have made.

![Screen_Shot_2013-09-28_at_2.34.59_PM.png](images/Screen_Shot_2013-09-28_at_2.34.59_PM.png)


**4) Make changes**

Your project is now on your computer like any other file or folder. You can make changes using and text editor. Here, I'm using textmate.

![Screen_Shot_2013-09-28_at_2.39.21_PM.png](images/Screen_Shot_2013-09-28_at_2.39.21_PM.png)


**5) Sync changes with Penflip**

The following steps are done through the GitHub app.

Switch to the 'Changes' tab:

![Screen_Shot_2013-09-28_at_2.42.33_PM.png](images/Screen_Shot_2013-09-28_at_2.42.33_PM.png)

Turn on 'Commit & Sync' (square toggle switch):

![Screen_Shot_2013-09-28_at_2.41.49_PM.png](images/Screen_Shot_2013-09-28_at_2.41.49_PM.png)

Type a description of your changes in the 'Commit summary' box:

![Screen_Shot_2013-09-28_at_2.43.59_PM.png](images/Screen_Shot_2013-09-28_at_2.43.59_PM.png)

Click 'Commit & Sync':

![Screen_Shot_2013-09-28_at_2.46.12_PM.png](images/Screen_Shot_2013-09-28_at_2.46.12_PM.png)


**6) Done!**

Verify that your changes have been synced with Penflip by looking at your project page.

![Screen_Shot_2013-09-28_at_2.48.09_PM.png](images/Screen_Shot_2013-09-28_at_2.48.09_PM.png)

---
Still confused? Email support@penflip.com for help!
writing/Markdown
# Markdown Cheatsheet

Forked from [here](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet).

- [Headers](#headers)
- [Emphasis](#emphasis)
- [Lists](#lists)
- [Links](#links)
- [Images](#images)
- [Code and Syntax Highlighting](#code)
- [Tables](#tables)
- [Footnotes](#footnotes)
- [Blockquotes](#blockquotes)
- [Inline HTML](#html)
- [Horizontal Rule](#hr)
- [Line Breaks](#lines)
- [Escaping Control Characters](#escape)
- [Youtube videos](#videos)

---

## Headers

```no-highlight
# H1
## H2
### H3
#### H4
##### H5
###### H6

Alternatively, for H1 and H2, an underline-ish style:

Alt-H1
======

Alt-H2
------
```

# H1
## H2
### H3
#### H4
##### H5
###### H6

Alternatively, for H1 and H2, an underline-ish style:

Alt-H1
======

Alt-H2
------

----

## Emphasis

```no-highlight
Emphasis, aka italics, with *asterisks* or _underscores_.

Strong emphasis, aka bold, with **asterisks** or __underscores__.

Combined emphasis with **asterisks and _underscores_**.

Strikethrough uses two tildes. ~~Scratch this.~~
```

Emphasis, aka italics, with *asterisks* or _underscores_.rr

Strong emphasis, aka bold, with **asterisks** or __underscores__.

Combined emphasis with **asterisks and _underscores_**.

Strikethrough uses two tildes. ~~Scratch this.~~


---

## Lists

(In this example, leading and trailing spaces are shown with with dots: ⋅)

```no-highlight
1. First ordered list item
2. Another item
⋅⋅* Unordered sub-list.
1. Actual numbers don't matter, just that it's a number
⋅⋅1. Ordered sub-list
4. And another item.

⋅⋅⋅You can have properly indented paragraphs within list items. Notice the blank line above, and the leading spaces (at least one, but we'll use three here to also align the raw Markdown).

⋅⋅⋅To have a line break without a paragraph, you will need to use two trailing spaces.⋅⋅
⋅⋅⋅Note that this line is separate, but within the same paragraph.⋅⋅
⋅⋅⋅(This is contrary to the typical GFM line break behaviour, where trailing spaces are not required.)

* Unordered list can use asterisks
- Or minuses
+ Or pluses
```

1. First ordered list item
2. Another item
* Unordered sub-list.
1. Actual numbers don't matter, just that it's a number
1. Ordered sub-list
4. And another item.

You can have properly indented paragraphs within list items. Notice the blank line above, and the leading spaces (at least one, but we'll use three here to also align the raw Markdown).

To have a line break without a paragraph, you will need to use two trailing spaces.
Note that this line is separate, but within the same paragraph.
(This is contrary to the typical GFM line break behaviour, where trailing spaces are not required.)

* Unordered list can use asterisks
- Or minuses
+ Or pluses

---

## Links

There are two ways to create links.

```no-highlight
[I'm an inline-style link](https://www.google.com)

[I'm an inline-style link with title](https://www.google.com "Google's Homepage")

[I'm a reference-style link][Arbitrary case-insensitive reference text]

[I'm a relative reference to a repository file](../blob/master/LICENSE)

[You can use numbers for reference-style link definitions][1]

Or leave it empty and use the [link text itself]

Some text to show that the reference links can follow later.

[arbitrary case-insensitive reference text]: https://www.mozilla.org
[1]: http://slashdot.org
[link text itself]: http://www.reddit.com
```

[I'm an inline-style link](https://www.google.com)

[I'm an inline-style link with title](https://www.google.com "Google's Homepage")

[I'm a reference-style link][Arbitrary case-insensitive reference text]

[I'm a relative reference to a repository file](../blob/master/LICENSE)

[You can use numbers for reference-style link definitions][1]

Or leave it empty and use the [link text itself]

Some text to show that the reference links can follow later.

[arbitrary case-insensitive reference text]: https://www.mozilla.org
[1]: http://slashdot.org
[link text itself]: http://www.reddit.com

---

## Images

```no-highlight
Here's a logo (hover to see the title text):

Inline-style:
![alt text](https://github.com/adam-p/markdown-here/raw/master/src/common/images/icon48.png "Logo Title Text 1")

Reference-style:
![alt text][logo]

[logo]: https://github.com/adam-p/markdown-here/raw/master/src/common/images/icon48.png "Logo Title Text 2"

```

Here's a logo (hover to see the title text):

Inline-style:
![alt text](https://github.com/adam-p/markdown-here/raw/master/src/common/images/icon48.png "Logo Title Text 1")

Reference-style:
![alt text][logo]

[logo]: https://github.com/adam-p/markdown-here/raw/master/src/common/images/icon48.png "Logo Title Text 2"

---

## Code and Syntax Highlighting

Code blocks are part of the Markdown spec, but syntax highlighting isn't. However, many renderers -- like Github's and *Markdown Here* -- support syntax highlighting. *Markdown Here* supports highlighting for dozens of languages (and not-really-languages, like diffs and HTTP headers); to see the complete list, and how to write the language names, see the [highlight.js demo page](http://softwaremaniacs.org/media/soft/highlight/test.html).

```no-highlight
Inline `code` has `back-ticks around` it.
```

Inline `code` has `back-ticks around` it.

Blocks of code are either fenced by lines with three back-ticks ```, or are indented with four spaces. I recommend only using the fenced code blocks -- they're easier and only they support syntax highlighting.

```no-highlight
```javascript
var s = "JavaScript syntax highlighting";
alert(s);
```

```python
s = "Python syntax highlighting"
print s
```

```
No language indicated, so no syntax highlighting.
But let's throw in a tag.
```
```

```javascript
var s = "JavaScript syntax highlighting";
alert(s);
```

```python
s = "Python syntax highlighting"
print s
```

```
No language indicated, so no syntax highlighting in Markdown Here (varies on Github).
But let's throw in a tag.
```

(Github Wiki pages don't seem to support syntax highlighting, so the above won't be colourful (the strings are not red, for example). Try it out in a *Markdown Here* email or a Github Markdown README or Github Issue -- you can preview a new Issue without submitting it.)

Again, to see what languages are available for highlighting, and how to write those language names, see the [highlight.js demo page](http://softwaremaniacs.org/media/soft/highlight/test.html).

---

## Tables

Tables aren't part of the core Markdown spec, but they are part of GFM and *Markdown Here* supports them. They are an easy way of adding tables to your email -- a task that would otherwise require copy-pasting from another application.

```no-highlight
Colons can be used to align columns.

| Tables | Are | Cool |
| ------------- |:-------------:| -----:|
| col 3 is | right-aligned | $1600 |
| col 2 is | centered | $12 |
| zebra stripes | are neat | $1 |

The outer pipes (|) are optional, and you don't need to make the raw Markdown line up prettily. You can also use inline Markdown.

Markdown | Less | Pretty
--- | --- | ---
*Still* | `renders` | **nicely**
1 | 2 | 3
```

Colons can be used to align columns.

| Tables | Are | Cool |
| ------------- |:-------------:| -----:|
| col 3 is | right-aligned | $1600 |
| col 2 is | centered | $12 |
| zebra stripes | are neat | $1 |

The outer pipes (|) are optional, and you don't need to make the raw Markdown line up prettily. You can also use inline Markdown.

Markdown | Less | Pretty
--- | --- | ---
*Still* | `renders` | **nicely**
1 | 2 | 3

---

## Footnotes

Footnotes are not supported in standard markdown, but Penflip allows footnotes:

Here is a footnote reference [^1].

[^1]: Here is the footnote.

---

## Escaping Control Characters
```
Sometimes, you need to use plus, minus, underscore, curly and straight braces, backticks and others without them being registered as part of Markdown.

In this case, you use backslashes to escape them, like this: \* \_ \- \+ \{ \] \} \[ \# \` \\
```
Sometimes, you need to use plus, minus, underscore, curly and straight braces, backticks and others without them being registered as part of Markdown.

In this case, you use backslashes to escape them, like this: \* \_ \- \+ \{ \] \} \[ \# \` \( \) \\


---

## Blockquotes

```no-highlight
> Blockquotes are very handy in email to emulate reply text.
> This line is part of the same quote.

Quote break.

> This is a very long line that will still be quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can *put* **Markdown** into a blockquote.
```

> Blockquotes are very handy in email to emulate reply text.
> This line is part of the same quote.

Quote break.

> This is a very long line that will still be quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can *put* **Markdown** into a blockquote.

---

## Inline HTML

You can also use raw HTML in your Markdown, and it'll mostly work pretty well.

```no-highlight

Definition list

Is something people use sometimes.


Markdown in HTML

Does *not* work **very** well. Use HTML tags.


```


Definition list

Is something people use sometimes.


Markdown in HTML

Does *not* work **very** well. Use HTML tags.



---

## Horizontal Rule

```
Three or more...

---

Hyphens

***

Asterisks

___

Underscores
```

Three or more...

---

Hyphens

***

Asterisks

___

Underscores

---

## Line Breaks

My basic recommendation for learning how line breaks work is to experiment and discover -- hit once (i.e., insert one newline), then hit it twice (i.e., insert two newlines), see what happens. You'll soon learn to get what you want. "Markdown Toggle" is your friend.

Here are some things to try out:

```
Here's a line for us to start with.

This line is separated from the one above by two newlines, so it will be a *separate paragraph*.

This line is also a separate paragraph, but...
This line is only separated by a single newline, so it's a separate line in the *same paragraph*.
```

Here's a line for us to start with.

This line is separated from the one above by two newlines, so it will be a *separate paragraph*.

This line is also begins a separate paragraph, but...
This line is only separated by a single newline, so it's a separate line in the *same paragraph*.

(Technical note: *Markdown Here* uses GFM line breaks, so there's no need to use MD's two-space line breaks.)

---

## Youtube videos

They can't be added directly but you can add an image with a link to the video like this:

```no-highlight
alt="IMAGE ALT TEXT HERE" width="240" height="180" border="10" />
```

Or, in pure Markdown, but losing the image sizing and border:

```no-highlight
[![IMAGE ALT TEXT HERE](http://img.youtube.com/vi/YOUTUBE_VIDEO_ID_HERE/0.jpg)](http://www.youtube.com/watch?v=YOUTUBE_VIDEO_ID_HERE)
```

---
Still confused? Email support@penflip.com for help!
writing/mathjax
# MathJax

Penflip uses the MathJax javascript library to display mathematical notation. Notation is written in LaTeX and wrapped in delimiters. Penflip uses \( ... \) for **inline math**, and $$ ... $$ for **display math**.

### Inline Math

Penflip uses \( ... \) for inline math delimiters. Here's an example:

![inline math](https://dl.dropboxusercontent.com/u/10941557/Penflip/mathjax-inline-2.png)

is rendered as:

Pythagorean equation: \(a^2 + b^2 = c^2\)

### Display Math

Penflip uses $$ ... $$ for display math delimiters. Unlike inline equations, display equations must be written on their own line. Display math delimiters can be included on the equation line, or on lines preceding and following the equation line (spanning three lines). Here's an example:

![display math](https://dl.dropboxusercontent.com/u/10941557/Penflip/mathjax-display.png)

is rendered as:

$$
x = {-b \pm \sqrt{b^2-4ac} \over 2a}
$$

## Resources

- [MathJax documentation](http://docs.mathjax.org/en/latest/)
- [LaTeX mathematics documentation](http://en.wikibooks.org/wiki/LaTeX/Mathematics)
writing/sections
# Sections and Folders

Folders can be created in the web editor to organize your book or writing project. Not only are folders a handy way to split your project into manageable pieces for editing, they're also used for display.

Folders are represented as "sections" outside the editor. [Penflip Help](https://www.penflip.com/Penflip/help), for example, has the following sections: _Getting Started_, _Writing_, and _Working Offline_. Each of these sections is actually folder containing numerous files.

When a project is downloaded as a PDF, folders become "parts", and are included in the table of contents with chapters nested beneath them.

### Organizing folders

Within the Penflip editor, folders can be dragged and dropped to reorder. Files can be dragged and dropped between folders.

### Hiding folders

If you do not want to include a folder in the compiled output (e.g. a _notes_ folder), there is no shortcut for currently doing so. You'll have to manually hide each file within the folder.

### Renaming folders

_Unsupported in the Penflip editor at this time, coming soon!_

Currently could be done offline by editing content of the file \_title.md in the target folder.

### Deleting folders

As a precaution, you can only delete empty folders. To delete a folder with contents, first delete or move the contents to another folder.