Pathways Paper

Due: September 2021 March 2022 (?)

Tools:

• Format to be AsciiDoc (.adoc)
• AsciiDoc plugin for Visual Studio Code: asciidoctor.asciidoctor-vscode
• Rendering to PDF: see below

Two ways to position the paper:

1. A solution for OpenDRR Pathways - How the platform supports the project.
2. A solution for Open Science - How the platform enables open science from a principled perspective. Demonstrated via an implementation for OpenDRR Pathways. TO BE AN OPENFILE

Title ideas

• OpenDRR Platform, an infrastructure for open science (for risk modelling/hazards)
• Open Science Platform for Disaster Risk Reduction

TOC ideas

• Summary
• Introduction to OpenDRR (mention why opendrr platform was needed/created before Intro to openDRR)
• Platform Requirements
• Architecture
• Lessons learned
• Future development

---

Brainstorming

• Resource requirements
  • Some resource-intensive processes include: OpenQuake, loading CSV into PostgreSQL database using Python (solvable); SSD vs HDD; CPU and RAM requirement, etc.
• Reproducible builds:
  • R5 principles
  • Reproducible Builds — a set of software development practices that create an independently-verifiable path from source to binary code, and see how e.g. Debian and Arch Linux are doing
  • What we are facing:
    • OpenQuake stable release vs. latest development snapshot with slight incompatibilities
    • Python versions related to the above; Python libraries (requirements.txt) and their compatibilities. (affects OpenQuake runs; opendrr-api; Docker image for running Python)
    • underlying OS (Ubuntu 16.04 vs 18.04 vs 20.04); different distros (e.g. CentOS); different Debian versions in Docker image
    • the current need to set up AWS EC2 instances and their environments manually...
      • Potential solution: GeoscienceAustralia/aws-openquake: Python (Boto3) script which installs, runs and downloads results from seismic hazard and risk software (OpenQuake Engine) on Amazon Web Services EC2.
• Concurrent builds
  • Amazon services, EC2...
• Storage strategies (?)
  • Git LFS, Amazon S3, etc.
• Backup strategies
  • Backing up all our GitHub repos to AWS S3?
• Security
  • Protecting GitHub tokens, for example
  • Security protocols/policies compliance within the Government of Canada
• Open Science, Open Data (open/transparent process)
  • How open? Balancing transparency and confidentiality. Accountability.
  • Aggregating raw data to avoid privacy-sensitive data being exposed
  • Potential issues/liabilities of making draft scientific papers available to the public before peer review: to soon, too premature?
• Free-and-open-source software and commercial software
• How can we make our work available for anyone to copy and use for other purposes for the greater good? (feasibility, efforts; documentation, promotion, etc.)

Rendering final output formats

HTML

• Hugo with its AsciiDoc support (with Asciidoctor)? :-)
• Jekyll AsciiDoc Plugin
• Quire and its Community Showcase. Some support for interactive maps based on Hugo. Does Quire support AsciiDoc?

Some examples, with automatic Table of Contents on the side, and with built-in search:

• ReSpec Documentation used by W3C
• DocuAPI theme with Hugo, see demo

PDF

How to convert asciidoc to pdf? - Stack Overflow

1. AsciiDoc → Asciidoctor.js → HTML → wkhtmltopdf → PDF
   (Ctrl+Shift+P, select "AsciiDoc: Export document as PDF", from Visual Studio Code: asciidoctor.asciidoctor-vscode)
2. AsciiDoc → _Asciidoctor PDF → PDF
   (Ctrl+Shift+P, select "AsciiDoc: Export document as PDF", from Visual Studio Code: asciidoctor.asciidoctor-vscode, with setting "Use_asciidoctorpdf" turned on)
3. Asciidoctor PDF (using Prawn)
4. AsciiDoc → Asciidoctor or AsciiDoc → DocBook → DocBook XSL and Apache FOP → PDF
   (asciidoctor/asciidoctor-fopub: A portable DocBook-to-PDF build command that wraps DocBook XSL and Apache FOP)
5. AsciiDoc → Asciidoctor or AsciiDoc → DocBook → dblatex → PDF
6. If Quire works, use its PDF generation method? (with PrinceXML?)

To do: To test and compare.