diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 9ba46cf..3bce1b8 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -11,6 +11,23 @@ on: branches: ["*"] tags: ["v*"] + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: + + +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + contents: write + pages: write + id-token: write + +# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. +# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. +concurrency: + group: "pages" + cancel-in-progress: false + + jobs: build: # The type of runner that the job will run on @@ -46,6 +63,11 @@ jobs: name: Build-Logs path: logs + - name: Upload artifact + uses: actions/upload-pages-artifact@v2 + with: + path: ./output + # The release only triggers when the thing that was pushed was a tag starting with 'v' release: needs: build @@ -102,3 +124,15 @@ jobs: asset_path: PRMinXML-Staging/index.pdf asset_name: PRMinXML-Staging-${{ steps.get_version.outputs.VERSION }}.pdf asset_content_type: application/pdf + + publish: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + if: startsWith(github.ref, 'refs/tags/v') + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v2 diff --git a/Makefile b/Makefile index 0919a06..07dd524 100644 --- a/Makefile +++ b/Makefile @@ -4,20 +4,22 @@ TOOL = riscos-prminxml +LOGDIR=logs + all: pdf lint: dirs - ${TOOL} --lint -f index -L logs index.xml - cat logs/2-build.log + ${TOOL} --lint -f index -L ${LOGDIR} index.xml + cat ${LOGDIR}/2-build.log output: dirs - ${TOOL} -f index -L logs index.xml - cat logs/2-build.log + ${TOOL} -f index -L ${LOGDIR} index.xml + cat ${LOGDIR}/2-build.log pdf: output ifeq (${PRINCEXML_I_HAVE_A_LICENSE},1) if [ -f output/html/filelist.txt ] ; then \ - cd output/html && prince --verbose -o ../index.pdf -l filelist.txt ; \ + cd output/html && prince --verbose -o ../RISC_OS_Staging_Documents.pdf -l filelist.txt ; \ else \ echo NOTE: riscos-prminxml tool is too old to generate PDF. ; \ fi @@ -26,9 +28,9 @@ else endif dirs: - mkdir -p logs + mkdir -p ${LOGDIR} zip: output rm -f src.zip output.zip - zip -9r src.zip index.html Makefile src + zip -9r src.zip index.xml build.sh Makefile src zip -9r output.zip output diff --git a/build-style.sh b/build-style.sh new file mode 100755 index 0000000..a39fec6 --- /dev/null +++ b/build-style.sh @@ -0,0 +1,75 @@ +#!/bin/bash +## +# Helper script to build a given style of document (or multiple styles) + +set -e +set -o pipefail + +scriptdir="$(cd "$(dirname "$0")" && pwd -P)" + +OUTPUTDIR="output" +rm -rf "${OUTPUTDIR}" +mkdir -p "${OUTPUTDIR}" + +TMPINDEX="${TMPDIR:-/tmp}/prminxml-index.xml" + +# Common extra variants +extra_variants="large-bullets page-a4" +index_variants="no-edge-index index-no-descriptions-in-print index-include-indexed-header-label" + +# Construct a new index.xml for us to use. +function generate_documents() { + local srcindex=$1 + local name=$2 + local variants=$3 + local html=${4:-html5} + local catalog=${5:-103} + echo "- Building documents in ${OUTPUTDIR}/$name" + + sed -E \ + -e "s!output/!${OUTPUTDIR}/$name/!g" \ + -e "s!page-css-variant='[^']*'!page-css-variant='$variants'!g" \ + -e "s!index-css-variant='[^']*'!index-css-variant='$variants $index_variants'!g" \ + -e "s!page-format='.*'!page-format='$html'!" \ + "$srcindex" > "${TMPINDEX}" + + mkdir -p "${OUTPUTDIR}/logs-$name" + riscos-prminxml --catalog "$catalog" -f index -L "${OUTPUTDIR}/logs-$name" "${TMPINDEX}" + if [[ "$PRINCEXML_I_HAVE_A_LICENSE" = 1 && -f "${OUTPUTDIR}/$name/html/filelist.txt" ]] ; then + ( cd "${OUTPUTDIR}/$name/html" && + prince --verbose -o "../RISC_OS_PRM_Staging.pdf" -l filelist.txt ) + fi + cp "${TMPINDEX}" "${OUTPUTDIR}/$name/index.xml" +} + +# Build each of the requested formats +# Arguably we shouldn't really /have/ to regenerate all the documentation just to replace the +# CSS. But that's the way they've been set up. A bit of a rethink of the CSS generation would +# be needed to make it more flexible... but that's for another day. +for arg in "$@" ; do + handled=false + if [[ "$arg" = 'all' || "$arg" = 'regular' ]] ; then + generate_documents "index.xml" regular "$extra_variants" + handled=true + fi + if [[ "$arg" = 'all' || "$arg" = 'unstyled' ]] ; then + generate_documents "index.xml" unstyled "$extra_variants" "html" + handled=true + fi + if [[ "$arg" = 'all' || "$arg" = 'prm' ]] ; then + generate_documents "index.xml" prm "prm body-fraunces heading-raleway webfont-fraunces webfont-raleway $extra_variants" + handled=true + fi + if [[ "$arg" = 'all' || "$arg" = 'prm-ro2' ]] ; then + generate_documents "index.xml" prm-ro2 "prm prm-ro2 body-fraunces heading-raleway webfont-fraunces webfont-raleway $extra_variants" + handled=true + fi + if [[ "$arg" = 'all' || "$arg" = 'prm-modern' ]] ; then + generate_documents "index.xml" prm-modern "prm prm-modern body-notosans heading-saira webfont-notosans webfont-saira $extra_variants" + handled=true + fi + if ! $handled ; then + echo "Did not understand build style '$arg'" >&2 + exit 1 + fi +done diff --git a/build.sh b/build.sh index 5f9c5e0..438053c 100755 --- a/build.sh +++ b/build.sh @@ -1,9 +1,10 @@ #!/bin/bash ## -# Build the index, obtaining the tools first. +# Build the documentation, obtaining the tools first. # # We will obtain all the tools we need from the OS. -# We will try to get a version of PRM-in-XML that we can work with. +# We will try to get a version of PRM-in-XML that we can work with (or use +# the local version). # We will obtain PrinceXML to generate PDFs. # # Because PrinceXML requires that you have a license to use it, @@ -18,20 +19,43 @@ # # Consult the PrinceXML documentation for license details. # +# To override the version of PRM-in-XML which is used, set the environment +# variable PRMINXML_VERSION to either 'local' or a version number from the +# PRM-in-XML distribution: +# +# Parameters may be given to request a specific style be used - there are a +# number of styles in the `build-style.sh` script, for example: +# +# ./build.sh prm-modern +# +# Currently defined styles are: +# +# regular +# unstyled +# prm +# prm-ro2 +# prm-modern +# +# To build all styles, use: +# +# ./build.sh all +# # Supported operating systems: # # macOS -# Ubuntu Linux (18.04-21.04) +# Ubuntu Linux (18.04, 20.04, 22.04) # Centos (7 and 8) # Debian (10) +# Linux Mint (18 and 20) # set -e set -o pipefail -PRINCE_VERSION=14.4 -#PRMINXML_VERSION=1.02.65 -PRMINXML_VERSION=1.03.65.html5-css.176 +PRINCE_VERSION=15.1 +#DEFAULT_PRMINXML_VERSION=1.02.65 +DEFAULT_PRMINXML_VERSION=1.03.343 +PRMINXML_VERSION=${PRMINXML_VERSION:-$DEFAULT_PRMINXML_VERSION} SYSTEM="$(uname -s)" if [[ "$SYSTEM" = 'Darwin' ]] ; then @@ -156,14 +180,19 @@ function install_package() { install_package wget install_package perl -install_package git install_package xsltproc install_package xmllint libxml2-utils install_package make -if ! type -p riscos-prminxml >/dev/null 2>&1 ; then +if [[ "$PRMINXML_VERSION" == 'local' ]] ; then + echo +++ Using local version of riscos-prminxml + if ! type -p riscos-prminxml >/dev/null 2>&1 ; then + echo "No 'riscos-prminxml' tool is available." >&2 + exit 1 + fi +else # riscos-prminxml isn't installed, so let's get a copy. if [[ ! -x "./riscos-prminxml-$PRMINXML_VERSION/riscos-prminxml" ]] ; then echo +++ Obtaining riscos-prminxml @@ -189,21 +218,32 @@ if ! type -p prince >/dev/null 2>&1 && [[ "$PRINCEXML_I_HAVE_A_LICENSE" = 1 ]] ; elif [[ "$SYSTEM" = 'Linux' ]] ; then # I'm assuming this is amd64. PRINCE_DISTRO_RELEASE=${DISTRO_RELEASE} - if [[ "$DISTRO" = 'ubuntu' ]] ; then - if [[ "$DISTRO_RELEASE" =~ 20.10|21.04|21.10 ]] ; then + PRINCE_DISTRO=${DISTRO} + if [[ "${PRINCE_DISTRO}" = 'linuxmint' ]] ; then + PRINCE_DISTRO=linux-generic + PRINCE_DISTRO_RELEASE="" + PRINCE_ARCH='x86_64' + elif [[ "${PRINCE_DISTRO}" = 'ubuntu' ]] ; then + if [[ "$DISTRO_RELEASE" =~ 22.10 ]] ; then + PRINCE_DISTRO_RELEASE=22.04 + elif [[ "$DISTRO_RELEASE" =~ 20.10|21.04|21.10 ]] ; then PRINCE_DISTRO_RELEASE=20.04 elif [[ "$DISTRO_RELEASE" =~ 18.10|19.04|19.10 ]] ; then PRINCE_DISTRO_RELEASE=18.04 fi # FIXME: Determine the actual architecture PRINCE_ARCH='amd64' - elif [[ "$DISTRO" = 'debian' ]] ; then + elif [[ "$PRINCE_DISTRO" = 'debian' ]] ; then PRINCE_ARCH='amd64' - elif [[ "$DISTRO" = 'centos' ]] ; then + elif [[ "$PRINCE_DISTRO" = 'centos' ]] ; then PRINCE_ARCH='x86_64' + if [[ "$DISTRO_RELEASE" == 8 ]] ; then + # CentOS 8 is old and Prince wasn't updated beyond 14.2 + PRINCE_VERSION=14.2 + fi fi - url="https://www.princexml.com/download/prince-$PRINCE_VERSION-${DISTRO}${PRINCE_DISTRO_RELEASE}-${PRINCE_ARCH}.tar.gz" - extract_dir="prince-${PRINCE_VERSION}-${DISTRO}${PRINCE_DISTRO_RELEASE}-${PRINCE_ARCH}" + url="https://www.princexml.com/download/prince-$PRINCE_VERSION-${PRINCE_DISTRO}${PRINCE_DISTRO_RELEASE}-${PRINCE_ARCH}.tar.gz" + extract_dir="prince-${PRINCE_VERSION}-${PRINCE_DISTRO}${PRINCE_DISTRO_RELEASE}-${PRINCE_ARCH}" ext="tar.gz" else echo "Unrecognised OS" >&2 @@ -246,6 +286,18 @@ if ! type -p prince >/dev/null 2>&1 && [[ "$PRINCEXML_I_HAVE_A_LICENSE" = 1 ]] ; install_package liblcms2-2 install_package libcurl4 install_package libfontconfig1 + + # Version 15 requires some other libraries as well + if [[ "${PRINCE_VERSION%.*}" -ge "15" ]] ; then + if [[ "${DISTRO}" != 'centos' || "$DISTRO_RELEASE" != 7 ]] ; then + install_package libwebpdemux2 + fi + if [[ "${DISTRO}" = 'ubuntu' ]] ; then + if [[ "$DISTRO_RELEASE" =~ 22 ]] ; then + install_package libavif13 + fi + fi + fi fi fi fi @@ -265,4 +317,26 @@ fi echo Run the build... -make +build="${1:-}" +if [[ "$#" != 0 ]] ; then + shift +fi +and_zip=false +if [[ "$build" == '' ]] ; then + build=regular + +elif [[ "$build" == 'zip' ]] ; then + + build=all + and_zip=true +fi + +if [[ "$build" == 'lint' ]] ; then + make lint +else + ./build-style.sh "$build" "$@" + ./index-generator.pl output/index.html output +fi +if $and_zip ; then + make zip +fi diff --git a/index-generator.pl b/index-generator.pl new file mode 100755 index 0000000..61ae2ee --- /dev/null +++ b/index-generator.pl @@ -0,0 +1,69 @@ +#!/usr/bin/perl +## +# Generate a simple index for the PRMinXML staging repository. +# We're linking to each of the different styles of the documents. +# + +use warnings; +use strict; + +my $output = shift; +my $outputdir = shift; + +# We need to determine the styles we can use +opendir(my $dh, $outputdir); +my @styles = grep { -f "$outputdir/$_/html/index.html" } readdir($dh); + +my %style_names = ( + 'prm-modern' => 'Modern style', + 'prm' => 'RISC OS 3 PRM style', + 'prm-ro2' => 'RISC OS 2 PRM style', + 'regular' => 'Simple style for browsers', + 'unstyled' => 'Unstyled (no CSS)', + ); +my %style_weights = ( + 'prm-modern' => 0, + 'prm' => 1, + 'prm-ro2' => 2, + 'regular' => 3, + 'unstyled' => 4, + ); + + +sub read_file { + my ($file) = @_; + open(my $fh, '<', $file) || die "Cannot read '$file': $!\n"; + my $content = ''; + while (<$fh>) { + $content .= $_; + } + close($fh); + return $content; +} + + +my $head = read_file('index-head.html'); +my $tail = read_file('index-tail.html'); + +my @rows; +for my $style (sort { ($style_weights{$a} // 10) <=> ($style_weights{$b}) } @styles) { + my $title = $style_names{$style} // "(UNTITLED: $style)"; + my $pdffile = "$style/RISC_OS_PRM_Staging.pdf"; + + my $row = "
  • "; + $row .= "$title"; + if (-f "$outputdir/$pdffile") { + $row .= " (PDF)"; + } + $row .= "
    • "; + push @rows, "$row\n"; +} + +open(my $fh, '>', $output) || die "Cannot write output '$output': $!\n"; +print $fh $head; +for my $row (@rows) +{ + print $fh $row; +} +print $fh $tail; +close($fh); diff --git a/index-head.html b/index-head.html new file mode 100644 index 0000000..b847d05 --- /dev/null +++ b/index-head.html @@ -0,0 +1,1666 @@ + +PRM-in-XML staging documents + + + +

    PRM-in-XML staging documents

    +

    Introduction

    +

    + The PRM-in-XML project is an initiative to make a standardised documentation + format for the RISC OS Programmer's Reference Manuals. The tooling for + generating such documentation can be found in the + riscos-prminxml-tool + GitHub repository. Additional justification and details about the project itself + can be found in an article about the project published in + The Iconbar. +

    +

    + The documents published here are staged documents which are in the process of + being edited. The staged documents either do not have a home, or have not + been edited to an acceptable standard. The source content for the documents + can be found in the XML documents in the repository. + The full repository can be found in the + riscos-prminxml-staging + repository on GitHub. +

    + +

    + The documentation is generated in different styles to show off the different + presentation formats, and provide users with a choice of how they wish to see + their documents. +

    +
    + + +
    + + +