Website Maintenance
From GnuCash
Sometimes something should be improved on our website. This page is intended to collect the right procedure.
Contents
Introduction
www.gnucash.org is the webserver of the GnuCash project. The sources are public available at GitHub. Building is done by a simple GNU Make.
- Branches
- Master: https://www.gnucash.org, the official site,
- Beta: https://www.gnucash.org/beta/ is intended for developing major changes.
Content State
{sizing|develdocs}.phtml are currently (2017) hopeless outdated.
Used Standards
- The static structure is usually written in HTML.
- Html version & encoding
- The main page is based on HTML5 with charset=UTF-8.
- Todo
-
- A few elements like #Metatags contain attributes based on RDFa etc. Some declaration required?
- The dynamic parts are injectet via PHP. You can assume PHP7 is supported.
- Direct formating is disliked. Instead we use the Cascading Style Sheets (CSS) from externals/gnucash.css.
Adding or Changing Text
If you add or change text, keep in mind Gnucash and its website are multilingual. If you - like me and most other people - are not firm in all languages, you should ask the translators, to help you keeping the translations up to date.
"Coding" Style
The current code is suboptimal. In the future follow standards:
- HTML
- (https://selfhtml.org/ is a good starting point in German)
- PHP
- The PHP Framework Interop Group published them. PSR-0 got obsoleted by PSR-4, so start with PSR-1: Basic Coding Standard.
- Multiple occurrences of the same text: Assign it once to a variable and use that.
Metatags
Currently 2 sets of metatags are important/partly implemented:
- By Google recognized <meta> tags
- The Open Graph protocol is primary used by Facebook and requires at least the W3C standard Resource Description Framework in Attributes (RDFa).
- Rules
- If applicable,
- put content in a (PHP) $variable or $CONSTANT and use that in both flavours,
- mark it as _("Translatable").
- Restrictions
-
- Title
- 60 char,
- Description
- 105 char, first words are today taken as keywords by Google,
- Image
- [TBD: currently slightly too big or because some of
- type, width, length, alt
- are missing]
- Keyword
- Negative impact today as they often were misused.
I18N
- Translatable text is quoted:
<?php echo T_("A translatable string");?>
- Separate data (Numbers, URL, ...) from text:
- Bad
-
<?php echo T_("<span class=\"gnucash\">GnuCash</span> handles internationalized dates and currencies. The application's menus and popups have been translated to 21 languages, including Chinese, Danish, French, German, Hungarian, Italian, Japanese, Norwegian, Polish, Portuguese, Russian, Spanish, Swedish, Turkish, Ukrainian, and British English. Documentation is available in English, French, Portuguese and Spanish.");?></p>
- Better
-
<?php printf (T_("<span class=\"gnucash\">GnuCash</span> handles internationalized dates and currencies. The application's menus and popups have been translated to %u languages, including Chinese, Danish, French, German, Hungarian, Italian, Japanese, Norwegian, Polish, Portuguese, Russian, Spanish, Swedish, Turkish, Ukrainian, and British English. Documentation is available in English, French, Portuguese and Spanish."), 21);?></p>
- Now an additional translation of the program will not break all website translations.
- Try to avoid putting URLs in translatable strings, but
- links to the wiki should be separate marked translatatable - there might be a translated page in the wiki.
- addresses of images, which contain text should be translatable to link them to localized versions.
- Todo: Try also to avoid Markups in the translatable text.
- Fix me
- Which methods should we use for the images? This needs documentation in Translation, too.
Managing Translations
After changing the english text, you should prepare the translation by
- creating a new .pot file
make pot
- msgmerge all existing .po files
make msgmerge
- and commit the updates
- send a short mail to gnucash-devel about "Translators: Website changed ..."
- feel free to give them some clues, what changed like
- "complete new download page" or
- "fixed 42 typos in the english text".
- As patches with reworked .po files arrive,
- If a language is new, add it in
- makefile
- to languages
- If a language is new or bitrotten, add or enable in
- externals/header.phtml
- a line in
<span id="language">
- Note
- A few languages are disabled here, because they are bitrotten.
- apply them and
- make the .mo files, e.g. with
make mos
- commit
- [[makefile, ]
- externals/header.phtml, ]
- po/LL.po and
- locale/LL/LC_MESSAGES/gnucash-htdocs.mo
- where LL is the language code.
- If a language is new, add it in
Further details can be found on the Translation page.
Images
Traditional icons had a size of 32x32, for today see #Favicon. For other images we have a few tips in Documentation_Update_Instructions#Screenshots_and_Images.
Testing
make check
After modifying PHP parts, runmake check
php -l <file>
W3C Validation
There are at least 2 ways to validate pages against W3C standards:
- Final Test
- After pushing and transfer of your changes to the website check the results with https://validator.w3.org/nu/?doc=https%3A%2F%2Fwww.gnucash.org%2Fbeta%2Fnews.phtml (vary the last part if you maintained a different page). Fix any errors it reports and re-commit.
- Local Test
- If PHP and Tidy are installed on your system, you can check your work with HTML Tidy before pushing by e.g.: to test the english version. In theory you should run it for all installed languages as it is possible, that a page is broken only in one language, if the translator made a mistake with the markups in the msgstrings like using uppercase tags in XHTML — or some HTML injection.
clear; LANGUAGE=C php index.phtml | tidy -config tidy.conf # or to locate errors easier: clear; LANGUAGE=C php index.phtml >tmp.html && tidy -config tidy.conf tmp.html # the location is then valid for tmp.html
- Tip for news
- Because our *news pages are very long, it is suggested to test your new *.news file separatly before the full news page: This 3 warnings are normal because this elements are part of news.phtml. But fix everything else!
$ tidy -config tidy.conf news/200726-4.1.news line 1 column 1 - Warning: missing <!DOCTYPE> declaration line 1 column 1 - Warning: inserting implicit <body> line 1 column 1 - Warning: inserting missing 'title' element Info: Document content looks like HTML5 Tidy found 3 warnings and 0 errors!
- Create an adjusted tidy.conf
- Execute and then adjust it:
tidy -export-config > tidy.conf
- Enabling indentation and wrapping improves the readability. show-filename is only useful, if you do no preprocessing by PHP.
- With Cleanup options you can generate an improved output to be merged back in your files:
- clean: replaces legacy presentational tags: <i>, <b>, <center> when enclosed within appropriate inline tags, and <font>.
- logical-emphasis: replaces <i> with <em> and <b> with <strong>.
- replace-color: replaces numeric values in color attributes with HTML/XHTML color names where defined, e.g. "#ffffff" with "white".
Mobile Friendliness
Today there are more mobiles than desktop devices.
Metatags
If you changed Metatags and related elements like images, enter the URL at https://metatags.io/ to see how the page would appear in several social media.
Favicon
Because there are in between many flavours of favicons (resolutions, devices, OSes, browsers) you can use a service like
to check and update them.
- Size
- As of 2020-10-05 they recommend 260x260 or more for optimal results and require at least 70x70.
- Type
- As they accept many formats, we recommend PNG.
On Your Localhost
- Todo
-
- Idea
- Set up a web server, usually apache.
- Tip
- Eclipses PHP module can also run a test instance.
- Add your repository to your apache configuration /etc/apache2/conf.d/
- View http://localhost/gnucash/
Future developement
There are considerations to modernize the website:
- Full CMS like wordpress or drupal, but monsters to be configured (by Linas) or
- static site generator like https://gohugo.io or https://jekyllrb.com/
