cwehli / gnucash-htdocs

GnuCash website.

# -- rst --

TODO

• re-work page content for new-style translations (one big block)
  • re-flow existing po-file content.
• update features screenshots
• fix double-slash on langdir='' mlist search menu URLs

Requirements

• gettext
• PHP (7 recommended)

Notes about multi-lingual gnucash website content

• all pages must call lang.php to bring in gettext support.
• It would be nice to use the same containing structure for all translations.
• Phrase content can probably be po-style translated well.
• Body/paragraph content probably wants to be block-replaced.
• We're fine not doing auto-language negotiation.

www.gnucash.org coding conventions/notes

There are three main classes of links:

• external resources [$top_dir[/externals]]
  • www: relative
  • !www: relative
• translations [$top_dir/[<lang>]]
  • www: relative
  • !www: relative
• navigation [$home]
  • www: relative
  • !www: url-prefixed ("https://www.gnucash.org/file.phtml")

Type of Link	www.gnucash.org	lists.gnucash.org	Relative to
external (C)	./[externals/]	./[externals/]	$top_dir
external (lang)	../[externals/]	../[externals/]	$top_dir
translation (C)	./[lang]	./[lang]	$top_dir
translation (lang)	../[lang]	../[lang]	$top_dir
navigation (C)	./	https://www.[...]/	$home
navigation (lang)	./	https://www.[...]/[lang]/	$home

As such:

$top_dir := the relative reference to the top of the relative website; this

should be used for language-independent resources (stylesheets, images, php includes), but not for links...

$home := a prefix for navigational URLs; for everything but

lists.gnucash.org, this'll be ".", but for lists.gnucash.org it'll be "https://www.gnucash.org/".

As well, the following variables should be set:

• per directory:

  $locale := the LANG to use for gettext.

• per file:

  $title := the text of the page.

  $homepage := if the file is the homepage; controls RSS feed linkage.

Note about folders

• "externals" folder contains images linked to external sources (e.g. logo_w120.png is used on the wiki and packtpub_gnucash_2.4cov.png is linked to the external book website)
• "docs" is supposed to hold copies of the compiled documentation (html, pdf, epub,...) This used to be a version managed directory inside this repository. It has been moved into a separate repository in 2014. The php website code still assumes this directory to exist though. So in order to satisfy this code a softlink should be set up on the webserver: docs->"real location of compiled docs"

Get a local copy of our repository

Note: This step is required for all following sections.

Create a local git repository in the directory gnucash-htdocs:

$ git clone https://github.com/Gnucash/gnucash-htdocs

and enter it:

$ cd gnucash-htdocs

Now you can edit files, run make commands, git commands ... But before you change anything else than translations read:

https://wiki.gnucash.org/wiki/Website_Maintenance

For more details about git see:

https://wiki.gnucash.org/wiki/Git.

Preparing translations

First, make sure the pot file is up to date. You can do that by running the command:

$ make pot

Now merge the new content into your translation, substituting the name of your po file in the command:

$ msgmerge po/en_GB.po po/gnucash-htdocs.pot -o po/en_GB.po

Finally, see the size of the task ahead:

$ msgfmt -c --statistics po/en_GB.po

Whilst editing the translation, run the msgfmt command from time to time to catch errors and let you know how much is left to do.

When you come across fuzzy markers: (#, fuzzy), check whether the proposed translation is a valid translation. If it is, then remove the fuzzy marker. If it is not, either edit the translation and remove the fuzzy marker, or leave the fuzzy marker where it is -- this message will then be treated as untranslated.

When you have no fuzzy and no untranslated messages, update the binary translation file for your locale:

$ make de [fr nl ...]

Which will build an individual translation, or:

$ make mos

Which will make all the translations known to Makefile. So, if your language is new, add it there to languages = ...

See also: https://wiki.gnucash.org/wiki/Translation#How_to_translate_the_website. It is usually more recent.

Publishing the website

Changes that are committed to 'master' are published automatically. No other steps are required.

Website beta environment

Some changes may be too drastic or experimental to push to the public website. There is a beta website available as well on

https://www.gnucash.org/beta/

WARNING: This branch is currently not kept in sync with master.

So if you intend to experiment with the current content in master, please ask one of the devs to merge the current master to beta first!

To work in this beta environment, checkout the beta branch in your local repo:

$ git checkout beta

Have fun!