configuration files

the basics

To check a static web site using a configuration file: ssc -f config.file

A configuration file is in INI file format, which is basically a sequence of entries looking like:

The section names and entries are the same as the long switch names. The part before the dot is the section name, and after the dot is the setting name.

Boolean settings require the ‘=’ with no value after the setting name.

examples

A simple configuration:

The website for example.edu can be found in ~/www/htdocs. Standard index files are called index.html, and html files always have the html extension.

The configuration outputs errors, warnings and info messages to ssc.out. It analyses class identifiers, so will scan CSS files for class names.

Links and virtual directories

Here’s an example of a site using virtual directories, accompanied by some link checking, including external links and crosslinked ids.

The configuration file specifies a virtual directory. When a link refers to the local directory /net, ssc will seek the corresponding file(s) in tests/virtual (relative to the current directory, not the root).

Microformats

Microformats contain machine–readable site information held in class attributes, the kind of thing that cheers up search engines. For more gen, browse their site, microformats.org.

The only new thing here is to turn on microformats analysis (class analysis is required).

HTML & SVG

A configuration file to check a site against HTML 5.2 and SVG 1.1 might contain:

living standard

A configuration file to check against a particular WhatWG living standard, gathering statistics:

shadow output

A configuration file to shadow copy and deduplicate a site might contain:

ontology

A configuration file to export ontologies content from schema.org version 7.2 might contain:

Actually, ssc will report on any microdata it finds, no matter what. Note that, if you use itemref in your pages, ssc may give false warnings in the section referenced by the itemref. This is because ssc does not always know that the referenced data is not intended to be used in its own right, unless you put it under a <TEMPLATE> element.

statistics

To gather some site stats:

This turns on summary statistics, which produces a grand total at the end of a complete run (add page= below summary for individual page stats). There are many other stats reports available.

Note also that server side includes have been turned on using general.ssi, and files with the SHTML extension will be treated as web pages.

mathML

This configuration file could be used to test MathML 2.

What’s interesting here is the validation section. The MathML documentation lists a specific set of values that can be used with the TYPE attribute on the CI element. The examples in the specification give this attribute many additional, and apparently illegal, values. (This apparent inconsistency is not uncommon amongst web specifications.) The way to avoid ssc complaining about these extra values is to give CI TYPE additional values in the configuration file, as noted.

Indeed, many enumerated attribute values can be extended in this way. Use the --validation switch to get a complete list.

real world examples

arts & ego

These files are based on the steps I take to update my OpenBSD hosted website, arts & ego.

Presume a directory containing the following:

Then I run a script like this:

upload.sh is a macos bash script that can be found among the source code. Note that I have rather naughtily replaced OpenBSD’s httpd document directory /var/www/htdocs with a link.

Here is a recent site.conf:

My site has been built by hand over the decades, and is full of errors. I wrote ssc because I was frustrated that I could find no tool to properly check it. Unfortunately, ssc is too successful: it finds a gadzillion errors in arts & ego. I am slowly making the repairs.

OpenBSD website

Perhaps you’ve grabbed a copy of the OpenBSD website from github:

Dylan Harris
November 2024