taler-www

README (5940B)

---

 This repository contains the GNU Taler web site www.taler.net.
 
 The web site consists of basically static HTML. However, the static HTML is
 run through the Jinja2 template processor for internationalization.
 
 Structure:
 
 /template/
   Basically, you edit the English *.html.j2 files in /template/, and then run
   the Python script to generate static HTML. To facilitate translation, all
   English text in the HTML is marked for GNU Gettext using Jinja2 mark-up.
 
 /common/
   This directory contains files shared between the various HTML pages, such
   as our navigation bar.
 
 /locale/
   The translations of the strings into the various languages are in the
   /locale/ directory.
 
 /build-system/
   This directory contains JavaScript from other projects which we redistribute,
   such as bootstrap and jquery.
 
 /static/
   This directory contains static resources that are language-independent
   and never change.
 
 /inc/
   This directory contains various Python scripts that are included during
   the pre-processing with Jinja2.
   
 /rendered/
   This directory contains the build of the web site after you commanded 'make'.
   Open this file with your favourite browser and check the final result with other browsers.
 
 
 How To  -  Instructions for how to generate the HTML page(s):
 
 A. Preparing the environment:
 
 If not already installed, please install according to your needs and your OS:
 
 # apt install python3-babel python3-jinja2 python3-markupsafe
 # apt install python3-ruamel.yaml python3-ruamel.yaml.clib
 # apt install python3-lxml python3-bs4 python3-cssselect python3-soupsieve
 # apt install gettext gettext-base
 
 -> On some distros, you may need to use `pip install ruamel.yaml`
 
 and if not yet done:
 # apt install git
 
 For read-only access pass 
 # git clone https://git.taler.net/taler-www.git
 
 If you think you are trustworthy enough to deserve edit rights as a contributor 
 with Git access, you can apply for such by signing and mailing the 
 Copyright Assignment Agreement (https://taler.net/pdf/copyright.pdf) 
 to ensure that the GNUnet e.V. --- Taler Systems SA agreement on licensing and 
 the collaborative development of the GNUnet and GNU Taler projects 
 (https://git.gnunet.org/gnunet-ev.git/tree/gnunet_taler_agreement.tex) is satisfied.
 
 The agreements ensure that the code will continue to be made available under free 
 software licenses, which gives developers the freedom to move code between GNUnet 
 and GNU Taler without worrying about licenses and the company the ability to 
 dual-license (for example, so that we can distribute via app-stores that are hostile 
 to free software).
 
 Minor contributions do not require copyright assignment (basically, anyone without Git access). 
 Pseudonymous contributions are accepted, in this case simply sign the agreement 
 with your pseudonym. Scanned copies are sufficient, but snail mail is preferred.
 
 ====================
 Debian prerequisites
 ====================
 
 Simply install:
 
 # apt install python3-ruamel.yaml python3-jinja2 python3-babel git python3-lxml python3-bs4
 
 ====================
 NetBSD prerequisites
 ====================
 Install python3.7, py37-babel, npm, nodejs from pkgsrc.
 
 Adjust the values in config.mk:    PYTHON=python3.7    BABEL=pybabel-3.7
 
 ====================
 Nix Developer Shell
 ====================
 
 If you have nix installed, simply start a developer shell via:
 ```
 # nix-shell contrib/nix
 ```
 
 ====================
 Python virtual env
 ====================
 * Install python3 i.e on Debian
 ```
 # apt install python3
 ```
 * Create virtual environment **.venv directory is excluded with git ignore paterns**
 ```
 python3 -m venv .venv
 ```
 * Activate the virtual environment
 ```
 source .venv/bin/activate
 ```
 * Install all requirements from [requirements.txt](requirements.txt) using pip
 ```
 pip install -r requirements.txt
 
 
 B. When reusing the existing web site from Git, get its files and folder structure:
 # git clone git+ssh://git@git.taler.net/taler-www.git
 
 Change into the new folder and run:
 ./bootstrap
 ./configure
 make
 
 The website will be installed in the /rendered/ directory.
 
 If ./configure without parameters does not work, try ./configure --variant=/rendered/
 
 Open the web site that results in /rendered/ or run
 $ firefox rendered/en/index.html
 
 
 C. Preparing for deployment:
 When using a web site template from a dislocated web server, you will have to check whether all files are at your hand.
 wget might eventually not retrieve all the files necessary for building the local site.
 
 1. wget -r https://server.foo/taler/index.html
 2. Download the website with all files to your home folder
 3. Check media resources of the web site by right-clicking and selecting from the browser sub menu 'Show page info'
 4. Compare and get the missing files of the online web site which will serve as your main source
 5. Add image resources to /images/
 6. Add fonts to /static/fonts/
 7. Add or modify CSS files in /static/css/
 8. Add JS files in /static/js/
 9. Add or modify *.html.j2 files in /template/
 10. Commit all files to Git
 
 Then run in the new web site's home folder (e.g. ~/taler-www/):
 ./bootstrap
 ./configure
 make
 
 If the page finally builds well, proceed with the following steps:
 
 1. Insert internationalization mark-up tags around any text string for translation:
 {% trans %} foo text {% endtrans %}
 2. Modify shared HTML logic in /common/
 3. Adjust navigation.j2.inc, header.j2.inc and footer.j2.inc in /common/
 4. Add more *html.j2 files to expand the web site structure and paste their URLs into navigation.j2.inc
 5. Modify HTML code in the other *.html.j2 files according to your needs and wishes
 6. Test out and deactivate unnecessary Javascript
 7. Check for typos and mistakes in the text strings
 8. Check the translation strings in /locale/*/LC_MESSAGES/messages.po
 9. Clean up unnecessary files and folders
 10. Push all files to Git
 11. Review the results before deploying the new web site, then publish it on the internet