From 9d0be0ad138bb0b2a58a2b15f1aff80c1ddb6777 Mon Sep 17 00:00:00 2001 From: Charles Ferguson Date: Sun, 3 Sep 2023 23:09:37 +0100 Subject: [PATCH] Update the build with latest version and an index ready for GitHub pages. The build system has been updated with features from the main PRM-in-XML repository and the examples repository. This means that we now have an index available which should be able to show you each of the document styles, and we should be able to publish to the GitHub pages shortly. --- .github/workflows/ci.yml | 38 +- Makefile | 16 +- build-style.sh | 75 ++ build.sh | 104 ++- index-generator.pl | 69 ++ index-head.html | 1666 ++++++++++++++++++++++++++++++++++++++ index-tail.html | 10 + 7 files changed, 1954 insertions(+), 24 deletions(-) create mode 100755 build-style.sh create mode 100755 index-generator.pl create mode 100644 index-head.html create mode 100644 index-tail.html diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 9ba46cf..b44d5ce 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 @@ -34,7 +51,7 @@ jobs: # # These criteria are met by the builds we're creating here, and so we can # use the non-commercial license. - sudo env PRINCEXML_I_HAVE_A_LICENSE=1 ./build.sh + sudo env PRINCEXML_I_HAVE_A_LICENSE=1 ./build.sh all - uses: actions/upload-artifact@v2 with: @@ -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 @@ -99,6 +121,18 @@ jobs: # This pulls from the CREATE RELEASE step above, referencing it's ID to get its outputs object, which include a `upload_url`. # See this blog post for more info: https://jasonet.co/posts/new-features-of-github-actions/#passing-data-to-future-steps upload_url: ${{ steps.create_release.outputs.upload_url }} - asset_path: PRMinXML-Staging/index.pdf + asset_path: PRMinXML-Staging/prm/RISCOS_PRM_Staging.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. +

    +
    + + +
    + + +