Difference between revisions of "Website Maintenance"

Latest revision as of 13:17, 8 April 2024

Sometimes something should be improved on our website. This page is intended to collect the right procedure and belongs to the Project Administration.

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.

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

Tutorials: https://www.w3schools.com/ has tutorials for HTML, CSS, and PHP.

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.; A nice tool for modern PHP is PHP-CS-Fixer.

Multiple occurrences of the same text: Assign it once to a variable and use that.

Comments

While

<!-- HTML comments -->

are sent to the readers (show source view),

<?PHP // PHP comment line
?>

<?PHP //*
 and PHP comment block
*/ ?>

are not visible to them.

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)
- [global] $variable or
- [define (] CONSTANT […)] and use that in both flavours,
mark it as T_("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");
?>

or as single expression in HTML parts

 <?=T_("A translatable string")?>

To get a list of files run

grep -rl 'T_(' --include="*.ph*" .

or exact positions

grep -inr 'T_(' --include="*.ph*" .

Only while debugging gettext include also --include="*.inc".

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

Moved to Language Administration#Website.

Images

Traditional web 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.

App icons today have a default size of 48x48.

Dependencies

Some images are referenced from elsewhere:

gnucash: gnucash.appdata.xml: <screenshots> section
Wiki_Tips: gnucash-perspective.png; banner5.png

Testing

Spell Check

Ideally you should spell check your textual changes by priority:

Language: Source files should be in en_US, not en_GB or something else;
Grammar, including punctuation;
Typography (Documentation_Update_Instructions#Text_conventions).

Todo: Add references and/or tools.

make check

After modifying PHP parts, run

make check

before committing. This currently calls

php -l <file>

— PHP's integrated lint — for all php or phtml files.

W3C Validation

There are at least 2 ways to validate pages against W3C standards:

Local Test

If PHP and Tidy are installed on your system, you can check your work with HTML Tidy before pushing by e.g.:

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
## Exception: atom.php produces xml (Fixme: There is no authoritative DTD nor XSD for RFC 4287 so xmllint won't work.):
clear; LANGUAGE=C php atom.php >tmp.xml && xmllint --valid tmp.xml {-o out.xml|--noout}

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.

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:

$ 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!

This 3 warnings are normal because this elements are part of news.phtml. But fix everything else!

Current tidy.conf

Since 2021-09-27 we ship our adjusted tidy.conf.

Before you had to execute tidy -export-config > tidy.conf and then adjust it:

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 manually merged back into your files:

clean: replaces legacy presentational tags: , , <center> when enclosed within appropriate inline tags, and .

logical-emphasis: replaces with and with .

replace-color: replaces numeric values in color attributes with CSS/HTML/XHTML color keywords where defined, e.g. "#ffffff" with "white".

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).; The Atom feed can be tested with W3C Feed Validation Service.; Fix any errors they report and re-commit.

Mobile Friendliness

Today there are more mobiles than desktop devices.

Google test mobile-friendly

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

Favicon Generator. For real.

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 https://localhost/gnucash/

Future developement

Gettext variants

We are currently using

Last available version: https://launchpad.net/php-gettext/trunk/1.0.11 released: 2010-12-24

continued by Seyyed Morteza Moosavi as https://github.com/smmoosavi/php-gettext v1.0.1 28 Oct 2015

And there are:

https://github.com/php-gettext/Gettext, active, Minimum PHP version supported is 7.2
https://www.php.net/manual/en/function.gettext since PHP4

User:Fell is not sure, how they relate and to which we should upgrade.

CMS or site generator

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/

Sources: https://lists.gnucash.org/logs/2020/09/27.html#T15:36:13; https://lists.gnucash.org/logs/2020/09/29.html#T10:38:28

@@ Line 1: / Line 1: @@
-Sometimes something should be improved on our website. This page is intended to collect the right procedure.
+Sometimes something should be improved on our website. This page is intended to collect the right procedure and belongs to the [[Project Administration]].
 == Introduction ==
-'''www.gnucash.org''' is the webserver of the GnuCash project. The sources are public available at [https://github.com/Gnucash/gnucash-htdocs GitHub]. Building is done by a simple GNU Make.
+'''{{WebServer}}''' is the webserver of the GnuCash project. The sources are public available at [https://github.com/Gnucash/gnucash-htdocs GitHub]. Building is done by a simple GNU Make.
 ;Branches:
-:Master: https://www.gnucash.org, the official site,
+:Master: {{URL:www}}, the official site,
-:Beta: https://www.gnucash.org/beta/ is intended for developing major changes.
+:Beta: {{URL:www}}beta/ is intended for developing major changes.
-=== Content State ===
-<tt>{sizing|develdocs}.phtml</tt> are ''currently'' (2017) hopeless outdated.
 == Used Standards ==
 * The static structure is usually written in [[Glossary#H|HTML]].
-:;Html version & encoding: The main page is based on ''XHTML+RDFa'' with ''charset=UTF-8''.
+:;Html version & encoding: The main page is based on ''HTML5'' with ''charset=UTF-8''.
 ::;Todo:
-:::* older parts are still HTML 4.01 and have charset=iso-8859-1.
+:::* A few elements like [[#Metatags]] contain attributes based on ''RDFa'' etc. Some declaration required?
-:::* A few, currently disabled, Social Media snippets would expect HTML 5.
 * The ''dynamic parts'' are injectet via [[Glossary#P|PHP]]. You can assume ''PHP7'' is supported.
 * Direct formating is disliked. Instead we use the [https://en.wikipedia.org/wiki/Cascading_Style_Sheets Cascading Style Sheets] (CSS) from [https://github.com/Gnucash/gnucash-htdocs/blob/master/externals/gnucash.css externals/gnucash.css].
@@ Line 24: / Line 20: @@
 === "Coding" Style ===
+;Tutorials: https://www.w3schools.com/ has tutorials for HTML, CSS, and PHP.
 The current code is suboptimal. In the future follow standards:
 ;HTML: (https://selfhtml.org/ is a good starting point in German)
 ;PHP: The [https://www.php-fig.org/ PHP Framework Interop Group] published them. PSR-0 got obsoleted by PSR-4, so start with [https://www.php-fig.org/psr/psr-1/ PSR-1: Basic Coding Standard].
+:A nice tool for modern PHP is [https://github.com/FriendsOfPHP/PHP-CS-Fixer PHP-CS-Fixer].
 * Multiple occurrences of the same text: Assign it once to a variable and use that.
+;Comments: While <syntaxhighlight lang="html">
+<!-- HTML comments -->
+</syntaxhighlight> are sent to the readers (<tt>show source view</tt>), <syntaxhighlight lang="php">
+<?PHP // PHP comment line
+?>
+<?PHP //*
+ and PHP comment block
+*/ ?>
+</syntaxhighlight> are not visible to them.
 ===Metatags===
@@ Line 35: / Line 43: @@
 ;Rules: If applicable,
-# put content in a (PHP) $variable or $CONSTANT and use that in both flavours,
+# put content in a (PHP)
-# mark it as _("Translatable").
+#* <tt>[global] '''$variable'''</tt> or
+#* <tt>[define (] '''CONSTANT''' […)]</tt> and use that in both flavours,
+# mark it as T_("Translatable").
 ;Restrictions:
@@ Line 47: / Line 57: @@
 ===I18N===
 * Translatable text is quoted:
-<SyntaxHighlight lang="php"> <?php echo T_("A translatable string");?> </SyntaxHighlight>
+:<SyntaxHighlight lang="php">
-:* Separate data (Numbers, URL, ...) from text:
+<?php
+  echo T_("A translatable string");
+?></SyntaxHighlight> or as single expression in HTML parts
+<SyntaxHighlight lang="php"> <?=T_("A translatable string")?> </SyntaxHighlight>
+::To get a list of files run <SyntaxHighlight lang="sh">
+grep -rl 'T_(' --include="*.ph*" .</SyntaxHighlight> or exact positions <SyntaxHighlight lang="sh">
+grep -inr 'T_(' --include="*.ph*" .</SyntaxHighlight> Only while debugging gettext include also <SyntaxHighlight lang="sh" inline>--include="*.inc"</SyntaxHighlight>.
+* Separate data (Numbers, URL, ...) from text:
 :;Bad: <SyntaxHighlight lang="php"> <?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> </SyntaxHighlight>
 :;Better: <SyntaxHighlight lang="php"> <?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> </SyntaxHighlight>
 ::Now an additional translation of the program will not break all website translations.
-:*Try to avoid putting URLs in translatable strings, but
+*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.
+:* 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.
+:* 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.
+*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.
+;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
+Moved to [[Language Administration#Website]].
-# creating a new .pot file <pre>make pot</pre>
-# msgmerge all existing .po files <pre>make msgmerge</pre>
-#: 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 <tt>languages</tt>
-## If a language is new or ''bitrotten'', add or enable in
-##;externals/header.phtml: a line in <syntaxhighlight lang="html"><span id="language"></syntaxhighlight>
-##;Note: A few languages are disabled here, because they are '''bitrotten'''.
-## apply them and
-## make the .mo files, e.g. with <pre>make mos</pre>
-## commit
-##:[[<tt>makefile</tt>, ]
-##:<tt>externals/header.phtml</tt>, ]
-##:<tt>po/''LL''.po</tt> and
-##:<tt>locale/''LL''/LC_MESSAGES/gnucash-htdocs.mo</tt>
-##:where ''LL'' is the language code.
-Further details can be found on the [[Translation#How_to_translate_the_website|Translation]] page.
 == Images ==
-Icons should have a size of 32x32. We have a few tips in [[Documentation_Update_Instructions#Screenshots_and_Images]].
+Traditional ''web'' 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]].
+:''App'' icons today have a default size of 48x48.
+;Dependencies: Some images are referenced from elsewhere:
+:; [{{URL:git}}gnucash/blob/maint/gnucash/gnome/gnucash.appdata.xml.in.in#L41 gnucash: gnucash.appdata.xml]: <tt><screenshots></tt> section
+:;[[Wiki_Tips]]: [{{URL:www}}images/gnucash-perspective.png gnucash-perspective.png]
+:: [{{URL:www}}images/banner5.png banner5.png]
 == Testing ==
+===Spell Check===
+Ideally you should spell check your textual changes by priority:
+# '''Language''': Source files should be in ''en_US'', not en_GB or something else;
+# '''Grammar''', including punctuation;
+# '''Typography''' ([[Documentation_Update_Instructions#Text_conventions]]).
+;Todo: Add references and/or tools.
 ===make check===
 After modifying '''PHP''' parts, run <syntaxhighlight lang="sh">
@@ Line 95: / Line 102: @@
 </syntaxhighlight> — PHP's integrated lint — for all php or phtml files.
-===W3C===
+===W3C Validation===
-#After pushing your commit press the <code>W3C-Check</code> button in the lower left corner of the website and fix any claimed errors.
+There are at least 2 ways to validate pages against W3C standards:
-#:Do it for ''every page'', which might by affected by your change. E.g. Changing a modules in /external might affect all pages.
+;Local Test: If '''PHP''' and '''Tidy''' are installed on your system, you can check your work with [https://en.wikipedia.org/wiki/HTML_Tidy HTML Tidy] ''before pushing'' by e.g.: <syntaxhighlight lang="sh">
-#Do the same with <code>CSS-Validator</code>.
-;Note: <tt>W3C-check</tt> is the online version of the ''formatter'' and ''linter'' [https://en.wikipedia.org/wiki/HTML_Tidy tidy]. So in theory you can run the checks also locally before pushing by e.g.: <syntaxhighlight lang="sh">
 clear; LANGUAGE=C php index.phtml | tidy -config tidy.conf
-</syntaxhighlight> to test the english version. 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, which are not allowed in XHTML.
+# or to locate errors easier:
-To create an adjusted <tt>tidy.conf</tt> you can use <syntaxhighlight lang="sh">
+clear; LANGUAGE=C php index.phtml >tmp.html && tidy -config tidy.conf tmp.html
-tidy -export-config >tidy.conf
+# the location is then valid for tmp.html
-</syntaxhighlight> and then adjust it. Enabling indentation and wrapping improves the readability.
+## Exception: atom.php produces xml (Fixme: There is no authoritative DTD nor XSD for RFC 4287 so xmllint won't work.):
+clear; LANGUAGE=C php atom.php >tmp.xml && xmllint --valid tmp.xml {-o out.xml|--noout}
+</syntaxhighlight> 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.
+:;Tip for news: Because our <tt>*news</tt> pages are very long, it is suggested to test your new <tt>*.news</tt> file separatly before the full news page: <syntaxhighlight lang="console">
+$ 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!
+</syntaxhighlight> This 3 warnings are normal because this elements are part of <tt>news.phtml</tt>. But fix everything else!
+:;Current <tt>tidy.conf</tt>: Since 2021-09-27 we ship our adjusted <tt>tidy.conf</tt>.
+::Before you had to execute <syntaxhighlight lang="sh" inline>
+tidy -export-config > tidy.conf
+</syntaxhighlight> and then adjust it:
+:* 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 ''manually'' merged back into your files:
+::''clean'': <nowiki>replaces legacy presentational tags: <i>, <b>, <center> when enclosed within appropriate inline tags, and <font>.</nowiki>
+::''logical-emphasis'': <nowiki>replaces <i> with <em> and <b> with <strong>.</nowiki>
+::''replace-color'': replaces numeric values in color attributes with [{{URL:W3C}}wiki/CSS/Properties/color/keywords CSS/HTML/XHTML color keywords] where defined, e.g. "#ffffff" with "white".
+;Final Test: After pushing and transfer of your changes to the website check the results with {{URL:W3C|validator}}nu/?doc=https%3A%2F%2F{{WebServer}}%2Fbeta%2Fnews.phtml (vary the last part if you maintained a different page).
+:The [{{URL:git}}gnucash-htdocs/blob/master/atom.php Atom feed] can be tested with [{{URL:W3C|validator}}feed/ W3C Feed Validation Service].
+:Fix any errors they report and re-commit.
 ===Mobile Friendliness===
@@ Line 114: / Line 141: @@
 ===Favicon===
-Because there are in between many flavours of favicons (resolutions, devices, OSes, browsers)you can use a service like
+Because there are in between many flavours of favicons (resolutions, devices, OSes, browsers) you can use a service like
 :[https://realfavicongenerator.net/ Favicon Generator. For real.]
 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===
@@ Line 123: / Line 152: @@
 ::;Tip: [[Eclipse]]s PHP module can also run a test instance.
 ::Add your repository to your apache configuration <tt>/etc/apache2/conf.d/</tt>
-::View http://localhost/gnucash/
+::View https://localhost/gnucash/
+==Future developement==
+===Gettext variants===
+We are currently using
+* PHP-gettext, Copyright (c) 2009 Danilo Segan <danilo@kvota.net>
+: Last available version: https://launchpad.net/php-gettext/trunk/1.0.11 released: 2010-12-24
+* continued by Seyyed Morteza Moosavi as {{URL:GH}}smmoosavi/php-gettext v1.0.1 28 Oct 2015
+And there are:
+* {{URL:GH}}php-gettext/Gettext, active, Minimum PHP version supported is 7.2
+* https://www.php.net/manual/en/function.gettext since PHP4
+[[User:Fell]] is not sure, how they relate and to which we should upgrade.
+===CMS or site generator===
+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/
+:;Sources: {{URL:Lists}}logs/2020/09/27.html#T15:36:13
+::{{URL:Lists}}logs/2020/09/29.html#T10:38:28
 [[Category:Documentation]]
 [[Category:Maintenance]]
 [[Category:Translation]]

Difference between revisions of "Website Maintenance"

Latest revision as of 13:17, 8 April 2024

Contents

Introduction

Used Standards

Adding or Changing Text

"Coding" Style

Metatags

I18N

Managing Translations

Images

Testing

Spell Check

make check

W3C Validation

Mobile Friendliness

Metatags

Favicon

On Your Localhost

Future developement

Gettext variants

CMS or site generator

Navigation menu

Personal tools

Namespaces

Variants

Views

More

Search

Navigation

Related Sites

Contributing

Tools