2.1.1 Variables to Control the Build Process

The build process has several modes of operation, and they all relate to the handling of files that are to be added to the repository or performing certain sanity checks at build time. The variables are specified on the command line, after make, in the form VARIABLE=value, e.g. make VCS=yes. In the future, additional features will be implemented in a similar fashion.

‘VCS=no’

‘...’

Do not add any files to the repository. This is the default. You may as well omit to define VCS entirely; there is no special code that expects assigning the value `no'.

‘VCS=yes’

Automatically add any new files in the repository (CVS or Subversion—the repository type is auto-determined at build time). These are any POT files, if they are generated for the first time, and the translated articles (.lang.html) in HTML format. In addition, if there is no server/gnun/generic.lang.html file for the specific language an article is being generated, an empty file will be added. Finally, any missing PO and their HTML counterparts of the server templates will be added, computed on the basis of the template-files variable.

‘VCS=always’

Because GNU Make considers the targets up-to-date after a successful build, if it was performed with no VCS interaction, the important newly created files will not be added (and committed when you do cvs|svn commit) in the repository. Assigning this value enables additional check and forcefully adds all files. Use it sparingly, since it is very slow and generally less reliable.

‘VALIDATE=no’

‘...’

Does not perform validation of the HTML articles and PO files. This is the default, and not defining this variable has the same effect.

‘VALIDATE=yes’

Validates all original articles before generating the POTs, to ensure that the ultimate source is valid XHMTL. Also, validates all generated translations in HTML format and all PO files. It is highly recommended to run the build this way, even if it is a bit tedious to fix the errors that are reported as a result of enforcing validation.

Articles defined in the variable no-validate-articles are never checked for HTML validity. Its purpose is to skip validation of HTML 5 articles, until the command-line validation tools are updated to parse files that comply with this new standard. Use it sparingly, since this may lead to other errors.

‘NOTIFY=no’

‘...’

Do not send email notifications about errors. This is the default.

‘NOTIFY=yes’

If an error occurs, send a mail with a meaningful subject and the error message as body to the concerned party. The variables devel-addr, web-addr and transl-addr control the recipients; normally they should be set to the GNUN maintainers, webmasters and translators accordingly.

‘VERBOSE=yes’

If defined, the value of the variables templates-translated, home-translated, ALL_POTS, articles-translated and gnunews will be printed to the standard output. This is off by default, but recommended in general since it will show a bug in the computation of the basic variables.

‘GRACE=days’

If defined, ordinary articles that have fuzzy strings and are not older than days will not be regenerated. This functionality is implemented specifically to prevent gratuitous replacement of translated strings with the English text when there are only minor formatting changes in the original. The translator has time (the “grace” period as defined in this variable) to review the changes and unfuzzy the strings, while keeping the online translation intact. Note that this variable has no effect on the homepage, the server templates, gnunews and all articles defined in the variable no-grace-articles.

‘TEAM=lang’

The translation team which articles need to be checked for completeness. This variable is applicable only for the report target, and is mandatory for it. See report.

Note that VCS=yes,always is a valid combination: because POT files of the server templates are not handled by always, running the build this way will commit any newly added files as specified in TEMPLATE_LINGUAS and will perform additional check at the end, cvs|svn add-ing all necessary files.

When validation is enabled (i.e. with VALIDATE=yes), the original English articles are validated first, before any commands that generate the other files, and make exits with an error on the first encountered article. This is done on purpose, to prevent the propagation of an eventual error in the markup of the original article to all translations.

By contrast, validation of the translated .lang.html is performed after it is generated and if VCS=yes the article will be committed in the repository. The build will fail again and further processing of the remaining articles will not be performed, but this particular translation will be installed. The translator has time until the next run to fix the error—usually by modifying the corresponding .lang.po file.

If notification is enabled (NOTIFY=yes), and the build system encounters errors (mostly when validating articles), email messages will be sent to the party that is expected to fix the error. The subject of the messages always include the problematic article, for example:

     Subject: [GNUN Error] gnu/gnu.fa.html is not valid XHTML