metanorma-taste 0.1.3 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 93ec554922c0639b8d8145f5719df4b2bafdf898f97cefce58a8300a29637583
-  data.tar.gz: 77ac6c4cae4af665e6100a4822d79b3b42fa67cd7f6b3ca0a4b203957013d303
+  metadata.gz: 8f4a74f3a7d05b348f0321f8b705f4ee3be169f70e3fed955dcb61c668bf4a6a
+  data.tar.gz: aab5942f506ae7ecf610db8ab24290e8867cb8ed889e6e4ea5357f1ff9130a78
 SHA512:
-  metadata.gz: b0e0ef6772b27117b40bb0a65f3fc3221b1597dfba88720a9ec4148542d590771a6c52ed8020aef07784a7a930d7bae951bac9fd2b924aaad99c7a5b7d9d2e2d
-  data.tar.gz: d7a246f2898f8ad2c0edbc77f27ebd5a03eb801d755102b7306d54e799abbfb86e817560023fa278ec81fa06f204f64aa0fe5398e480297539988f64694960ea
+  metadata.gz: 57a9509823af08dbabc4266a4c6a54d88c34f9e2b9f5bc4c0f99d47094ce96423e5dbdb7d469e4d5f054d13d37e40b1a3fb228d04fdc8cb6996e950897594b23
+  data.tar.gz: 9e1ac2f9d11c7917e9daa8af65fcb9478ee876b2ebcf25ffc4cbe9e07df45ff5dd1256b370b65068fc2b536150fca1d47389feafbb54583529539c70f202d5a8

data/README.adoc

@@ -152,12 +152,12 @@ currently available:
 |`icc`
 |International Color Consortium
 |`iso`
-|ICC specifications and standards with ICC branding and copyright
+|International Color Consortium specifications and standards with ICC branding and copyright
 
 |`elf`
 |Express Language Foundation
 |`iso`
-|ELF specifications and standards with ELF branding and copyright
+|Express Language Foundation specifications and standards with ELF branding and copyright
 
 |`enosema`
 |Enosema Foundation
@@ -166,8 +166,24 @@ currently available:
 
 |`csa`
 |Cloud Security Alliance
-|`cc`
+|`generic`
 |Cloud Security Alliance specifications and standards with CSA branding and copyright
+
+|`pdfa`
+|PDF Association
+|`ribose`
+|PDF Association specifications and standards with PDFA branding and copyright
+
+|`swf`
+|Spatial Web Foundation
+|`ribose`
+|Spatial Web Foundation specifications and standards with SWF branding and copyright
+
+|`mbxif`
+|MBx Interoperability Forum
+|`ribose`
+|MBx Interoperability Forum specifications and standards with MBx-IF branding and copyright
+
 |===
 
 
@@ -193,7 +209,10 @@ taste.
 === General
 
 A taste package is a directory structure that contains all the necessary files
-to define a Metanorma taste. It includes configuration files, copyright notices, internationalization dictionaries, and stylesheets if any.
+to define a Metanorma taste.
+
+It includes configuration files, copyright notices, internationalization
+dictionaries, and stylesheets if any.
 
 === Directory structure
 
@@ -220,32 +239,36 @@ The main configuration file for each taste:
 flavor: string             # The name of the custom flavor (e.g., "icc")
 owner: string              # Organization name (e.g., "International Color Consortium")
 base-flavor: string        # Base Metanorma flavor to extend (e.g., "iso")
-copyright-notice: string   # Path to boilerplate file (e.g., "copyright.adoc"), which includes
-                           # copyright, license, legal, and feedback notices
-i18n-dictionary: string    # Path to internationalization dictionary (e.g., "i18n.yaml")
-publisher-logo: string     # Path to publisher logo (e.g., "icc.png")
-htmlcoverpage: string      # HTML output cover page
-htmlintropage: string      # HTML output introductory page
-htmlstylesheet: string     # HTML output CSS stylesheet
-htmlstylesheet-override: string     # HTML output CSS stylesheet, overriding base flavor stylesheet
-wordcoverpage: string      # Word output cover page
-wordintropage: string      # Word output introductory page
-wordstylesheet: string     # Word output CSS stylesheet
-wordstylesheet-override: string     # Word output CSS stylesheet, overriding base flavor stylesheet
-standardstylesheet: string # Word output secondary CSS stylesheet
-standardstylesheet-override: string # Word output secondary CSS stylesheet, overriding base flavor stylesheet
-header: string             # Word output header and footer content
-pdf-stylesheet: string     # PDF output XSLT stylesheet
-pdf-stylesheet-override: string     # PDF output XSLT stylesheet, overriding base flavor stylesheet
-base-override:             # Hash of document attributes to override from base flavor
-  publisher: string        # Publisher name override
-  publisher_abbr: string   # Publisher abbreviation
-  body_font: string        # Default font to use in HTML and Word stylesheets
-  header_font: string      # Header font to use in HTML and Word stylesheets
-  monospace_font: string   # Monospace font to use in HTML and Word stylesheets
-  fonts: string            # Comma-delimited listing of fonts to retrieve for the taste from Fontist
-  output-extensions: string         # Comma-delimited listing of output formats to support (subset of base flavor's)
-  presentation-metadata-*: # Template style attributes for presentation
+base-override:             # Document attributes to override from base flavor
+  filename-attributes:     # Metanorma document attributes that contain filenames
+    copyright-notice: string   # Path to boilerplate file (e.g., "copyright.adoc")
+    i18n-dictionary: string    # Path to internationalization dictionary (e.g., "i18n.yaml")
+    publisher-logo: string     # Path to publisher logo (e.g., "icc.png")
+    htmlcoverpage: string      # HTML output cover page
+    htmlintropage: string      # HTML output introductory page
+    htmlstylesheet: string     # HTML output CSS stylesheet
+    htmlstylesheet-override: string     # HTML output CSS stylesheet, overriding base flavor stylesheet
+    wordcoverpage: string      # Word output cover page
+    wordintropage: string      # Word output introductory page
+    wordstylesheet: string     # Word output CSS stylesheet
+    wordstylesheet-override: string     # Word output CSS stylesheet, overriding base flavor stylesheet
+    standardstylesheet: string # Word output secondary CSS stylesheet
+    standardstylesheet-override: string # Word output secondary CSS stylesheet, overriding base flavor stylesheet
+    header: string             # Word output header and footer content
+    pdf-stylesheet: string     # PDF output XSLT stylesheet
+    pdf-stylesheet-override: string     # PDF output XSLT stylesheet, overriding base flavor stylesheet
+    customize: string          # Path to custom metanorma configuration file
+    coverpage-image: string    # Path to coverpage image file
+    backpage-image: string     # Path to backpage image file
+  value-attributes:        # Metanorma document attributes that contain values
+    publisher: string        # Publisher name override
+    publisher_abbr: string   # Publisher abbreviation
+    body-font: string        # Default font to use in HTML and Word stylesheets
+    header-font: string      # Header font to use in HTML and Word stylesheets
+    monospace-font: string   # Monospace font to use in HTML and Word stylesheets
+    fonts: string            # Comma-delimited listing of fonts to retrieve for the taste from Fontist
+    output-extensions: string         # Comma-delimited listing of output formats to support (subset of base flavor's)
+    presentation-metadata-*: # Template style attributes for presentation
 doctypes:                  # Array of doctypes built over base flavour doctypes
   - taste:                 # taste-specific machine-readable doctype name
     base:                  # Base Metanorma flavor corresponding machine-readable doctype name
@@ -260,13 +283,21 @@ doctypes:                  # Array of doctypes built over base flavour doctypes
 flavor: icc
 owner: International Color Consortium
 base-flavor: iso
-copyright-notice: copyright.adoc
-i18n-dictionary: i18n.yaml
 base-override:
-  publisher: International Color Consortium
-  publisher_abbr: ICC
-  presentation-metadata-color-secondary: '#376795'
-  presentation-metadata-backcover-text: color.org
+  filename-attributes:
+    copyright-notice: copyright.adoc
+    i18n-dictionary: i18n.yaml
+    publisher-logo: icc-full.svg
+    htmlcoverpage: htmlcoverpage.html
+    htmlstylesheet-override: htmlstylesheet-override.scss
+  value-attributes:
+    publisher: International Color Consortium
+    publisher_abbr: ICC
+    presentation-metadata-color-secondary: '#376795'
+    presentation-metadata-backcover-text: color.org
+    body-font: Arial, 'Helvetica Neue', Helvetica, sans-serif
+    header-font: Arial, 'Helvetica Neue', Helvetica, sans-serif
+    output-extensions: xml,html,pdf,doc
 doctypes:
 - taste: specification # Specification # The name goes into i18n.yaml
   base: international-standard
@@ -286,8 +317,11 @@ doctype_dict:             # Document type translations
   # Add more document type mappings as needed
 ----
 
-Note that any taste-specific doctypes need to have a renderable corresponding entry under
-`doctype_dict`. The same is the case for the native doctypes in the base flavor's i18n.yaml files.
+Every taste-specific doctype is required to have a renderable corresponding
+entry under `doctype_dict`.
+
+The same is the case for the native doctypes in the base flavor's `i18n.yaml`
+files.
 
 .i18n.yaml example from ICC
 [example]
@@ -302,7 +336,10 @@ doctype_dict:
 
 ==== copyright.adoc
 
-Organization-specific copyright, legal, license and feedback text. This file can contain:
+This file supplies taste-specific copyright, legal, license and feedback
+text.
+
+This file can contain:
 
 * Copyright statements with template variables (e.g., `{{ docyear }}`)
 * License information
@@ -327,38 +364,151 @@ The file is in the Metanorma AsciiDoc format, with the following syntax:
 
 Copyright (c) {{ docyear }} Your Organization Name
 
-[Legal text here...]
+[legal text here...]
 
 == feedback-statement
-=== Contact Information
+=== Contact information
 
-[Organization contact details...]
+[organization contact details...]
 ----
 ====
 
-The same file format is used internally for Metanorma flavors, and is documented in
-https://www.metanorma.org/develop/topics/metadata-and-boilerplate/[Metadata and predefined text]
-on the metaorma.org site.
+The same file format is used internally for Metanorma flavors, and is documented
+in
+https://www.metanorma.org/develop/topics/metadata-and-boilerplate/[Metadata and predefined text].
+
+=== Base-override configuration
+
+==== General
+
+The `base-override` section allows customization of document attributes
+supported by the base flavor through two categories.
+
+The reason for this division is that some attributes contain file paths relative
+to the taste definition, while others contain simple values that are not
+relevant to path resolution.
+
+* Filename attributes are used to point to custom files provided by the taste,
+under the `data/{taste}/` directory.
++
+[example]
+====
+When `:publisher-logo: {logo-file-path}` is defined in the taste's
+`config.yaml`, the actual logo file is expected to be located at
+`data/{taste}/{logo-file-path}`.
+
+When `:publisher-logo: {logo-file-path}` is defined as a document
+attribute in the input document, the logo file is expected to be located
+relative to the input document's location at
+`{input-document-directory}/{logo-file-path}`.
+====
+
+* Value attributes are simple values (strings, numbers, lists) that do not
+involve file paths. These attributes are identical whether defined in the
+taste's `config.yaml` or as document attributes in the input document.
++
+[example]
+====
+`:publisher_abbr: {abbreviation}` is a simple string value and does not
+involve any file path resolution.
+====
+
+
+==== Filename attributes (`filename-attributes`)
+
+These are Metanorma document attributes that take file paths as values.
+
+`copyright-notice`::
+Path to boilerplate file containing copyright, license, and legal notices
+
+`i18n-dictionary`::
+Path to internationalization dictionary
+
+`publisher-logo`::
+Path to organization logo file
+
+`htmlcoverpage`, `htmlintropage`::
+HTML output page templates
+
+`htmlstylesheet`, `htmlstylesheet-override`::
+HTML CSS stylesheets
+
+`wordcoverpage`, `wordintropage`::
+Word output page templates
+
+`wordstylesheet`, `wordstylesheet-override`::
+Word CSS stylesheets
 
-=== Base-Override configuration
+`standardstylesheet`, `standardstylesheet-override`::
+Secondary Word CSS stylesheets
 
-The `base-override` section allows customization of any document attribute
-supported by the base flavor.
+`header`::
+Word output header and footer content
 
-This includes:
+`pdf-stylesheet`, `pdf-stylesheet-override`::
+PDF XSLT stylesheets
 
-Document attributes:
+`customize`::
+Path to custom metanorma configuration file
 
-* `publisher`: Organization name
-* `publisher_abbr`: Organization abbreviation
-* `doctype`: Document type mappings
-* Custom organization-specific attributes
+`coverpage-image`, `backpage-image`::
+Cover and back page image files
 
-Template style attributes:
 
-* `presentation-metadata-*`: Visual styling attributes
-* Color schemes, logos, layout preferences
-* Typography and formatting options
+==== Value attributes (`value-attributes`)
+
+These are Metanorma document attributes that contain path-independent values.
+
+`publisher`::
+Organization name
+
+`publisher_abbr`::
+Organization abbreviation
+
+`body-font`, `header-font`, `monospace-font`::
+Typography settings
+
+`fonts`::
+Comma-delimited list of fonts to retrieve from Fontist
+
+`output-extensions`::
+Comma-delimited list of supported output formats
+
+`presentation-metadata-*`::
+Visual styling attributes for presentation, including:
+
+`presentation-metadata-color-secondary`:::
+Secondary color for styling
+
+`presentation-metadata-backcover-text`:::
+Text for document back cover
+
+`presentation-metadata-ul-label-list`:::
+Unordered list label formatting
+
+`presentation-metadata-annex-delim`:::
+Annex delimiter formatting
+
+`presentation-metadata-middle-title`:::
+Middle title formatting
+
+`presentation-metadata-ol-label-template-alphabet`:::
+Ordered list alphabet template
+
+`presentation-metadata-ol-label-template-alphabet_upper`:::
+Ordered list uppercase alphabet template
+
+`presentation-metadata-ol-label-template-roman`:::
+Ordered list roman numeral template
+
+`presentation-metadata-ol-label-template-roman_upper`:::
+Ordered list uppercase roman numeral template
+
+`presentation-metadata-ol-label-template-arabic`:::
+Ordered list arabic numeral template
+
+Custom organization-specific attributes::
+These are any additional attributes supported by the base flavor or taste.
 
 The availability of these attributes depends on the base flavor's supported
 document attributes and template system.
@@ -368,6 +518,20 @@ For example, the ISO flavor supports specific presentation metadata attributes.
 Other flavors may have different customization options. Please check the base
 flavor documentation for available attributes.
 
+== Mappings of structures from taste to base flavours
+
+The taste configuration includes various document classifications which need to
+be mapped between values specific to the taste, and corresponding values in the
+base flavor.
+
+The document will actually be compiled with the base flavor settings, but it
+will be rendered using the taste's corresponding values.
+
+These include:
+
+* `doctype`: mapping of taste doctypes to native base flavor doctypes
+* `stage`: mapping of taste stages to native base flavor stages
+
 
 == Data model
 
@@ -414,11 +578,19 @@ content for each taste.
 
 === Workflow
 
-. Discovery: On gem load, `TasteRegister` scans `data/` directory for taste configurations
+. Discovery: On gem load, `TasteRegister` scans `data/` directory for taste
+configurations
+
 . Registration: Each valid taste directory is registered with its configuration
-. Access: Users call `TasteRegister.get(:flavor)` to obtain a configured taste instance
-. Processing: The taste instance applies overrides and customizations to document attributes
-. Integration: The customized attributes are used by Metanorma for document processing
+
+. Access: Users call `TasteRegister.get(:flavor)` to obtain a configured taste
+instance
+
+. Processing: The taste instance applies overrides and customizations to
+document attributes
+
+. Integration: The customized attributes are used by Metanorma for document
+processing
 
 
 [[creating-a-taste]]
@@ -433,10 +605,15 @@ configuration directory with the necessary files.
 
 To create a new taste:
 
-. Create directory: Add a new directory under `data/` with your unique taste code
+. Create directory: Add a new directory under `data/` with your unique taste
+code
+
 . Add configuration: Create `config.yaml` with your taste settings
+
 . Add content: Optionally add `copyright.adoc` and `i18n.yaml` files
-. Test: The taste will be automatically discovered and available via the TasteRegister
+
+. Test: The taste will be automatically discovered and available via the
+TasteRegister
 
 Example for a new `acme` taste:
 

data/data/csa/config.yaml

@@ -2,30 +2,32 @@
 flavor: csa
 owner: Cloud Security Alliance
 base-flavor: generic
-customize: metanorma.yml
-copyright-notice: boilerplate.adoc
-i18n-dictionary: i18n.yaml
-publisher-logo: logo.svg
-htmlcoverpage: html_csa_titlepage.html
-htmlstylesheet: htmlstyle.scss
-htmlintropage: html_csa_intro.html
-wordcoverpage: word_csa_titlepage.html
-standardstylesheet: csa.scss
-wordstylesheet: wordstyle.scss
-wordintropage: word_csa_intro.html
-header: header.html
-pdf-stylesheet: csa.standard.xsl
 base-override:
-  publisher: Cloud Security Alliance
-  publisher_abbr: CSA
-  body-font: Lato,"Source Sans Pro",sans-serif
-  header-font: Lato,"Source Sans Pro",sans-serif
-  monospace-font: '"Source Code Pro",monospace'
-  presentation-metadata-ul-label-list: "•, -, o"
-  presentation_metadata_annex_delim: "<br/>"
-  presentation_metadata_middle_title: ""
-  presentation_metadata_ol_label_template_alphabet_upper: "%<span class='fmt-label-delim'>)</span>"
-  output-extensions: xml,html,pdf,doc
+  filename-attributes:
+    customize: metanorma.yml
+    copyright-notice: boilerplate.adoc
+    i18n-dictionary: i18n.yaml
+    publisher-logo: logo.svg
+    htmlcoverpage: html_csa_titlepage.html
+    htmlstylesheet: htmlstyle.scss
+    htmlintropage: html_csa_intro.html
+    wordcoverpage: word_csa_titlepage.html
+    standardstylesheet: csa.scss
+    wordstylesheet: wordstyle.scss
+    wordintropage: word_csa_intro.html
+    header: header.html
+    pdf-stylesheet: csa.standard.xsl
+  value-attributes:
+    publisher: Cloud Security Alliance
+    publisher_abbr: CSA
+    body-font: Lato,"Source Sans Pro",sans-serif
+    header-font: Lato,"Source Sans Pro",sans-serif
+    monospace-font: '"Source Code Pro",monospace'
+    presentation-metadata-ul-label-list: "&#x2022;, &#x2d;, &#x6f;"
+    presentation_metadata_annex_delim: "<br/>"
+    presentation_metadata_middle_title: ""
+    presentation_metadata_ol_label_template_alphabet_upper: "%<span class='fmt-label-delim'>)</span>"
+    output-extensions: xml,html,pdf,doc
 doctypes:
 - taste: standard
   base: standard