Clarify git wiki instructions
[openafs-wiki.git] / devel / GitWiki.mdwn
index f3b3d51..a897390 100644 (file)
@@ -1,51 +1,47 @@
 # Using git to edit the OpenAFS wiki
 
-Unlike most wiki engines, which generate html from database records,
-the wiki engine on the OpenAFS wiki site generates static html files
-from a set of source files in markdown format. Revision history of the
-pages is managed with git. The OpenAFS gerrit system has been
-configured to accept git pushes to update the wiki, which means it is
-now possible to update this site using git directly.
-
-This page describes how to use git to create and edit pages on this wiki
-as an alternative to the online web form. A local wiki setup is
-described to allow you to preview changes before pushing them to the
-public wiki. One advantage to this approach is that you can edit while
-offline, and then submit your work later, as you would for any other git
-based project. Also, using git for making changes is especially handy
-when making a series of changes which should be committed together, such
-as reorganizing pages and links.
+Unlike most wiki engines, which generate html from database records, the wiki
+engine on the OpenAFS wiki site generates static html files from a set of
+source files in markdown format. Revision history of the pages is managed with
+git. The OpenAFS gerrit system has been configured to accept git pushes to
+update the wiki, which means it is now possible to update this site using git
+directly.
+
+This page describes how to use git to create and edit pages on this wiki as an
+alternative to the online web form. A local wiki setup is described to allow
+you to preview changes before pushing them to the public wiki. One advantage to
+this approach is that you can edit while offline and then submit your work
+later, as you would for any other git based project. Using git for making
+changes is especially handy when making a series of changes which should be
+committed together, such as reorganizing pages and links.
 
+## Prerequisites
 
 Read [[GitDevelopers]] before following the instructions on this page.
 
-## Prerequisites
-
 The following are needed to be able to edit the wiki pages with git.
 
-* git installed and configured with your name and email.
+* `git` is installed and configured with your name and email.
 * an OpenAFS gerrit account; see [[registering with gerrit|GitDevelopers]] for details.
 
-A installation of the ikiwiki software on your laptop or workstation is
-recommended so you can preview your changes before submitting them to the
-OpenAFS wiki. This requires:
+A installation of the `ikiwiki` software on your laptop or workstation is
+recommended but is optional. This will allow you preview your changes before
+submitting them to the OpenAFS wiki. The `ikiwiki` requires:
 
 * [[ikiwiki|http://ikiwiki.info]] installation
 * a basic ikiwiki setup file (shown below)
-* a browser
+* a basic httpd setup
 
 ## Getting the wiki source pages
 
-Use `git clone` to get the openafs-wiki source files:
+Use `git clone` to get the openafs-wiki source files from the
+`gerrit.openafs.org` repo.
 
     git clone ssh://gerrit.openafs.org/openafs-wiki.git
 
-This will clone the wiki git repository to a new directory called
-'openafs-wiki'.
-
 Set up your OpenSSH configuration to connect to the gerrit server port as
 described in [[GitDevelopers]].  The commit hook which generates a gerrit
-'change id' as described in [[GitDevelopers]] is not required for pushing
+'change id' as described in [[GitDevelopers]] is *not required* for pushing
 openafs-wiki changes to gerrit.
 
 Note: At this time, the git.openafs.org repo (gitweb) can trail the canonical
@@ -55,6 +51,19 @@ to make changes by pulling and pushing via git, you must pull from the
 gerrit.openafs.org repository above. If you pull from git.openafs.org,
 subsequent pushing may fail.
 
+## Editing pages
+
+When you are satisfied with your changes, use `git add` and `git commit` to
+create a commit to be submitted. To publish your changes on the wiki, push your
+commits *directly* to the **master** branch `master`. Do **not**
+push to the gerrit review branch `refs/for/master`.
+
+    git push origin master
+
+The commit will be merged immediately to the openafs-wiki.git repository.  The
+html on the wiki server will be automatically updated after a successful `git
+push` after a few moments.  The changes will not be held by gerrit for review.
+
 ## Setting up ikiwiki to preview your changes
 
 This is an optional but recommended step. The ikiwiki software can be installed
@@ -68,7 +77,7 @@ ikiwiki on a Debian or Ubuntu system.
     sudo apt-get install ikiwiki
 
 See [[ikiwiki downloads|http://ikiwiki.info/download]] for installation
-instructions for other various platforms.
+instructions for other platforms.
 
 Create a minimal ikiwiki configuration file by saving the following in
 the file '~/openafs-wiki.setup',  where `<username>` is your username:
@@ -96,31 +105,14 @@ static html files in that directory:
 
     ikiwiki --setup ~/openafs-wiki.setup
 
-The pages may be previewed locally by pointing your browser at:
+Install a httpd server, such as apache.  Configure the document root to be the
+same as the `destdir` path in the `openafs-wiki.setup` file.
 
-    file:///home/<username>/public_html/openafs-wiki/index.html
+The pages may be previewed locally by pointing your browser at:
 
-## Editing pages
+    http://localhost/
 
-You can now use your favorite text editor to change the markdown source and to
-create new markdown files. When creating new files, be sure to create new links
-on existing pages so visitors will be able to navigate to your
-new page. Run the following `ikiwiki` command to regenerate the html files from
-the source files.
+Run the following `ikiwiki` command to regenerate the html files from the
+source files after making any changes to the source files.
 
     ikiwiki --setup ~/openafs-wiki.setup --refresh
-
-To preview a page, point your browser at:
-
-    file:///home/<username>/public_html/openafs-wiki/
-
-When you are satified with your changes, use `git add` and `git commit` to
-create a commit to be submitted, then to publish your changes on the wiki, push
-your commits directly to the 'master' branch of the openafs-wiki.git repository
-on gerrit.
-
-    git push ssh://gerrit.openafs.org/openafs-wiki.git HEAD:refs/heads/master
-
-The changes will not be held by gerrit for review.  The commit will be merged
-immediately to the openafs-wiki.git repository and the html on the wiki server
-will be automatically updated after a successful 'git push'.