Skip to content

Latest commit

 

History

History
154 lines (98 loc) · 5.09 KB

README.adoc

File metadata and controls

154 lines (98 loc) · 5.09 KB
Raw

ITU Operational Bulletin Website

build_deploy (main) build_deploy (staging)

The website built from this source is available at:

Generates a web-based representation of individual OB issues and message filtering across OB issues.

Building

  • Ensure you have Ruby and Git.

  • Clone the repository & initialize submodules.

  • Run bundle; then bundle exec jekyll build (or serve).

The source data branches are:

Approach

Each ITU OB issue is modelled as a collection of messages. Each section in an OB issue is considered a message.

Authoring

  • The ITU OB editor, currently in early alpha testing mode, will be the authoring tool for ITU Operational Bulletin data.

  • See itu-ob-data for how the data directory should be structured.

OB issues

Place each OB issue under data/issues/{{ OB No. }}/ directory.

Each OB issue should contain the following files:

meta.yaml

Information about OB issue: number, date, authors, etc.

general.yaml

General information from the OB issue. Contains a list of messages.

amendments.yaml

The amendments part from the OB issue. Contains a list of messages.

annexes.yaml

Any annexes to this OB issue.

Referenced service publications (annexed Lists)

Many messages in OB issue amend previous publications.

To avoid repeating publication titles and other metadata, each publication is given an ID.

When a publication is annexed to an OB issue, and whenever it is amended in subsequent issues, its publication ID is referenced.

Place all publications under data/lists/{{ list (publication) ID }}/.

Each publication directory should contain one file:

meta.yaml

Publication metadata, such as title, URL, associated recommendation.

When annexed to an OB issue, all Lists must specify a “position”. Amendments to such Lists should specify the position being amended as well.

(Technically this is redundant, as we can infer the position being amended by finding which position of the List was annexed to OB last, but currently it is used for data consistency check.)

Special cases

Publications that are never annexed, but are amended (“external” Lists V and VIII, NNP dataset), should also be included under data/lists/. For them, amendments are not required to specify position.

Publications that are never amended, but are annexed under section B of Annexed Lists in each OB edition via extra_links array of running_annexes message (e.g., BUREAUFAX, ROA), should also be included under data/lists/.

Documentation for site editors

Documentation for ITU OB authors, and also technically the same as editor app help, is built from the docs Jekyll collection.

Note
 This may be moved to a dedicated website in future.

These pages use docs[_*] layouts, and are styled by docs.scss.

Pages are generated twice, firstly (with default Jekyll behavior) as part of main website, and secondly (with builtin_app_help_generator.rb plugin) to be used as application’s built-in help.

Built-in app help page generation

The generator plugin is configured through in_app_help site-wide config key. It re-uses the documents from specified collection under specified URL prefix, specifying or overriding certain page frontmatter.

Most importantly, it sets the {{ page.in_app_help }} variable.

Site layouts make use of that variable to add a HTML class on <body>, and to turn on/off (mostly off) certain UI elements that do not make sense in context of built-in app help.

The ITU OB editor app loads these pages when user uses the Help menu.

Implementation details

The following plugins enable the site to function.

Issue data reader

Processes OB issue data and populates site.data with structured information about OB issues and changes in telecommunications landscape covered by ITU

Issue page generator

Creates a page for each OB issue using site.data

Message index generator

Generates message index/archive pages

Localizer

implements two template tags:

Template tag {% trans a_string %} allows to translate string variables specified in the form of { <lang1>: <string1>, <lang2>: <string2> }.

Template tag {% trans_file a_filename %} includes file, specified by name relative to current issue root, using language-specific version (<lang>-<a_filename>) if available. It also parses AsciiDoc into HTML, so it does not belong under localizer umbrella per se.