NAME
ssc - analyse static web sites at source



SYNOPSIS
ssc [...] directory
ssc -f config
ssc



DESCRIPTION
ssc (the Static Site Checker) is an opinionated HTML nit-picker, intended for people, such as its author, who hand code websites.
It doesn't just check static websites for broken links, dubious syntax, and bad semantic data, it will actively complain about
things that are perfectly legal but just a little bit untidy.

Except when serving CGI queries, it recursively scans the directory looking for HTML source files to analyse. It produces a list
of errors, warnings, comments, and other hints of imperfection. Once complete, it summarises internal site inconsistencies, and
can produce some simple statistics.

ssc ignores HTML scripts.

The options are as follows:

-3                      Normally, when ssc checks external links (--link.external) it does not report http forwarding errors
--link.301              301 and 308. Use this switch to have it do so.

-e                      check external links, e.g. those not on the site being checked. This requires a copy of curl on the path.
--link.external         Note that ssc will NOT check sites such as example.com, rather it will presume the link is valid.

-f file                 load configuration from file, which should be in .INI file format. See CONFIGURATION FILE FORMAT below.

-F                      load configuration file from .ssc/config in the current directory.

-g dir                  this is the root of the website to analyse. ssc will recursively scan the directory analysing any HTML
--site.root dir         files it finds. The default is the current directory.

--general.css           do NOT process .css files

--general.custom el     define a custom element 'el' for verifying the IS attribute. May be repeated.

--general.ignored el    ignore attributes and content of the specified element. May be repeated.

--general.lang la       when HTML files do not have a language specified (e.g. "en" for standard (Her Majesty's) English, "en_IE" for Irish
                        English, "lb" for Luxembourgish, etc.), default to 'la'. If not given, the default is your system default, or, if none,
                        then "en_US".

--general.maxfilesize n Do not process HTML source files are exceeed n bytes in size. Specify 0 for unlimited, although be warned that ssc is
                        stunningly stupid and will attempt to load files that exceed available memory.

--general.rdf           Check RDF attributes. This option currently underperforms. An extension to properly support RDF and RDFs is planned.

--general.rel           Only mention <LINK> REL values, found neither in the living standard nor at microformats.org, in debug output.

--general.slob          Ignore perfectly legal but inefficient, indeed thoroughly slobby, HTML, such as being far too lazy to get round to
                        bothering to close elements.

-h                      print a summary of switches and exit

--html.tags             When an HTML file is loaded that contains no DOCTYPE, ssc normally presumes it's an HTML 1 file. This switch tells it to
                        presume the file follows an earlier HTML Tags specification (the one at CERN). This is overridden by --html.version.

--html.rfc1867          Ignore the RFC 1867 (INPUT=FILE) extension when processing HTML 2.0

--html.rfc1942          Ignore the RFC 1942 (tables) extension when processing HTML 2.0.

--html.rfc19802         Ignore the RFC 1980 (client side image maps) extension when processing HTML 2.0.

--html.rfc2070          Ignore the RFC 2070 (internationalisation) extension when processing HTML 2.0.

--html.version X        If no doctype is specified, presume version X of HTML. X can be:
                            tags        HTML tags (1991, informal)
                            1.0         HTML 1.0 (June 1993 draft)
                            +           HTML Plus (November 1993 draft)
                            2.0         HTML 2.0 (RFC 1860)
                            3.0         HTML 3.0 (March 1995 draft)
                            3.2         HTML 3.2
                            4.0         HTML 4.0
                            4.1         HTML 4.01
                            4.2         XHTML 1.0
                            4.3         XHTML 1.1 Core
                            4.4         XHTML 2.0
                            5.0         W3 HTML 5.0
                            5.1         W3 HTML 5.1
                            5.2         W3 HTML 5.2
                            5.3         W3 HTML 5.3 (October 2018 draft)
                            2005/1/1    WhatWG WebApps draft (January 2005)
                            ...
                            2007/1/1    WhatWG WebApps draft (January 2007)
                            2007/7/1    WhatWG HTML 5 living standard (July 2007)
                            ...
                            2021/4/1    WhatWG HTML 5 living standard (April 2021)

                        Although you can specify exact dates for versions of the What WG HTML 5 living standard, currently only broad versions
                        published in January and July are supported (and April 2021). It is expected that, as the standard develops, more
                        precision will be applied to changes in ssc analysis.

                        Certain versions of HTML offer variants, such as loose and strict definitions. ssc picks those up from the SGML headers
                        in the HTML file, if any, and carelessly ignores them.

                        Validation of code built to old standards, including XHTML standards, is not strict. Validation of code built to
                        contemporary standards is better. Just to remind you, there are no guarantees of accuracy (or inaccuracy).

                        Copies of the appropriate standards can be found online at source, or can be downloaded from ssc.lu.

-i file                 This is the name of the index file in a directory. This can be repeated. This is used for checking internal links.
--site.index file

-I                      Process Server Side Includes. Although ssc can process many server side includes, it cannot process those containing
--general.ssi           formulae. Note that processing SSIs may cause incorrect line numbers to be mentioned when an issue is described.

-L v=a                  The HTML virtual directory 'v' is located in actual directory 'a' on the local filesystem.
--site.virtual v=a

-l                      Check internal links, e.g. those within the website being checked.
--link.internal

--math.version          Presume this version of MathML (1, 2 or 3). The following versions are supported:
                                0   work it out from the (HTML) version of the file being analysed
                                1   MathML 1
                                2   MathML 2
                                3   MathML 3
                                4   MathML 4 (December 2020 draft)

-m                      Check schema.org & n.whatwg.org microdata found in WhatWG microdata attributes (itemprop, itemtype, etc.)
--microdata.microdata

--microdata.export      Export schema.org microdata encountered. This data is exported in JSON format.

--microdata.root dir    when exporting microdata with --microdata.export, write files into dir. sssc will create the directory tree
                        structure as appropriate

--microdata.version x.y Test for schema.org microdata version X.Y
                        The following values are valid:
                                version 2: 2.0 to 2.2
                                version 3: 3.0 to 3.9
                                versions 4.0, 5.0, 6.0
                                version 7: 7.0 to 7.04
                                versions 8.0, 9.0, 10.0, 11.0, 12.0
                        If .Y is omitted, version X.0 is presumed.

--microdata.virtual v=d when exporting microdata using --microdata.export, export the contents of virtual directory 'v' to 'd'. 'v'
                        must corresponding to a directory identified with --site.virtual.

-m x                    When validating W3 HTML 5 source code, using this minor version of HTML 5. Valid values are 0, 1, 2, and 3.
--validation.minor x    WhatWG versions are determined by date, corresponding roughly to the date of the (online) publication  of the
                        specific version. See the --html.version switch.

-M                      Verify Microformats data in class and rel attributes (see https://microformats.org/).
--microformat.verify

--microformat.export    Export microformat data encountered in JSON format. This option will write files in the same directory as the source,
                        with the extension .json.

--microformat.version x Presume microformats version x. The following values are current accepted:
                                1   microformats version 1 only
                                2   microformats version 2 only
                                3   both microformats versions 1 and 2

-n                      report what ssc would do, but do not do it
--general.nochange

--nits.catastrophe n    redefine nit n as a catastrophe; may be repeated (the value of n can be determined using --nits.nids below)

--nits.codes            output nit codes

--nits.comment n        redefine nit n as a comment; may be repeated (the value of n can be determined using --nits.nids below)

--nits.debug   n        redefine nit n as a debug message; may be repeated (the value of n can be determined using --nits.nids below)

--nits.error n          redefine nit n as an error; may be repeated (the value of n can be determined using --nits.nids below)

--nits.info n           redefine nit n as information; may be repeated (the value of n can be determined using --nits.nids below)

--nits.nids             output nit ids, which can be used to redefine nits

--nits.silence n        silence nit n; may be repeated (the value of n can be determined using --nits.nids below)

--nits.warning n        redefine nit n as a warning; may be repeated (the value of n can be determined using --nits.nids below)

-o file                 output to the specified file. If this switch is not used, standard output is used.
--general.output

-O                      Only report each broken external link once. If, for example, the site has a number of references to http://broken.com/duff.html
--link.once             which does not exist, ssc will only report the first instance of the broken link. Note that, even if it reports every occurrence
                        of the link, it will only check it the first time it encounters it (unlike a good number of other link checkers out there).
                        Requires --link.external

-p dir                  look for any configuration, caches, and other useful files, in this directory
--general.datapath dir

-r                      Do not check whether a https link's https certificates have been revoked. Requires --link.external
--link.revoke

-s domain               The domain name of the site is 'domain'. This can be repeated. This is used to identify any URL that is apparently external but
--site.domain domain    is actually internal to the site.

--shadow.comment        Do not delete comments when writing shadow pages

--shadow.copy x         Create a shadow directory structure from the source HTML files, which errors removed and some other things tidied up.
                        Specify the strategy to use for non HTML files:
                                0   shadow nothing (default)
                                1   write 'fixed' source files, ignore non source files
                                2   set up hard links to non-source files (requires source and shadow directories to be on the same disk)
                                3   set up soft links to non-source files
                                4   copy non HTML files
                                5   copy non HTML files, but deduplicate them, changing links in HTML source if necessary
                                6   only report duplicates (no shadowing)
                        NOTE: ssc cannot convert between versions of HTML, or between HTML and XHTML. For that, using the 'tidy' utility.

--shadow.file f         Write ssc's shadow cache to this file, to accelerate future shadows of the same content

--shadow.ignore ext     When shadowing, ignore files with this extension. May be repeated

-- shadow.info          Add a comment at the top of each shadowed HTML file noting its generation time

--shadow.ssi            Do NOT resolve SSIs when shadowing even if --general.ssi is set.

--shadow.spacing        Leave excess and repeated spaces and blank lines in the HTML files untidily untouched

--shadow.virtual v=d    When shadowing virtual directories, output the shadow of virtual directory 'v' to directory 'd'. 'v' must corresponding to a directory
                        set up using --site.virtual

--stats.meta            Produce statistics on <META> usage in <HEAD>. Note that pragmas reported (http-equiv) are those found in the HTML source, not those
                        returned by the HTTP protocol. Note that many web servers (not all) will remove some pragmas when serving pages.

--stats.page            Produce statistics for each source file encountered

--stats.summary         Produce a summary of overall statistics for the website

--svg.version x         Presume any SVG code encountered is this version. Valid versions are 1.0 / 1.1 / 2.0. The SVG code may specify the version itself.
                        If this switch is not used, and some SVG code does not identify its version, the version is worked out from the version of the host HTML
                        code.

-v x                    ssc becomes verbose and outputs additional information. X is a digit to indicate verbosity level. Verbosity levels are:
--general.verbose x         0 keep mum
                            1 catastrophic errors
                            2 errors
                            3 warnings
                            4 information
                            5 comments
                            ... debug
                        Each level includes its preceding level, so, for example, level 3 (warnings) will also output levels 0 to 2.

-V                      print version details and exit

--validation            list attribute extensions and exits. Attribute extensions are additional values that can be associated with attributes
                        on HTML elements. When such values are found, no error or warning is raised.

--validation.microdata  validate (schema.org) microdata

--validation.*          Add a permitted value to a particular HTML enumeration. Can be repeated. Extendable enumerations include charset,
                        class (valid values may also be picked up from CSS files), colour, currency, http-equiv, lang, metaname, mimetype,
                        rel, and SGML. A full set of possible enumerations can be listed using the --validation switch.

-x ext                  treat files with this extension as HTML source files. This may be repeated. Files with extension .html are always checked.
--site.extension ext

-X                      Check crosslink IDs on the site being analysed. For example, if a link goes to /index.html#id, then, when this switch is set,
--link.xlink            ssc will verify that the id exists and that it is not hidden. This feature uses additional memory.

-z n                    If some <TITLE> text is longer than n characters, say so.  This applies to child text of a <TITLE> element, not the value of
--html.title n          TITLE attributes.



CONFIGURATION FILE FORMAT

If a configuration file is used, it should be in INI file format. All content is optional.

Section and option names are derived from the long form switch name, which consists of SECTION.OPTION, laid out in the format:
[SECTION]
OPTION=yes
OPTION=123456

Switches that do not have a long form version cannot be used in a configuration file.

Note that the ssc source code includes a number of tests, all of which have configuration files. Browse them for examples.



ENVIRONMENT

SSC_CONFIG              If no configuration file given on the command line, use this one
SSC_ARGS                Preliminary command line parameters

If, when SSC is run, the environment variable QUERY_STRING is set to an OpenBSD httpd server CGI value that includes the parameter
html.snippet, then SSC will nitpick that snippet only. Some other parameters are processed, including general.verbose and html.version.



EXIT STATUS
If no errors are found ssc exits with 0, otherwise it exits with a value > 0.



EXAMPLES

To verify the version of ssc:
ssc -V

To check the static web side source directory /home/site/wwwroot:
ssc /home/site/wwwroot

To check a static website for example.com,  in the current directory, that uses server side includes,
including verification of external links, with very verbose output:
ssc -e -I -x html -x shtml -s example.com -v 5 -i index.shtml

To check a static web side in the current directory, with a virtual directory, verifying microformats:
ssc -L vitual=/home/site/virtual -M

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

A simple configuration file might contain:
[general]
verbose=4
output=simple.out
[site]
domain=example.edu
extension=html
index=index.html
root=simple

A configuration file to check a site against HTML 5.2 and SVG 1.1 might contain:
[general]
output=site.out
class=yes
[link]
check=yes
[site]
domain=example.edu
extension=html
index=index.html
root=site
[html]
version=5.2
[svg]
version=1.1

A configuration file to check against a particular WhatWG living standard, gathering statistics:
[general]
output=jan21.out
[html]
version=2021/01/01
[link]
check=yes
[microdata]
version=11.0
[site]
domain=example.edu
extension=html
index=index.html
root=site
[stats]
summary=yes
meta=yes

A configuration file to shadow copy and deduplicate a site might contain:
[general]
output=dedu.out
class=yes
[site]
domain=example.edu
extension=html
index=index.html
root=site
[shadow]
copy=5
root=shadow
file=dedu.ndx

A configuration file to export microdata preparing against schema.org version 7.2 might contain:
[general]
output=export.out
class=yes
[site]
domain=example.edu
extension=html
index=index.html
root=site
[link]
check=yes
[microdata]
export=yes
root=export
version=7.2



SEE ALSO
tidy



STANDARDS
A full set of standards used to guide the development of ssc can be viewed at https://ssc.lu/. These are copied from
many sources online, including https://w3.org/ and https://whatwg.org/. Check https://ssc.lu/ for details.



HISTORY
ssc is written by Dylan Harris, https://ssc.lu/.
