From bbf3cf7e69e0416a0fefb30c4ceccd9eedf0a7bf Mon Sep 17 00:00:00 2001
From: P. J. McDermott <pehjota>
Date: Sat, 22 Sep 2012 02:47:15 -0400
Subject: Write an "Editing this Wiki" page.

---
(limited to 'wiki/editing.mdwn')

diff --git a/wiki/editing.mdwn b/wiki/editing.mdwn
new file mode 100644
index 0000000..1ae1cbb
--- /dev/null
+++ b/wiki/editing.mdwn
@@ -0,0 +1,127 @@
+[[!meta title="Editing this Wiki"]]
+
+This wiki is managed using [ikiwiki][ikiwiki].  Pages are formatted in
+[Markdown][mdwn] and stored in [a Git repository][wiki-git].
+
+This page offers instructions to help new editors work with this wiki.
+Additonal assistance may be requested on the IRC channel.
+
+
+Repository Editing
+==================
+
+These sections assume at least a basic familiarity with the Git revision control
+system.  Numerous books and tutorials for Git exist on the Web, and Git's
+included manual pages are a great reference.
+
+Cloning
+-------
+
+To work with the wiki repository, you first need to clone it (using
+**git-clone**(1)).  The following commands will get you a copy of the full
+repository and make it your working directory:
+
+    git clone git://git.os.libiquity.com/www/wiki.git embedded-os-wiki
+    cd embedded-os-wiki
+
+Editing, Staging, and Committing
+--------------------------------
+
+Now you can simply edit files in your favorite text editor.
+
+When you've made some changes, stage them to the index with **git-add**(1) and
+commit them to the repository with **git-commit**(1).  For example:
+
+    git add wiki/editing.mdwn
+    git commit
+
+All of the usual recommendations for commit messages (50-character summary,
+followed optionally by an empty line and detailed text wrapped at 72 characters)
+apply.
+
+Be aware that the author usernames shown in the wiki's
+[[change_log|recentchanges]] come from the author email addresses in commits.
+You can set just this value (and thus your username for the wiki) by setting the
+`GIT_AUTHOR_EMAIL` environment variable before running `git commit`.
+
+Pushing
+-------
+
+When you've committed some changes, you can push them to the public repository
+(the "origin" which you cloned) using **git-push**(1).  For example:
+
+    git push origin master:master
+
+The shorter `git push` should also work, unless you modified the default remote
+and/or ref in your repository configuration.
+
+As soon as the Git daemon receives your changes, it will run ikiwiki's Git hook
+to rebuild the pages you've edited.  You can then immediately view the new pages
+on the wiki in your Web browser.
+
+Pulling
+-------
+
+You might need to fetch and merge recent changes using **git-pull**(1),
+especially if you haven't fetched anything from the public repository in a
+while.  For example:
+
+    git pull origin master
+
+
+Web Editing
+===========
+
+This wiki also supports editing by authenticated users through an interactive
+Web interface.
+
+However, the Web authentication and editing interface for this wiki is not yet
+well-tested.  Committing to the repository is currently the recommended method
+to edit this wiki.
+
+
+Formatting Syntax
+=================
+
+Basic Syntax and File Extensions
+--------------------------------
+
+The basic formatting syntax used by this wiki is [Markdown][mdwn].  It is easy
+to read and can be learned quickly.  See John Gruber's [Markdown syntax
+description][mdwn-syn] to learn more.
+
+All wiki page files must have names ending in ".mdwn".  This tells ikiwiki that
+they should be rendered into HTML using the Markdown processor.
+
+Page Titles
+-----------
+
+Each wiki page should be given a title.  This can be done using the [`meta`
+directive][ikiwiki-meta] of ikiwiki's "meta" plugin.  For example, this page
+begins with the following directive:
+
+    [[!meta title="Editing this Wiki"]]
+
+Wiki Links
+----------
+
+Ikiwiki has [its own syntax][ikiwiki-wikilink] for links to other pages within
+the wiki.  For example, `\[[editing_this_wiki|wiki/editing]]` results in a link
+like this: [[editing_this_wiki|wiki/editing]].
+
+Images
+------
+
+Images may be committed and pushed to the wiki.
+
+They can then be included on wiki pages using the [`img` directive][ikiwiki-img]
+of ikiwiki's "img" plugin.
+
+
+[ikiwiki]: http://ikiwiki.info/
+[mdwn]: http://daringfireball.net/projects/markdown/
+[wiki-git]: http://git.os.libiquity.com/www/wiki.git/
+[mdwn-syn]: http://daringfireball.net/projects/markdown/syntax
+[ikiwiki-meta]: http://ikiwiki.info/ikiwiki/directive/meta/
+[ikiwiki-wikilink]: http://ikiwiki.info/ikiwiki/wikilink/
+[ikiwiki-img]: http://ikiwiki.info/ikiwiki/directive/img/
--
cgit v0.9.1