#7 Requirements for Site Generator and Font Definition File format

Closed
opened 1 month ago by lhinderberger · 1 comments

This document collects the long-term requirements for

  • The fontJAM Font Site Generator and in consequence
  • the Font Definition File format

This document will be rather technical. Its focus will be less on explanation and more on completeness. For a more explanatory, birds-eye view of the general idea of fontJAM, please have a look at #1.

Comments, criticism and suggestions are warmly welcome and may be used to improve this document.

Requirements that are intended for the first milestone, v0.1.0, are marked with M1.

Font Site Generator requirements

There are three major features of the Font Site Generator, the requirements for each are listed below:

Configuration and dependency management

The Font Site Generator operates within the context of a so-called Site.

  • For each Site, there must exist a plain text, human editable TOML configuration file. The Site Configuration File contains configuration keys that control how the final site shall be generated, for example keys that enable or disable the generation of a search index. The individual configuration keys are not in the scope of this document and will be determined during implementation. M1

  • The Site Configuration File may be named either fontJAM.toml or .fontJAM.toml. M1

    • If both files exist, this is an error condition. M1
  • Each site depends on a number of fonts, which are specified in the Site Configuration File, with each Font Dependency M1

    • referring to a Font Definition File
      • Either a local file in the same or a subdirectory of the Site, or
      • a font from the Common Font Definition Database, referenced by its Key and exact Version, or
      • a font downloaded from the web, referenced by its https URL
    • being identified by the Key of the font or a user-configurable alias (e.g. in case two fonts would otherwise use the same Key, which is not allowed)
  • There must be a number of CLI tools operating on the Site Configuration File in the current working directory

    • fontjam init (interactive) to help the user initialize a Site M1
    • fontjam add, fontjam remove and fontjam update to help the user add, remove and update Font Dependencies M1 (except update)
    • fontjam build to build the Site M1
  • The Font Site Generator should cache downloaded Font Definition Files M1

  • In future releases it should be possible to define custom font databases that act similarly to (or as a proxy for) the Common Font Definition Database.

  • In future, font dependencies from the Common Font Definition Database (or other datbases) may be specified by giving a version range, if the font supports Semantic Versioning.

Font Index generation

A Font Index is part of every fontJAM Site and contains important metadata about the contents and features of the Site.

Font Indexes until fontJAM v1.0.0 will not have a written specification (other than fontJAM’s source code) and are not necessarily forwards- or backwards-compatible. Font Indexes starting from v1.0.0 must have a written specification; their compatibility requirements will be determined then.

A Font Index consists of multiple files, the requirements for each are listed below:

  • The Summary Index in the file index/summary.json gives general information about the Site and the fonts deployed there (the newest versions only) and must contain: M1

    • The generator and version used to generate the Site (e.g. “fontJAM v0.1.0”)
    • A list of features that the Site supports
    • A list of the fonts that are part of the Site, with for each font
      • its Key
      • its Version
      • its General Metadata (see Font Definition File format)
      • links to TOML and JSON of its Font Definition File
  • If fonts are hosted (not only indexed) on the Site, The Deployment Index in the file index/deployment.json gives information about the versions and formats available on the Site and must contain: M1

    • For each version of each font deployed at the Site
      • a list of variants deployed at the site, with for each variant
        • a link to the CSS for inclusion as a webfont (note that the path to these CSS files will be deterministic and it is included here only for completeness)
        • a set with links to all the individual font files belonging to this variant
  • If the Site supports the history feature, The History Index in the file index/history.json gives information about previous versions of the fonts in the Site and must contain:

    • For the current and each previous version of each font in the Site:
      • Links to the TOML and JSON versions of its Font Definition File
      • The set of font weights / features / etc. of this version
      • The difference of the feature set between the current and the previous version, especially if that includes a license change
  • If the Site supports the search feature, The Search Index in the file index/search.json contains a previously calculated search index for quickly finding fonts by name and properties, and may contain (the specifics are still T.B.D.):

    • An index to find fonts by Display Name
    • An index to find fonts by Author
    • An index to find fonts based on specific features (e.g. variable width, serif/sans-serif etc.)
    • An index to find fonts based on supported languages/scripts (e.g. Arabic, Chinese, German, Greek etc.)
  • If the Site supports the preview feature, The Preview Index, in the file index/previews.json, which contains information about and links to previously generated preview images of the fonts, and may contain:

    • For the most recent version of each font in the Site
      • Information about and links to preview images, with the specifics T.B.D.
  • The Font Site Generator must automatically generate the Font Index on Site build M1

  • If the preview feature is enabled, in the Site Configuration File the Font Site Generator must be able to automatically generate font previews

Font self-hosting

A fontJAM site may contain copies of the font dependencies, in order to be able to self-host fonts.

  • This is an opt-out feature (feature name no-hosting), as it is possible to only generate a Font Index without also hosting the fonts. M1

  • On Site build, the Font Site Generator will, for each font that is defined as a dependency in the Site Configuration File:

    • Download (if not cached), verify (using the hashsum in the Font Definition File) and cache the downloaded archive. M1
      • If font verification fails, this is an error condition and must abort Site build. M1
    • Apply patches as specified in the Font Definition File M1
    • Auto-generate CSS files for the inclusion as web fonts, based on the information in the Font Definition File M1
      • For supported licenses, the generated CSS file shall contain the necessary licensing information
      • For non-supported licenses, the Font Site Generator must output a warning
    • Automatically compress the font as WOFF2
    • Optionally rename the font if it’s an RFN font
    • Refuse modification of fonts marked as OFL1.1-RFN M1
  • The built fonts must be collected in the dist subdirectory of the build target directory. M1

  • Build results should be cached so that re-builds are faster.

Deployment

Future versions of the Font Site Generator may contain facilities to deploy the finished Site for example to Codeberg Pages.

Font Definition File format requirements

A Font Definition File contains metadata and technical information such as verification hashes and preparation instructions/patches about a specific version of a font.

Using the requirements for the Font Site Generator, we can derive a number of requirements for the Font Definition File format:

  • A specification for the Font Definition File format must be written, which remains in draft status until the release of fontJAM v1.0.0; compatibility requirements are T.B.D. M1

  • A Font Definition File must contain the following General Metadata, which will also be mirrored to the Summary Index M1:

    • Display name
    • Version
    • Short summary
    • Name of author(s)
  • In addition the Font Definition File must contain the following data: M1

    • Legal information
      • SPDX code of license (for SIL OFL it MUST be specified whether it contains a RFN or not - the generic form will be considered invalid)
      • Copyright line
      • EDIT2: Path to license file (i.e. LICENSE.txt) within font archive
    • Versioning information
      • Indication whether the font supports Semantic Versioning
    • Sourcing and integrity information
      • HTTPS URL of where to get the font’s archive file
        • This may also be a list of URLs, to specify mirrors
      • A SHA256 hashsum of the archive file
    • Font metadata
      • A list of supported languages/scripts (e.g. Chinese, German, etc.) EDIT1
      • A list of included font files, with for each file
        • the path to it, relative to the archive root
        • its format (e.g. TTF, WOFF2, etc.) EDIT1
        • its style (e.g. regular/italic) EDIT1
        • its weight (or indication of variable weight) EDIT1
      • A list of possible subsets of the font (if any) EDIT1
    • Preparation instructions and patches
      • A list of files and directories to be deleted or renamed
      • A list of patches to be applied to the font distribution

Other requirements

  • fontJAM must be designed to work cross-platform or, if that is not feasible in the beginning, to at least be easily portable. M1

  • There must be user documentation for fontJAM available in the source repository. M1

  • The fontJAM project should get a website that contains general information about the project, download instructions, file format specification, user documentation, and API reference.

  • User documentation and API reference should be automatically added to the website, for all releases of fontJAM.

  • The specification of the Font Definition File format should be automatically added to the website, for all releases of the specification

  • The website should contain a GUI instance featuring a list of all fonts in the Common Font Definition Database, but it must not offer font hosting. (For font hosting, Codeberg Fonts is intended to be the “flagship” site, if fontJAM is accepted).

Edits

EDIT1

Removed font metadata from FDF that can be auto-derived later on.
Subsets of fonts should either be auto-deriveable or constitute multiple FDFs.

EDIT2

Added path to license file to Font Definition File Format requirements.

EDIT3

Strikethrough “no written specification for font metadata”

This document collects the long-term requirements for - The fontJAM Font Site Generator and in consequence - the Font Definition File format This document will be rather technical. Its focus will be less on explanation and more on completeness. For a more explanatory, birds-eye view of the general idea of fontJAM, please have a look at #1. Comments, criticism and suggestions are warmly welcome and may be used to improve this document. Requirements that are intended for the first milestone, v0.1.0, are marked with **M1**. ## Font Site Generator requirements There are three major features of the Font Site Generator, the requirements for each are listed below: ### Configuration and dependency management The Font Site Generator operates within the context of a so-called Site. - For each Site, there must exist a plain text, human editable TOML configuration file. The Site Configuration File contains configuration keys that control how the final site shall be generated, for example keys that enable or disable the generation of a search index. The individual configuration keys are not in the scope of this document and will be determined during implementation. **M1** - The Site Configuration File may be named either `fontJAM.toml` or `.fontJAM.toml`. **M1** - If both files exist, this is an error condition. **M1** - Each site depends on a number of fonts, which are specified in the Site Configuration File, with each Font Dependency **M1** - referring to a Font Definition File - Either a local file in the same or a subdirectory of the Site, or - a font from the Common Font Definition Database, referenced by its Key and exact Version, or - a font downloaded from the web, referenced by its https URL - being identified by the Key of the font or a user-configurable alias (e.g. in case two fonts would otherwise use the same Key, which is not allowed) - There must be a number of CLI tools operating on the Site Configuration File in the current working directory - `fontjam init` (interactive) to help the user initialize a Site **M1** - `fontjam add`, `fontjam remove` and `fontjam update` to help the user add, remove and update Font Dependencies **M1 (except update)** - `fontjam build` to build the Site **M1** - The Font Site Generator should cache downloaded Font Definition Files **M1** - In future releases it should be possible to define custom font databases that act similarly to (or as a proxy for) the Common Font Definition Database. - In future, font dependencies from the Common Font Definition Database (or other datbases) may be specified by giving a version range, if the font supports Semantic Versioning. ### Font Index generation A Font Index is part of every fontJAM Site and contains important metadata about the contents and features of the Site. ~~Font Indexes until fontJAM v1.0.0 will not have a written specification (other than fontJAM's source code) and are not necessarily forwards- or backwards-compatible.~~ Font Indexes starting from v1.0.0 must have a written specification; their compatibility requirements will be determined then. A Font Index consists of multiple files, the requirements for each are listed below: - The Summary Index in the file `index/summary.json` gives general information about the Site and the fonts deployed there (the newest versions only) and must contain: **M1** - The generator and version used to generate the Site (e.g. "fontJAM v0.1.0") - A list of features that the Site supports - A list of the fonts that are part of the Site, with for each font - its Key - its Version - its General Metadata (see Font Definition File format) - links to TOML and JSON of its Font Definition File - If fonts are hosted (not only indexed) on the Site, The Deployment Index in the file `index/deployment.json` gives information about the versions and formats available on the Site and must contain: **M1** - For each version of each font deployed at the Site - a list of variants deployed at the site, with for each variant - a link to the CSS for inclusion as a webfont (note that the path to these CSS files will be deterministic and it is included here only for completeness) - a set with links to all the individual font files belonging to this variant - If the Site supports the `history` feature, The History Index in the file `index/history.json` gives information about previous versions of the fonts in the Site and must contain: - For the current and each previous version of each font in the Site: - Links to the TOML and JSON versions of its Font Definition File - The set of font weights / features / etc. of this version - The difference of the feature set between the current and the previous version, especially if that includes a license change - If the Site supports the `search` feature, The Search Index in the file `index/search.json` contains a previously calculated search index for quickly finding fonts by name and properties, and may contain (the specifics are still T.B.D.): - An index to find fonts by Display Name - An index to find fonts by Author - An index to find fonts based on specific features (e.g. variable width, serif/sans-serif etc.) - An index to find fonts based on supported languages/scripts (e.g. Arabic, Chinese, German, Greek etc.) - If the Site supports the `preview` feature, The Preview Index, in the file `index/previews.json`, which contains information about and links to previously generated preview images of the fonts, and may contain: - For the most recent version of each font in the Site - Information about and links to preview images, with the specifics T.B.D. - The Font Site Generator must automatically generate the Font Index on Site build **M1** - If the `preview` feature is enabled, in the Site Configuration File the Font Site Generator must be able to automatically generate font previews ### Font self-hosting A fontJAM site may contain copies of the font dependencies, in order to be able to self-host fonts. - This is an opt-out feature (feature name `no-hosting`), as it is possible to only generate a Font Index without also hosting the fonts. **M1** - On Site build, the Font Site Generator will, for each font that is defined as a dependency in the Site Configuration File: - Download (if not cached), verify (using the hashsum in the Font Definition File) and cache the downloaded archive. **M1** - If font verification fails, this is an error condition and must abort Site build. **M1** - Apply patches as specified in the Font Definition File **M1** - Auto-generate CSS files for the inclusion as web fonts, based on the information in the Font Definition File **M1** - For supported licenses, the generated CSS file shall contain the necessary licensing information - For non-supported licenses, the Font Site Generator must output a warning - Automatically compress the font as WOFF2 - Optionally rename the font if it's an RFN font - Refuse modification of fonts marked as OFL1.1-RFN **M1** - The built fonts must be collected in the `dist` subdirectory of the build target directory. **M1** - Build results should be cached so that re-builds are faster. ### Deployment Future versions of the Font Site Generator may contain facilities to deploy the finished Site for example to Codeberg Pages. ## Font Definition File format requirements A Font Definition File contains metadata and technical information such as verification hashes and preparation instructions/patches about a specific version of a font. Using the requirements for the Font Site Generator, we can derive a number of requirements for the Font Definition File format: - A specification for the Font Definition File format must be written, which remains in draft status until the release of fontJAM v1.0.0; compatibility requirements are T.B.D. **M1** - A Font Definition File must contain the following General Metadata, which will also be mirrored to the Summary Index **M1**: - Display name - Version - Short summary - Name of author(s) - In addition the Font Definition File must contain the following data: **M1** - Legal information - SPDX code of license (for SIL OFL it MUST be specified whether it contains a RFN or not - the generic form will be considered invalid) - Copyright line - EDIT2: Path to license file (i.e. `LICENSE.txt`) within font archive - Versioning information - Indication whether the font supports Semantic Versioning - Sourcing and integrity information - HTTPS URL of where to get the font's archive file - This may also be a list of URLs, to specify mirrors - A SHA256 hashsum of the archive file - Font metadata - ~~A list of supported languages/scripts (e.g. Chinese, German, etc.)~~ EDIT1 - A list of included font files, with for each file - the path to it, relative to the archive root - ~~its format (e.g. TTF, WOFF2, etc.)~~ EDIT1 - ~~its style (e.g. regular/italic)~~ EDIT1 - ~~its weight (or indication of variable weight)~~ EDIT1 - ~~A list of possible subsets of the font (if any)~~ EDIT1 - Preparation instructions and patches - A list of files and directories to be deleted or renamed - A list of patches to be applied to the font distribution ## Other requirements - fontJAM must be designed to work cross-platform or, if that is not feasible in the beginning, to at least be easily portable. **M1** - There must be user documentation for fontJAM available in the source repository. **M1** - The fontJAM project should get a website that contains general information about the project, download instructions, file format specification, user documentation, and API reference. - User documentation and API reference should be automatically added to the website, for all releases of fontJAM. - The specification of the Font Definition File format should be automatically added to the website, for all releases of the specification - The website should contain a GUI instance featuring a list of all fonts in the Common Font Definition Database, but it must not offer font hosting. (For font hosting, Codeberg Fonts is intended to be the "flagship" site, if fontJAM is accepted). ## Edits #### EDIT1 Removed font metadata from FDF that can be auto-derived later on. Subsets of fonts should either be auto-deriveable or constitute multiple FDFs. #### EDIT2 Added path to license file to Font Definition File Format requirements. #### EDIT3 Strikethrough "no written specification for font metadata"
lhinderberger added the
Status: Needs feedback
label 1 month ago
lhinderberger added the
Kind: Documentation
label 1 month ago
lhinderberger commented 3 weeks ago
Owner

Closing, as the requirements have now been distributed to their appropriate places across the various fontJAM issue trackers.

Closing, as the requirements have now been distributed to their appropriate places across the various fontJAM issue trackers.
lhinderberger closed this issue 3 weeks ago
Sign in to join this conversation.
No Milestone
No Assignees
1 Participants
Notifications
Due Date

No due date set.

Dependencies

This issue currently doesn't have any dependencies.

Loading…
There is no content yet.