Merge branch 'master' of git+ssh://playfair.gnupg.org/git/gnupg-doc
[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 blog is maintained outside of the standard tree, so that it can be build using
34 # a separate script.
35 Alias /blog /var/www/www/www.gnupg.org/misc/blog
36
37 # Redirect a couple of well-known old URLs
38 # We use redirect to make language switching work.
39 Redirect /gpa.html       http://www.gnupg.org/related_software/gpa/
40 Redirect /gpgme.html     http://www.gnupg.org/related_software/gpgme/
41 Redirect /docs.html      http://www.gnupg.org/documentation/
42 Redirect /download.html  http://www.gnupg.org/download/
43 Redirect /faq.html       http://www.gnupg.org/documentation/faqs.html
44 Redirect /faqs.html      http://www.gnupg.org/documentation/faqs.html
45 Redirect /gpgme-faq.html http://www.gnupg.org/faq/gpgme-faq.html
46 Redirect /gnupg-faq.html http://www.gnupg.org/documentation/faqs.html
47 Redirect /GnuPG-FAQ.html http://www.gnupg.org/documentation/faqs.html
48 Redirect /supported_systems.html     http://www.gnupg.org/download/supported_systems.html
49 Redirect /release_notes.html         http://www.gnupg.org/download/release_notes.html
50 Redirect /integrity_check.html       http://www.gnupg.org/download/integrity_check.html
51 Redirect /cvs_access.html            http://www.gnupg.org/download/cvs_access.html
52 Redirect /iconv.html                 http://www.gnupg.org/download/iconv.html
53 Redirect /manpage.html               http://www.gnupg.org/documentation/manpage.html
54 Redirect /sites.html                 http://www.gnupg.org/documentation/sites.html
55 Redirect /guides.html                http://www.gnupg.org/documentation/guides.html
56 Redirect /manuals.html               http://www.gnupg.org/documentation/manuals.html
57 Redirect /mailing-lists.html         http://www.gnupg.org/documentation/mailing-lists.html
58 Redirect /howtos.html                http://www.gnupg.org/documentation/howtos.html
59 Redirect /bts.html                   http://www.gnupg.org/documentation/bts.html
60 Redirect /weak-digest-algos.html     http://www.gnupg.org/faq/weak-digest-algos.html
61 Redirect /subkey-cross-certify.html  http://www.gnupg.org/faq/subkey-cross-certify.html
62 Redirect /why-not-idea.html          http://www.gnupg.org/faq/why-not-idea.html
63
64 Redirect /howtos/ch/  http://www.gnupg.org/howtos/zh/
65
66 # Temporary:
67 Redirect /fund   http://goteo.org/project/gnupg-new-website-and-infrastructure
68
69 #+END_EXAMPLE
70
71 The howtos are symlinked into the www.gnupg.org tree; see below.
72
73
74 ** Symlinks
75
76 #+begin_example
77 howtos -> ../../howtos.gnupg.org/htdocs
78 related_software -> software
79 features.html -> software/index.html
80 #+end_example
81
82 The website-build script assures that these symlinks exist
83
84 ** Cronjobs
85
86   A cronjob needs to run mkkudos.sh to update the list of donors.
87   This can be done every few minutes because mkkudos won't do anything
88   if the list of donors has not been updated.
89
90 ** Writing a blog entry
91
92   The misc/blog.gnupg.org directory is used for the blogging system.
93   On the web server it is symlinked to /blog/.  To build and upload all
94   blogs you cd to misc/blog.gnupg.org and run the command ./upload.
95   This renders the org files into html, builds an index, and uploads
96   the html files to the web server.  Emacs and a decent org-mode are
97   required (tested with org-mode 8.2.7).
98
99   To add a new blog entry, decide on the publication date and create
100   a file
101
102     YYYYMMDD-short-headline.org
103
104   for example "20141030-what-happened-this-month.org".  For drafting
105   the blog you may want to store it in drafts/ first.  Unless you
106   translate an existing entry do not use a file name which ends in
107   ".??.org".  The file itself is a standard org file using these
108   conventions:
109
110   ===== 8< =========
111   # Comment
112   #+AUTHOR: Werner
113   #+DATE: 30th October 2014
114
115   ** What happened in October 2014
116
117   Blurb
118   ===== >8 =========
119
120   AUTHOR and DATE are used to construct the "Posted at" info.  The
121   headline needs to start at level 2.