Difference between revisions of "Website Maintenance"

From GnuCash
Jump to: navigation, search
(Metatags: Restrictions)
(Images: new; fix "On Your Localhost" level)
(7 intermediate revisions by the same user not shown)
Line 2: Line 2:
  
 
== Introduction ==
 
== 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.
 
'''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.
 
;Branches:
 
;Branches:
 
:Master: https://www.gnucash.org, the official site,
 
:Master: https://www.gnucash.org, the official site,
 
:Beta: https://www.gnucash.org/beta/ is intended for developing major changes.
 
:Beta: https://www.gnucash.org/beta/ is intended for developing major changes.
=== State ===
+
 
 +
=== Content State ===
 
<tt>{sizing|develdocs}.phtml</tt> are ''currently'' (2017) hopeless outdated.
 
<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''.
 +
::;Todo:
 +
:::* older parts are still HTML 4.01 and have charset=iso-8859-1.
 +
:::* 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].
  
 
== Adding or Changing Text ==
 
== Adding or Changing Text ==
 
 
If you add or change text, keep in mind Gnucash and its website are multilingual.
 
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.
 
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 ===
 
=== "Coding" Style ===
* The static structure is usually written in [[Glossary#H|HTML]].
+
The current code is suboptimal. In the future follow standards:
* The ''dynamic parts'' are injectet via [[Glossary#P|PHP]].
+
;HTML: (https://selfhtml.org/ is a good starting point in German)
* 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].
+
;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].
 
* Multiple occurrences of the same text: Assign it once to a variable and use that.
 
* 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 [https://support.google.com/webmasters/answer/79812?hl=en Google recognized <meta>] tags
 +
# The [https://ogp.me/ Open Graph protocol] is primary used by Facebook and requires at least the W3C standard [http://en.wikipedia.org/wiki/RDFa  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:
 
* Translatable text is quoted:
 
<SyntaxHighlight lang="php"> <?php echo T_("A translatable string");?> </SyntaxHighlight>
 
<SyntaxHighlight lang="php"> <?php echo T_("A translatable string");?> </SyntaxHighlight>
Line 58: Line 84:
 
Further details can be found on the [[Translation#How_to_translate_the_website|Translation]] page.
 
Further details can be found on the [[Translation#How_to_translate_the_website|Translation]] page.
  
Thanks for your time and work!
+
== Images ==
 +
Icons should have a size of 32x32. We have a few tips in [[Documentation_Update_Instructions#Screenshots_and_Images]].
  
 
== Testing ==
 
== Testing ==
 +
 
===W3C===
 
===W3C===
 
After pushing your commit press the <code>W3C-Check</code> button in the lower left corner of the website and fix any claimed errors.
 
After pushing your commit press the <code>W3C-Check</code> button in the lower left corner of the website and fix any claimed errors.
 
:Do it for ''every page'', which might by affected by your change. E.g. Changing a modules in /external might affect all pages.
 
:Do it for ''every page'', which might by affected by your change. E.g. Changing a modules in /external might affect all pages.
===Metatags===
 
  
If you changed Metattags and related elements like images, enter the URL at https://metatags.io/ to see how the page would appear in several social media.
+
===Mobile Friendliness===
 +
Today there are more mobiles than desktop devices.
 +
* [https://search.google.com/test/mobile-friendly Google test mobile-friendly]
  
Currently 2 sets of metatags are important/partly implemented:
+
===Metatags===
# [https://support.google.com/webmasters/answer/79812?hl=en Google <meta>] tags
+
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.
# The [https://ogp.me/ Open Graph protocol] is primary used by Facebook.
 
 
 
;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''',
 
:;Image: [TBD: currently slightly too big]
 
:;Keyword: Negative impact today.
 
  
 
===On Your Localhost===
 
===On Your Localhost===
Line 87: Line 105:
 
::Add your repository to your apache configuration <tt>/etc/apache2/conf.d/</tt>
 
::Add your repository to your apache configuration <tt>/etc/apache2/conf.d/</tt>
 
::View http://localhost/gnucash/
 
::View http://localhost/gnucash/
 
== Used Standards ==
 
;Html version & encoding: The main page is based on XHTML+RDFa with charset=UTF-8.
 
:;Todo:
 
::* older parts are still HTML 4.01 and have charset=iso-8859-1.
 
::* A few Social media snippets would expect HTML 5.
 
;Metadata: ''Html'' for Google et al.
 
:Facebooks [http://ogp.me Opengraph Protocol]: <code>og:...</code>
 
  
 
[[Category:Documentation]]
 
[[Category:Documentation]]
 
[[Category:Maintenance]]
 
[[Category:Maintenance]]
 
[[Category:Translation]]
 
[[Category:Translation]]

Revision as of 04:53, 10 September 2019

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

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 XHTML+RDFa with charset=UTF-8.
Todo
  • older parts are still HTML 4.01 and have charset=iso-8859-1.
  • A few, currently disabled, Social Media snippets would expect HTML 5.

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:

  1. By Google recognized <meta> tags
  2. 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,
  1. put content in a (PHP) $variable or $CONSTANT and use that in both flavours,
  2. 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

  1. creating a new .pot file
    make pot
  2. msgmerge all existing .po files
    make msgmerge
    and commit the updates
  3. 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".
  4. As patches with reworked .po files arrive,
    1. If a language is new, add it in
      makefile
      to languages
    2. 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.
    3. apply them and
    4. make the .mo files, e.g. with
      make mos
    5. commit
      [[makefile, ]
      externals/header.phtml, ]
      po/LL.po and
      locale/LL/LC_MESSAGES/gnucash-htdocs.mo
      where LL is the language code.

Further details can be found on the Translation page.

Images

Icons should have a size of 32x32. We have a few tips in Documentation_Update_Instructions#Screenshots_and_Images.

Testing

W3C

After pushing your commit press the W3C-Check button in the lower left corner of the website and fix any claimed errors.

Do it for every page, which might by affected by your change. E.g. Changing a modules in /external might affect all pages.

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.

On Your Localhost

Todo
Idea
Set up apache (or another webserver?)
Add your repository to your apache configuration /etc/apache2/conf.d/
View http://localhost/gnucash/