web: Move hover menu slightly up
[gnupg-doc.git] / README
1 README for the gnupg-doc repository                         -*- org -*-
2
3 This is a separated branch for the gnupg.org website.
4
5 The old website was tracked in a CVS repository but we want to start
6 the new website form scratch using only the texts from the generated
7 HTML files.
8
9 ** Directory structure
10
11    - web/      :: Source files for the web.  This also include images
12                   etc.
13    - web/share :: Logos, CSS, macros and elisp for building.
14    - misc      :: Other websites etc.
15                   - blog.gnupg.org
16                   - git.gnupg.org
17                   - howtos.gnupg.org :: Manuals etc.
18    - build-aux :: Build helper rscripts
19    - tools/    :: Tools used to build the web site.
20    - stage/    :: staging directory for the site.
21
22 ** Aliases
23
24 www.gnupg.org uses Boa to serve the pages, here are the aliases we
25 use:
26
27 #+BEGIN_EXAMPLE
28 # The manuals are maintained outside of the web pages;
29 # thus we use an alias to copy them in.
30 Alias /documentation/manuals /var/www/shared/manuals
31 Alias /gph /var/www/shared/gph
32
33 # The FAQ is located in the manuals directory but linked to the faq directory
34 Alias /faq/GnuPG-FAQ.html  /var/www/shared/manuals/GnuPG-FAQ.html
35
36
37 # Redirect a couple of well-known URLs
38 Redirect /gpa.html      http://www.gnupg.org/related_software/gpa/
39 Redirect /gpgme.html    http://www.gnupg.org/related_software/gpgme/
40 Redirect /docs.html     http://www.gnupg.org/documentation/
41 Redirect /download.html http://www.gnupg.org/download/
42 Redirect /faq.html      http://www.gnupg.org/documentation/faqs.html
43
44 # We use redirect to make language switching work.
45 Redirect /why-not-idea.html  http://www.gnupg.org/faq/why-not-idea.html
46
47 Redirect /howtos/ch/  http://www.gnupg.org/howtos/zh/
48
49 Redirect /fund   http://goteo.org/project/gnupg-new-website-and-infrastructure
50
51 #+END_EXAMPLE
52
53 The howtos are symlinked into the www.gnupg.org tree.
54
55
56 ** Symlinks
57
58 For compatibility with the old website it is best to run this script
59 in the htdocs directory:
60
61 for d in $(find . -type d); \\
62    do (cd $d && for f in $(ls *.html | grep -v '*.??.html'); \\
63        do ln -s $f ${f%.html}.en.html; ln -s $f ${f%.html}.de.html ; \\
64    done ); done
65
66 ** Cronjobs
67
68   A cronjob needs to run mkkudos.sh to update the list of donors.
69   This can be done every few minutes becuase mkkudos won't do anything
70   if the list of donors has not been updated.
71
72 ** Writing a blog entry
73
74   The misc/blog.gnupg.org directory is used for the blogging system.
75   On the web server it is symlinked to /blog/.  To build and upload all
76   blogs you cd to misc/blog.gnupg.org and run the command ./upload.
77   This renders the org files into html, builds an index, and uploads
78   the html files to the web server.  Emacs and a decent org-mode are
79   required (tested with org-mode 8.2.7).
80
81   To add a new blog entry, decide on the publication date and create
82   a file
83
84     YYYYMMDD-short-headline.org
85
86   for example "20141030-what-happened-this-month.org".  Unless you
87   translate an existing entry do not use a file name which ends in
88   ".??.org".  The file itself is a standard org file using these
89   conventions:
90
91   ===== 8< =========
92   # Comment
93   #+AUTHOR: Werner
94   #+DATE: 30th October 2014
95
96   ** What happened in October 2014
97
98   Blurb
99   ===== >8 =========
100
101   AUTHOR and DATE are used to construct the "Posted at" info.  The
102   headline needs to start at level 2.