X-Git-Url: https://git.distorted.org.uk/~mdw/sgt/agedu/blobdiff_plain/70322ae3751bc07ac749dffad79a5f3420e67b55..HEAD:/html.h diff --git a/html.h b/html.h index a02babf..47b7ffd 100644 --- a/html.h +++ b/html.h @@ -2,16 +2,143 @@ * html.h: HTML output format for agedu. */ +struct html_config { + /* + * Configure the format of the URI pathname fragment corresponding + * to a given tree entry. + * + * 'uriformat' is expected to have the following format: + * - it consists of one or more _options_, each indicating a + * particular way to format a URI, separated by '%|' + * - each option contains _at most one_ formatting directive; + * without any, it is assumed to only be able to encode the + * root tree entry + * - the formatting directive may be followed before and/or + * afterwards with literal text; percent signs in that literal + * text are specified as %% (which doesn't count as a + * formatting directive for the 'at most one' rule) + * - formatting directives are as follows: + * + '%n' outputs the numeric index (in decimal) of the tree + * entry + * + '%p' outputs the pathname of the tree entry, not counting + * any common prefix of the whole tree or a subdirectory + * separator following that (so that the root directory of + * the tree will always be rendered as the empty string). + * The subdirectory separator is translated into '/'; any + * remotely worrying character is escaped as = followed by + * two hex digits (including, in particular, = itself). The + * only characters not escaped are the ASCII alphabets and + * numbers, the subdirectory separator as mentioned above, + * and the four punctuation characters -.@_ (with the + * exception that at the very start of a pathname, even '.' + * is escaped). + * - '%/p' outputs the pathname of the tree entry, but this time + * the subdirectory separator is also considered to be a + * worrying character and is escaped. + * - '%-p' and '%-/p' are like '%p' and '%/p' respectively, + * except that they use the full pathname stored in the tree + * without stripping a common prefix. + * + * These formats are used both for generating and parsing URI + * fragments. When generating, the first valid option is used + * (which is always the very first one if we're generating the + * root URI, or else it's the first option with any formatting + * directive); when parsing, the first option that matches will be + * accepted. (Thus, you can have '.../subdir' and '.../subdir/' + * both accepted, but make the latter canonical; clients of this + * mechanism will typically regenerate a URI string after parsing + * an index out of it, and return an HTTP redirect if it isn't in + * canonical form.) + * + * All hyperlinks should be correctly generated as relative (i.e. + * with the right number of ../ and ./ considering both the + * pathname for the page currently being generated, and the one + * for the link target). + * + * If 'uriformat' is NULL, the HTML is generated without hyperlinks. + */ + const char *uriformat; + + /* + * Configure the filenames output by html_dump(). These can be + * configured separately from the URI formats, so that the root + * file can be called index.html on disk but have a notional URI + * of just / or similar. + * + * Formatting directives are the same as the uriformat above. + */ + const char *fileformat; + + /* + * Time stamps to assign to the extreme ends of the colour + * scale. If "autoage" is true, they are ignored and the time + * stamps are derived from the limits of the age data stored + * in the index. + */ + int autoage; + time_t oldest, newest; + + /* + * Specify whether to show individual files as well as + * directories in the report. + */ + int showfiles; + /* + * The string appearing in the