Pokology - a community-driven site around GNU poke
                             

     _____
 ---'   __\_______
            ______)         
Contributing to the site
            __)             
           __)
 ---._______)


Table of Contents
_________________

1. Getting access to pokology.git
2. Contents of pokology.git
3. Altering the contents of an existing page
4. Creating new pages
5. Hints on formatting


*Pokology* is made by the GNU poke community: developers, users and
friends.  Anybody is very welcome to add new content and to improve the
existing pages.  This page describes how.


1 Getting access to pokology.git
================================

  The contents of *Pokology* are written in Org mode files
  (https://orgmode.org) and stored in a git repository hosted on
  ageinghacker.net: http://git.ageinghacker.net/pokology

  You can clone a read-only version of the site via HTTP, like this:

  ,----
  | $ git clone http://git.ageinghacker.net/pokology
  `----


  Cloning via HTTP requires no authentication or authorisation.  However
  in order to contribute to the site you will need write access to the
  git repository.  To obtain it, please write an email to
  poke-devel@gnu.org requesting access to Pokology.  Someone will
  promptly get back to you, and ask you for several details including a
  public SSH key.

  Once you have write access, you must be able to clone a write-enabled
  working copy of the repository, via SSH:

  ,----
  | $ git clone git@ageinghacker.net:/pokology.git
  `----


2 Contents of pokology.git
==========================

  The layout of the site is very simple.  You will find the following
  kind of files in the repo:

  - Org-mode files that use the extension .org.  These are the files
    that provide the contents of the site, and that at some point get
    processed to generate corresponding HTML files.

  - A CSS file pokology.css, which provides the style applied in the
    entire site.

  - A couple of scripts pull-pokology.sh and publish-pokology.sh, which
    are used at the server side in order to generate the HTML pages from
    the Org-mode sources.

  As an author, you will be mostly concerned with the Org-mode files.


3 Altering the contents of an existing page
===========================================

  Editing the contents of an existing page FOO.html involves to edit the
  corresponding FOO.org file.  The best way to edit Org-mode files is
  with Emacs, but other editors (like VI derivatives) have also support
  for the format.  Any text editor will do the work.

  Once you are happy with the changes in the .org files, commit the
  changes and push them to ageinghacker.net.  A cron job in the server
  will eventually pick up your changes and regenerate the .html files
  accordingly.


4 Creating new pages
====================

  Creating new pages is also easy: just add a new .org file to the
  top-level directory; you can also create sub-directories.  When adding
  new files, use a header similar to this:

  ,----
  | #+title:      SOME TITLE
  | #+email:      poke-devel AT gnu DOT org
  | #+language:   en
  | #+category:   pokology
  | #+options:    H:3 \n:nil ::t |:t ^:t -:t f:t *:t tex:t d:(HIDE) author:nil
  `----

  Then commit and push the change to ageinghacker.net.  A cron-job will
  pick up the new files and generate HTML for them.


5 Hints on formatting
=====================

  The formatting and structuring tags (emphasis, sections, subsections,
  tables, etc) you can use in .org files are fully documented in the
  Org-mode manual (https://orgmode.org/manual).

  Some recommendations when writing Pokology contents:

  - If you don't want a table of contents then specify toc:nil at the
    #+options header line.

  - If you don't want numbered sections and subsections then specify
    num:nil at the #+options header line.

  - Use links like file:foo/bar.org in order to link to other Pokology
    pages.