From 1879ce3ce5fdc8b401f603651a46d76924f47c70 Mon Sep 17 00:00:00 2001 From: Claudio Bantaloukas Date: Mon, 30 Mar 2026 13:29:15 +0000 Subject: [PATCH 1/7] Update build-github-pages CI - use the curent pages-gem container rather than rebuilding it both in CI and in the build script - update actions/checkout --- .github/workflows/ci.yml | 18 ++++++++++++++++-- tools/build-github-pages.sh | 6 +----- 2 files changed, 17 insertions(+), 7 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index a784ef39..5139f316 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -20,10 +20,24 @@ jobs: build-github-pages: runs-on: ubuntu-latest + container: + image: ghcr.io/github/pages-gem:latest steps: - - uses: actions/checkout@v4.1.7 + - uses: actions/checkout@v6.0.2 - name: generate the GitHub Pages locally in order to check for errors - run: ./tools/build-github-pages.sh build + run: | + echo -e "plugins:\n \ + - jekyll-coffeescript\n \ + - jekyll-default-layout\n \ + - jekyll-gist\n \ + - jekyll-github-metadata\n \ + - jekyll-optional-front-matter\n \ + - jekyll-paginate\n \ + - jekyll-readme-index\n \ + - jekyll-titles-from-headings\n \ + - jekyll-relative-links\n" >> _config.yml + SITE=. + jekyll build markdown-link-check: runs-on: ubuntu-latest diff --git a/tools/build-github-pages.sh b/tools/build-github-pages.sh index c2800283..4f42c043 100755 --- a/tools/build-github-pages.sh +++ b/tools/build-github-pages.sh @@ -33,10 +33,6 @@ set -x ROOTDIR=$(realpath "$(dirname "$(realpath "$0")")/..") TEMPDIR=$(mktemp -d) -cd $TEMPDIR -git clone --depth 1 https://github.com/github/pages-gem.git -cd pages-gem -docker build -t gh-pages --build-arg RUBY_VERSION=3.2 . cd $ROOTDIR echo -e "plugins:\n \ - jekyll-coffeescript\n \ @@ -52,7 +48,7 @@ cd $TEMPDIR/pages-gem if [ "$1" == "build" ]; then SITE=$ROOTDIR - docker run --rm -p 4000:4000 -v `realpath ${SITE}`:/src/site gh-pages jekyll build + docker run --rm -p 4000:4000 -v `realpath ${SITE}`:/src/site ghcr.io/github/pages-gem:latest jekyll build elif [ "$1" == "serve" ]; then SITE=$ROOTDIR make server fi From 35b78cf90503ce0f22c6d4762b2dbe40fb86f0d9 Mon Sep 17 00:00:00 2001 From: Claudio Bantaloukas Date: Mon, 30 Mar 2026 13:29:15 +0000 Subject: [PATCH 2/7] Use simple string replacement rather than python templating. This makes it easier for multiple parsers that treat markdown and jekyll to do syntax checks. --- mve_intrinsics/mve.template.md | 8 ++++---- neon_intrinsics/advsimd.template.md | 8 ++++---- tools/gen-intrinsics-specs.py | 3 ++- 3 files changed, 10 insertions(+), 9 deletions(-) diff --git a/mve_intrinsics/mve.template.md b/mve_intrinsics/mve.template.md index 92f4575e..f5ecd0ad 100644 --- a/mve_intrinsics/mve.template.md +++ b/mve_intrinsics/mve.template.md @@ -4,7 +4,7 @@ version: 2021Q4 date-of-issue: 11 January 2022 # LaTeX specific variables landscape: true -copyright-text: Copyright 2019-2022 Arm Limited and/or its affiliates . +copyright-text: Copyright 2019-2026 Arm Limited and/or its affiliates . draftversion: true # Jekyll specific variables header_counter: true @@ -12,7 +12,7 @@ toc: true --- @@ -24,7 +24,7 @@ to generate the Table of Contents via Jekyll. They are automatically removed by the scripts that generate the pdfs. --> * TOC -{{:toc}} +{:toc} # Preface ## Abstract @@ -137,4 +137,4 @@ It is automatically removed by the scripts that generate the pdfs. # List of Intrinsics -{intrinsic_table} +REPLACE_INTRINSIC_TABLE_HERE diff --git a/neon_intrinsics/advsimd.template.md b/neon_intrinsics/advsimd.template.md index 336378db..d25b5fbd 100644 --- a/neon_intrinsics/advsimd.template.md +++ b/neon_intrinsics/advsimd.template.md @@ -4,7 +4,7 @@ version: 2025Q2 date-of-issue: 06 June 2025 # LaTeX specific variables landscape: true -copyright-text: "Copyright: see section \\texorpdfstring{{\\nameref{{copyright}}}}{{Copyright}}." +copyright-text: "Copyright: see section \\texorpdfstring{\\nameref{copyright}}{Copyright}." draftversion: true # Jekyll specific variables header_counter: true @@ -12,7 +12,7 @@ toc: true --- * TOC -{{:toc}} +{:toc} # Preface ## Abstract @@ -179,4 +179,4 @@ It is automatically removed by the scripts that generate the pdfs. # List of Intrinsics -{intrinsic_table} +REPLACE_INTRINSIC_TABLE_HERE diff --git a/tools/gen-intrinsics-specs.py b/tools/gen-intrinsics-specs.py index 3997b98c..549912b4 100755 --- a/tools/gen-intrinsics-specs.py +++ b/tools/gen-intrinsics-specs.py @@ -964,7 +964,8 @@ def get_intrinsics_db(path): intrinsics_db = get_intrinsics_db(cli_args.intrinsic_defs) doc_template = read_template(cli_args.template) intrinsic_table = process_db(intrinsics_db, classification_map, cli_args.workflow) - md_output = doc_template.format(intrinsic_table=intrinsic_table) + assert "REPLACE_INTRINSIC_TABLE_HERE" in doc_template, "The template file should contain the placeholder 'REPLACE_INTRINSIC_TABLE_HERE' for the intrinsic table." + md_output = doc_template.replace("REPLACE_INTRINSIC_TABLE_HERE", intrinsic_table) with (open(cli_args.outfile, 'w')) as f: f.write(md_output) # Always run the unit tests. From b45c2d3e5385032533bb12bcac3238b501486726 Mon Sep 17 00:00:00 2001 From: Claudio Bantaloukas Date: Mon, 30 Mar 2026 13:29:15 +0000 Subject: [PATCH 3/7] Allow compatibility with tabulate versions >= 0.10 --- tools/gen-intrinsics-specs.py | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/tools/gen-intrinsics-specs.py b/tools/gen-intrinsics-specs.py index 549912b4..26f04065 100755 --- a/tools/gen-intrinsics-specs.py +++ b/tools/gen-intrinsics-specs.py @@ -1,6 +1,6 @@ #!/usr/bin/env python3 -# SPDX-FileCopyrightText: Copyright 2021, 2023 Arm Limited and/or its affiliates +# SPDX-FileCopyrightText: Copyright 2021-2026 Arm Limited and/or its affiliates # SPDX-License-Identifier: Apache-2.0 # # Licensed under the Apache License, Version 2.0 (the "License"); @@ -20,6 +20,7 @@ import argparse import csv import doctest +import re from urllib.parse import urljoin from urllib.parse import quote @@ -50,6 +51,13 @@ def quote_literal(val, workflow): __ARMDEVELOPER = "https://developer.arm.com/architectures/instruction-sets/intrinsics/" +def parse_numeric_version(version): + match = re.match(r"(\d+)\.(\d+)\.(\d+)", version) + if not match: + raise ValueError(f"Unsupported version format: {version}") + return tuple(int(part) for part in match.groups()) + + def md_literal_quote(mapping, workflow): r""" >>> md_literal_quote('a; b', 'markdown') @@ -955,9 +963,17 @@ def get_intrinsics_db(path): # We require version 0.8.6 to be able to print multi-line records # in tables. - if tbl.__version__ < "0.8.6": + required_tabulate_version = "0.8.6" + try: + installed_tabulate_version = parse_numeric_version(tbl.__version__) + except ValueError: + print(f"Unable to parse installed tabulate version ({tbl.__version__}).", + file=sys.stderr) + exit(1) + + if installed_tabulate_version < parse_numeric_version(required_tabulate_version): print(f"Your version of package tabulate is too old ({tbl.__version__}). " - "Update it to be greater or equal to 0.8.6.", file=sys.stderr) + f"Update it to be greater or equal to {required_tabulate_version}.", file=sys.stderr) exit(1) classification_map = get_classification_map(cli_args.classification) From 53ae1fc4c84d14ba222b345b8f1e49fc60980aec Mon Sep 17 00:00:00 2001 From: Claudio Bantaloukas Date: Mon, 30 Mar 2026 13:29:15 +0000 Subject: [PATCH 4/7] Fix link checking - update action to currently maintained version - consider 429 (rate limiting) and 403 (forbidden) as success since sites like developer.arm.com sometimes block the action. --- .github/workflows/ci.yml | 4 ++-- .github/workflows/markdown-link-check.json | 3 ++- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 5139f316..77a55774 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -42,8 +42,8 @@ jobs: markdown-link-check: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4.1.7 - - uses: gaurav-nelson/github-action-markdown-link-check@v1 + - uses: actions/checkout@v6.0.2 + - uses: tcort/github-action-markdown-link-check@v1 with: config-file: '.github/workflows/markdown-link-check.json' diff --git a/.github/workflows/markdown-link-check.json b/.github/workflows/markdown-link-check.json index f28711c4..58593618 100644 --- a/.github/workflows/markdown-link-check.json +++ b/.github/workflows/markdown-link-check.json @@ -3,5 +3,6 @@ { "pattern": "^https://developer.arm.com/architectures/instruction-sets/intrinsics/" } - ] + ], + "aliveStatusCodes": [200, 206, 403, 429] } From b74f3ed6ad7aaa61753de20c2dff6894fc9912da Mon Sep 17 00:00:00 2001 From: Claudio Bantaloukas Date: Mon, 30 Mar 2026 13:29:15 +0000 Subject: [PATCH 5/7] Update pdf building to ubuntu 24.04 The change of pandoc version requires an update to the template used in building the PDFs. This template is based on the upstream default.latex template. --- .github/workflows/ci.yml | 36 +- tools/acle_template.tex | 763 ++++++++++++++++++++++++++++++--------- tools/docker/Dockerfile | 6 +- tools/generate-pdfs.sh | 8 +- tools/hyperref-check.sh | 8 +- 5 files changed, 631 insertions(+), 190 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 77a55774..94118275 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -6,14 +6,40 @@ name: CI on: [push, pull_request] jobs: - build: + build-pdfs: runs-on: ubuntu-latest - + container: + image: docker.io/library/ubuntu:24.04 steps: - - uses: actions/checkout@v4.1.7 + - uses: actions/checkout@v6.0.2 - name: check the correctness of the sources and generate the PDFs - run: ./build_with_docker.sh - - uses: actions/upload-artifact@v4.4.0 + run: | + # This is equivalent to the Dockerfile in tools/docker + apt-get update \ + && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \ + texlive-latex-base \ + texlive-fonts-recommended \ + texlive-fonts-extra \ + texlive-latex-extra \ + lmodern \ + pandoc \ + inkscape \ + python3 \ + python3-tabulate \ + librsvg2-bin \ + nodejs + + # this is equivalent to the entrypoint of the Dockerfile in tools/docker + + # Check that the internal links in the markdown files are correct + ./tools/hyperref-check.sh || exit 1 + + # Recreate the full markdown files from the templates and check that the saved ones are consistent. + ./tools/generate-intrinsics-specs.sh || exit 1 + + ./tools/generate-pdfs.sh || exit 1 + + - uses: actions/upload-artifact@v7 with: name: pdfs path: pdfs diff --git a/tools/acle_template.tex b/tools/acle_template.tex index 24e3779a..fa1d2531 100644 --- a/tools/acle_template.tex +++ b/tools/acle_template.tex @@ -1,205 +1,612 @@ -% Copyright (c) 2014--2021, John MacFarlane -% SPDX-FileCopyrightText: Copyright 2021-2022 Arm Limited and/or its affiliates +% Copyright (c) 2014--2023, John MacFarlane +% SPDX-FileCopyrightText: Copyright 2021-2026 Arm Limited and/or its affiliates % SPDX-License-Identifier: BSD-3-Clause % Based on default.latex template released with Pandoc (www.pandoc.org). % See `data/templates` in `COPYRIGHT` at https://github.com/jgm/pandoc +% Options for packages loaded elsewhere +\PassOptionsToPackage{unicode$for(hyperrefoptions)$,$hyperrefoptions$$endfor$}{hyperref} +\PassOptionsToPackage{hyphens}{url} +$if(colorlinks)$ +\PassOptionsToPackage{dvipsnames,svgnames,x11names}{xcolor} +$endif$ +% \documentclass[a4,10pt]{report} + +$if(beamer)$ +$if(background-image)$ +\usebackgroundtemplate{% + \includegraphics[width=\paperwidth]{$background-image$}% +} +% In beamer background-image does not work well when other images are used, so this is the workaround +\pgfdeclareimage[width=\paperwidth,height=\paperheight]{background}{$background-image$} +\usebackgroundtemplate{\pgfuseimage{background}} +$endif$ +\usepackage{pgfpages} +\setbeamertemplate{caption}[numbered] +\setbeamertemplate{caption label separator}{: } +\setbeamercolor{caption name}{fg=normal text.fg} +\beamertemplatenavigationsymbols$if(navigation)$$navigation$$else$empty$endif$ +$for(beameroption)$ +\setbeameroption{$beameroption$} +$endfor$ +% Prevent slide breaks in the middle of a paragraph +\widowpenalties 1 10000 +\raggedbottom +$if(section-titles)$ +\setbeamertemplate{part page}{ + \centering + \begin{beamercolorbox}[sep=16pt,center]{part title} + \usebeamerfont{part title}\insertpart\par + \end{beamercolorbox} +} +\setbeamertemplate{section page}{ + \centering + \begin{beamercolorbox}[sep=12pt,center]{part title} + \usebeamerfont{section title}\insertsection\par + \end{beamercolorbox} +} +\setbeamertemplate{subsection page}{ + \centering + \begin{beamercolorbox}[sep=8pt,center]{part title} + \usebeamerfont{subsection title}\insertsubsection\par + \end{beamercolorbox} +} +\AtBeginPart{ + \frame{\partpage} +} +\AtBeginSection{ + \ifbibliography + \else + \frame{\sectionpage} + \fi +} +\AtBeginSubsection{ + \frame{\subsectionpage} +} +$endif$ +$endif$ +$if(beamerarticle)$ +\usepackage{beamerarticle} % needs to be loaded first +$endif$ +\usepackage{amsmath,amssymb} +$if(linestretch)$ +\usepackage{setspace} +$endif$ +\usepackage{iftex} \usepackage[T1]{fontenc} +\usepackage[utf8]{inputenc} +\usepackage{textcomp} % provide euro and other symbols + +$if(fontfamily)$ +$else$ +$-- Set default font before Beamer theme so the theme can override it +\usepackage{lmodern} +$endif$ +$-- Set Beamer theme before user font settings so they can override theme +$if(beamer)$ +$if(theme)$ +\usetheme[$for(themeoptions)$$themeoptions$$sep$,$endfor$]{$theme$} +$endif$ +$if(colortheme)$ +\usecolortheme{$colortheme$} +$endif$ +$if(fonttheme)$ +\usefonttheme{$fonttheme$} +$endif$ +$if(mainfont)$ +\usefonttheme{serif} % use mainfont rather than sansfont for slide text +$endif$ +$if(innertheme)$ +\useinnertheme{$innertheme$} +$endif$ +$if(outertheme)$ +\useoutertheme{$outertheme$} +$endif$ +$endif$ +$-- User font settings (must come after default font and Beamer theme) +$if(fontfamily)$ +\usepackage[$for(fontfamilyoptions)$$fontfamilyoptions$$sep$,$endfor$]{$fontfamily$} +$endif$ +\ifPDFTeX\else + % xetex/luatex font selection +$if(mainfont)$ + $if(mainfontfallback)$ + \ifLuaTeX + \usepackage{luaotfload} + \directlua{luaotfload.add_fallback("mainfontfallback",{ + $for(mainfontfallback)$"$mainfontfallback$"$sep$,$endfor$ + })} + \fi + $endif$ + \setmainfont[$for(mainfontoptions)$$mainfontoptions$$sep$,$endfor$$if(mainfontfallback)$,RawFeature={fallback=mainfontfallback}$endif$]{$mainfont$} +$endif$ +$if(sansfont)$ + $if(sansfontfallback)$ + \ifLuaTeX + \usepackage{luaotfload} + \directlua{luaotfload.add_fallback("sansfontfallback",{ + $for(sansfontfallback)$"$sansfontfallback$"$sep$,$endfor$ + })} + \fi + $endif$ + \setsansfont[$for(sansfontoptions)$$sansfontoptions$$sep$,$endfor$$if(sansfontfallback)$,RawFeature={fallback=sansfontfallback}$endif$]{$sansfont$} +$endif$ +$if(monofont)$ + $if(monofontfallback)$ + \ifLuaTeX + \usepackage{luaotfload} + \directlua{luaotfload.add_fallback("monofontfallback",{ + $for(monofontfallback)$"$monofontfallback$"$sep$,$endfor$ + })} + \fi + $endif$ + \setmonofont[$for(monofontoptions)$$monofontoptions$$sep$,$endfor$$if(monofontfallback)$,RawFeature={fallback=monofontfallback}$endif$]{$monofont$} +$endif$ +$for(fontfamilies)$ + \newfontfamily{$fontfamilies.name$}[$for(fontfamilies.options)$$fontfamilies.options$$sep$,$endfor$]{$fontfamilies.font$} +$endfor$ +$if(mathfont)$ +$if(mathspec)$ + \ifXeTeX + \setmathfont(Digits,Latin,Greek)[$for(mathfontoptions)$$mathfontoptions$$sep$,$endfor$]{$mathfont$} + \else + \setmathfont[$for(mathfontoptions)$$mathfontoptions$$sep$,$endfor$]{$mathfont$} + \fi +$else$ + \setmathfont[$for(mathfontoptions)$$mathfontoptions$$sep$,$endfor$]{$mathfont$} +$endif$ +$endif$ +$if(CJKmainfont)$ + \ifXeTeX + \usepackage{xeCJK} + \setCJKmainfont[$for(CJKoptions)$$CJKoptions$$sep$,$endfor$]{$CJKmainfont$} + $if(CJKsansfont)$ + \setCJKsansfont[$for(CJKoptions)$$CJKoptions$$sep$,$endfor$]{$CJKsansfont$} + $endif$ + $if(CJKmonofont)$ + \setCJKmonofont[$for(CJKoptions)$$CJKoptions$$sep$,$endfor$]{$CJKmonofont$} + $endif$ + \fi +$endif$ +$if(luatexjapresetoptions)$ + \ifLuaTeX + \usepackage[$for(luatexjapresetoptions)$$luatexjapresetoptions$$sep$,$endfor$]{luatexja-preset} + \fi +$endif$ +$if(CJKmainfont)$ + \ifLuaTeX + \usepackage[$for(luatexjafontspecoptions)$$luatexjafontspecoptions$$sep$,$endfor$]{luatexja-fontspec} + \setmainjfont[$for(CJKoptions)$$CJKoptions$$sep$,$endfor$]{$CJKmainfont$} + \fi +$endif$ +\fi +$if(zero-width-non-joiner)$ +%% Support for zero-width non-joiner characters. +\makeatletter +\def\zerowidthnonjoiner{% + % Prevent ligatures and adjust kerning, but still support hyphenating. + \texorpdfstring{% + \TextOrMath{\nobreak\discretionary{-}{}{\kern.03em}% + \ifvmode\else\nobreak\hskip\z@skip\fi}{}% + }{}% +} +\makeatother +\ifPDFTeX + \DeclareUnicodeCharacter{200C}{\zerowidthnonjoiner} +\else + \catcode`^^^^200c=\active + \protected\def ^^^^200c{\zerowidthnonjoiner} +\fi +%% End of ZWNJ support +$endif$ +% Use upquote if available, for straight quotes in verbatim environments +\IfFileExists{upquote.sty}{\usepackage{upquote}}{} +\IfFileExists{microtype.sty}{% use microtype if available + \usepackage[$for(microtypeoptions)$$microtypeoptions$$sep$,$endfor$]{microtype} + \UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts +}{} +$if(indent)$ +$else$ +\makeatletter +\@ifundefined{KOMAClassName}{% if non-KOMA class + \IfFileExists{parskip.sty}{% + \usepackage{parskip} + }{% else + \setlength{\parindent}{0pt} + \setlength{\parskip}{6pt plus 2pt minus 1pt}} +}{% if KOMA class + \KOMAoptions{parskip=half}} +\makeatother +$endif$ +$if(verbatim-in-note)$ +\usepackage{fancyvrb} +$endif$ \usepackage{xcolor} -\usepackage{sectsty} -\usepackage{hyperref} -\usepackage{longtable,booktabs} -\urlstyle{same} % don't use monospace font for urls -\setlength{\emergencystretch}{3em} % prevent overfull lines -\providecommand{\tightlist}{% - \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}} -\usepackage{fancyhdr} +$if(geometry)$ +$if(beamer)$ +\geometry{$for(geometry)$$geometry$$sep$,$endfor$} +$else$ +\usepackage[$for(geometry)$$geometry$$sep$,$endfor$]{geometry} +$endif$ +$else$ +\usepackage{geometry} +$endif$ +$if(beamer)$ +\newif\ifbibliography +$endif$ +$if(listings)$ +\usepackage{listings} +\newcommand{\passthrough}[1]{#1} +\lstset{defaultdialect=[5.3]Lua} +\lstset{defaultdialect=[x86masm]Assembler} +$endif$ +$if(lhs)$ +\lstnewenvironment{code}{\lstset{language=Haskell,basicstyle=\small\ttfamily}}{} +$endif$ +$if(highlighting-macros)$ +$highlighting-macros$ +$endif$ +$if(tables)$ +\usepackage{longtable,booktabs,array} +$if(multirow)$ +\usepackage{multirow} +$endif$ +\usepackage{calc} % for calculating minipage widths +$if(beamer)$ +\usepackage{caption} +% Make caption package work with longtable +\makeatletter +\def\fnum@table{\tablename~\thetable} +\makeatother +$else$ +% Correct order of tables after \paragraph or \subparagraph \usepackage{etoolbox} -\usepackage{titleref} -\usepackage{tikz} \makeatletter - \newcommand*{\currentname}{\TR@currentTitle} +\patchcmd\longtable{\par}{\if@noskipsec\mbox{}\fi\par}{}{} \makeatother -\usepackage{charter} -\usepackage[defaultsans,scale=0.95]{lato} -\usepackage{inconsolata} -\renewcommand*\familydefault{\sfdefault} +% Allow footnotes in longtable head/foot +\IfFileExists{footnotehyper.sty}{\usepackage{footnotehyper}}{\usepackage{footnote}} +\makesavenoteenv{longtable} +$endif$ +$endif$ +$if(graphics)$ \usepackage{graphicx} -\usepackage[$if(landscape)$landscape,$endif$top=3.7cm,bottom=2.7cm,left=3cm,right=2cm,headsep=1.5cm,footskip=.5cm]{geometry} -\usepackage{lastpage} - -% Add extra space to table rows -\renewcommand{\arraystretch}{2} - \makeatletter - \patchcmd{\f@nch@foot}{\rlap}{\color{darkgray}\rlap}{}{} - \patchcmd{\footrule}{\hrule}{\color{darkgray}\hrule}{}{} +\def\maxwidth{\ifdim\Gin@nat@width>\linewidth\linewidth\else\Gin@nat@width\fi} +\def\maxheight{\ifdim\Gin@nat@height>\textheight\textheight\else\Gin@nat@height\fi} \makeatother - -\sectionfont{\color{armblue}} -$if(draftversion)$ -\newcommand{\versiontext}{\textcolor{red}{Development version based on $version$}} +% Scale images if necessary, so that they will not overflow the page +% margins by default, and it is still possible to overwrite the defaults +% using explicit options in \includegraphics[width, height, ...]{} +\setkeys{Gin}{width=\maxwidth,height=\maxheight,keepaspectratio} +% Set default figure placement to htbp +\makeatletter +\def\fps@figure{htbp} +\makeatother +$endif$ +$if(svg)$ +\usepackage{svg} +$endif$ +$if(strikeout)$ +$-- also used for underline +\ifLuaTeX + \usepackage{luacolor} + \usepackage[soul]{lua-ul} +\else + \usepackage{soul} +$if(beamer)$ + \makeatletter + \let\HL\hl + \renewcommand\hl{% fix for beamer highlighting + \let\set@color\beamerorig@set@color + \let\reset@color\beamerorig@reset@color + \HL} + \makeatother +$endif$ +$if(CJKmainfont)$ + \ifXeTeX + % soul's \st doesn't work for CJK: + \usepackage{xeCJKfntef} + \renewcommand{\st}[1]{\sout{#1}} + \fi +$endif$ +\fi +$endif$ +\setlength{\emergencystretch}{3em} % prevent overfull lines +\providecommand{\tightlist}{% + \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}} +$if(numbersections)$ +\setcounter{secnumdepth}{$if(secnumdepth)$$secnumdepth$$else$5$endif$} $else$ -\newcommand{\versiontext}{$version$} +\setcounter{secnumdepth}{-\maxdimen} % remove section numbering $endif$ -\newcommand{\dateofissue}{$if(draftversion)$TBD$else$$date-of-issue$$endif$} - -\pagestyle{fancy} -\fancyhf{} -\fancyhead[L]{\small $title$ \\~} -\fancyhead[R]{\small Version: \versiontext \\ \currentname} -\fancyfoot[C]{\small \emph{$copyright-text$}} -\fancyfoot[R]{\small ~\\ Page \textbf{\thepage}\ of \textbf{\pageref*{LastPage}}} -\renewcommand{\footrulewidth}{0pt} -\renewcommand{\headrulewidth}{0pt} - -\fancypagestyle{plain}{% - \fancyhf{} - \fancyhead[L]{\small $title$ \\~} - \fancyhead[R]{\small Version: \versiontext \\ \currentname} - \fancyfoot[C]{\small \emph{$copyright-text$}} - \fancyfoot[R]{\small ~\\ Page \textbf{\thepage}\ of \textbf{\pageref*{LastPage}}} - \renewcommand{\footrulewidth}{0pt} - \renewcommand{\headrulewidth}{0pt} -} - -$if(highlighting-macros)$ - $highlighting-macros$ +$if(subfigure)$ +\usepackage{subcaption} +$endif$ +$if(beamer)$ +$else$ +$if(block-headings)$ +% Make \paragraph and \subparagraph free-standing +\makeatletter +\ifx\paragraph\undefined\else + \let\oldparagraph\paragraph + \renewcommand{\paragraph}{ + \@ifstar + \xxxParagraphStar + \xxxParagraphNoStar + } + \newcommand{\xxxParagraphStar}[1]{\oldparagraph*{#1}\mbox{}} + \newcommand{\xxxParagraphNoStar}[1]{\oldparagraph{#1}\mbox{}} +\fi +\ifx\subparagraph\undefined\else + \let\oldsubparagraph\subparagraph + \renewcommand{\subparagraph}{ + \@ifstar + \xxxSubParagraphStar + \xxxSubParagraphNoStar + } + \newcommand{\xxxSubParagraphStar}[1]{\oldsubparagraph*{#1}\mbox{}} + \newcommand{\xxxSubParagraphNoStar}[1]{\oldsubparagraph{#1}\mbox{}} +\fi +\makeatother +$endif$ +$endif$ +$if(pagestyle)$ +\pagestyle{$pagestyle$} +$endif$ +$if(csl-refs)$ +% definitions for citeproc citations +\NewDocumentCommand\citeproctext{}{} +\NewDocumentCommand\citeproc{mm}{% + \begingroup\def\citeproctext{#2}\cite{#1}\endgroup} +\makeatletter + % allow citations to break across lines + \let\@cite@ofmt\@firstofone + % avoid brackets around text for \cite: + \def\@biblabel#1{} + \def\@cite#1#2{{#1\if@tempswa , #2\fi}} +\makeatother +\newlength{\cslhangindent} +\setlength{\cslhangindent}{1.5em} +\newlength{\csllabelwidth} +\setlength{\csllabelwidth}{3em} +\newenvironment{CSLReferences}[2] % #1 hanging-indent, #2 entry-spacing + {\begin{list}{}{% + \setlength{\itemindent}{0pt} + \setlength{\leftmargin}{0pt} + \setlength{\parsep}{0pt} + % turn on hanging indent if param 1 is 1 + \ifodd #1 + \setlength{\leftmargin}{\cslhangindent} + \setlength{\itemindent}{-1\cslhangindent} + \fi + % set entry spacing + \setlength{\itemsep}{#2\baselineskip}}} + {\end{list}} +\usepackage{calc} +\newcommand{\CSLBlock}[1]{\hfill\break\parbox[t]{\linewidth}{\strut\ignorespaces#1\strut}} +\newcommand{\CSLLeftMargin}[1]{\parbox[t]{\csllabelwidth}{\strut#1\strut}} +\newcommand{\CSLRightInline}[1]{\parbox[t]{\linewidth - \csllabelwidth}{\strut#1\strut}} +\newcommand{\CSLIndent}[1]{\hspace{\cslhangindent}#1} +$endif$ +$if(lang)$ +\ifLuaTeX +\usepackage[bidi=basic]{babel} +\else +\usepackage[bidi=default]{babel} +\fi +$if(babel-lang)$ +\babelprovide[main,import]{$babel-lang$} +$if(mainfont)$ +\ifPDFTeX +\else +\babelfont{rm}[$for(mainfontoptions)$$mainfontoptions$$sep$,$endfor$$if(mainfontfallback)$,RawFeature={fallback=mainfontfallback}$endif$]{$mainfont$} +\fi +$endif$ +$endif$ +$for(babel-otherlangs)$ +\babelprovide[import]{$babel-otherlangs$} +$endfor$ +$for(babelfonts/pairs)$ +\babelfont[$babelfonts.key$]{rm}{$babelfonts.value$} +$endfor$ +% get rid of language-specific shorthands (see #6817): +\let\LanguageShortHands\languageshorthands +\def\languageshorthands#1{} +$endif$ +$for(header-includes)$ +$header-includes$ +$endfor$ +\ifLuaTeX + \usepackage{selnolig} % disable illegal ligatures +\fi +$if(dir)$ +\ifPDFTeX + \TeXXeTstate=1 + \newcommand{\RL}[1]{\beginR #1\endR} + \newcommand{\LR}[1]{\beginL #1\endL} + \newenvironment{RTL}{\beginR}{\endR} + \newenvironment{LTR}{\beginL}{\endL} +\fi +$endif$ +$if(natbib)$ +\usepackage[$natbiboptions$]{natbib} +\bibliographystyle{$if(biblio-style)$$biblio-style$$else$plainnat$endif$} +$endif$ +$if(biblatex)$ +\usepackage[$if(biblio-style)$style=$biblio-style$,$endif$$for(biblatexoptions)$$biblatexoptions$$sep$,$endfor$]{biblatex} +$for(bibliography)$ +\addbibresource{$bibliography$} +$endfor$ +$endif$ +$if(nocite-ids)$ +\nocite{$for(nocite-ids)$$it$$sep$, $endfor$} +$endif$ +$if(csquotes)$ +\usepackage{csquotes} +$endif$ +\usepackage{bookmark} +\IfFileExists{xurl.sty}{\usepackage{xurl}}{} % add URL line breaks if available +\urlstyle{$if(urlstyle)$$urlstyle$$else$same$endif$} +$if(links-as-notes)$ +% Make links footnotes instead of hotlinks: +\DeclareRobustCommand{\href}[2]{#2\footnote{\url{#1}}} +$endif$ +$if(verbatim-in-note)$ +\VerbatimFootnotes % allow verbatim text in footnotes $endif$ - -% Remove "Chapter (Number)" before each new chapter and adjust title spacing. -\usepackage{titlesec} -\titleformat{\chapter}[block] - {\normalfont\huge\bfseries}{\thechapter.}{1em}{\Huge} -\titlespacing*{\chapter}{0pt}{-19pt}{0pt} - -% Set the indent level of the paragraphs. -\usepackage{parskip} -\setlength{\parindent}{0pt} -\setlength{\parskip}{6pt plus 2pt minus 1pt} - -% Set max depth of section numbering and ToC listing - 6 is used due to -% headings going up to h6 in HTML. -\setcounter{tocdepth}{6} -\setcounter{secnumdepth}{6} - -\date{\dateofissue} - \hypersetup{ - colorlinks=true, - linkcolor=armblue, - filecolor=armblue, - citecolor=armblue, - urlcolor=armblue, - breaklinks=true} - -\usepackage{dblfloatfix} -\usepackage{subcaption} - -% These colours are used for rendering the grid image below -\definecolor{armgray}{rgb}{0.5,0.5,0.5} -\definecolor{armlightgray}{rgb}{0.83,0.83,0.83} -\definecolor{armblue}{HTML}{0091BD} - -% This is used to turn block quotes into highlighted text. -$if(set-quote-highlight)$ -\newcounter{rulecounter} -\setcounter{rulecounter}{0} - \usepackage{tcolorbox} - \newtcolorbox{myquote}{colback=white, colframe=armblue, fonttitle=\bfseries, title={Requirement~\therulecounter}} - \renewenvironment{quote}{\begin{myquote}}{\end{myquote}\addtocounter{rulecounter}{1}} +$if(title-meta)$ + pdftitle={$title-meta$}, $endif$ +$if(author-meta)$ + pdfauthor={$author-meta$}, +$endif$ +$if(lang)$ + pdflang={$lang$}, +$endif$ +$if(subject)$ + pdfsubject={$subject$}, +$endif$ +$if(keywords)$ + pdfkeywords={$for(keywords)$$keywords$$sep$, $endfor$}, +$endif$ +$if(colorlinks)$ + colorlinks=true, + linkcolor={$if(linkcolor)$$linkcolor$$else$Maroon$endif$}, + filecolor={$if(filecolor)$$filecolor$$else$Maroon$endif$}, + citecolor={$if(citecolor)$$citecolor$$else$Blue$endif$}, + urlcolor={$if(urlcolor)$$urlcolor$$else$Blue$endif$}, +$else$ +$if(boxlinks)$ +$else$ + hidelinks, +$endif$ +$endif$ + pdfcreator={LaTeX via pandoc}} - +$if(title)$ +\title{$title$$if(thanks)$\thanks{$thanks$}$endif$} +$endif$ +$if(subtitle)$ +$if(beamer)$ +$else$ +\usepackage{etoolbox} \makeatletter -\renewcommand\maketitle{ - \newgeometry{left=0.0cm,right=0.0cm,top=1.0cm,bottom=0.0cm} - \begin{flushleft} - \hspace{1.0cm} \includegraphics[height=0.6cm]{"./tmp/Arm-logo-blue-RGB.pdf"} - \begin{minipage}[t][1.2cm][t]{\linewidth} - \phantom{empty} - \end{minipage} - \newline - \begin{minipage}[t]{4.0cm} - \phantom{empty} - \end{minipage} - \begin{minipage}[t]{14.0cm} - \begin{flushleft} - {\huge \bfseries $title$}\\[2ex] - {\large Release Date: \dateofissue}\\[2ex] - {\large \bfseries Version: \versiontext}\\[3ex] - \end{flushleft} - \end{minipage} - \newline - \begin{minipage}[t][0.47cm][t]{\linewidth} - \phantom{empty} - \end{minipage} - \newline - \begin{minipage}[t]{4.0cm} - \phantom{empty} - \end{minipage} - \begin{minipage}[t]{16.0cm} - \begin{minipage}[t]{9.0cm} - \textbf{$copyright-text$}\\[$if(landscape)$7ex$else$1ex$endif$] - \end{minipage} - \end{minipage} - \end{flushleft} - - % This is the rendering of the grid image used on the title page - \begin{figure}[hbt!] - - \makebox[\paperwidth]{ - $if(landscape)$\begin{subfigure}[b!]{13.8cm}$endif$ - \begin{tikzpicture}[scale=\paperwidth/$if(landscape)$16.0cm$else$8.0cm$endif$,samples=200] - $if(landscape)$ - $else$ - \draw[line width=0.0pt,color=white,fill=armblue] (5.005,0) rectangle (5.995,7); - $endif$ - \draw[line width=0.0pt,color=white,fill=armblue] (0,4.995) rectangle (8,4.005); - \foreach \y in {0,...,7} { - \draw[armlightgray, thin] (0,\y) -- (8,\y); - } - \foreach \x in {1,...,7} { - \draw[armlightgray, thin] (\x,0) -- (\x,7); - \foreach \y in {1,...,7} { - \draw[armgray, thick] (\x,\y - 0.05) -- (\x,\y + 0.05); - \draw[armgray, thick] (\x - 0.05,\y) -- (\x + 0.05,\y); - \draw[white, thick] (\x - 0.01,\y + 0.01) rectangle (\x + 0.01,\y - 0.01); - } - } - \end{tikzpicture} - $if(landscape)$\end{subfigure}$endif$ - $if(landscape)$\begin{subfigure}[b!]{13.8cm} - \begin{tikzpicture}[scale=\paperwidth/16.0cm,samples=200] - \draw[line width=0.0pt,color=white,fill=armblue] (5.005,0) rectangle (5.995,7); - \draw[line width=0.0pt,color=white,fill=armblue] (0,4.995) rectangle (8,4.005); - \foreach \y in {0,...,7} { - \draw[armlightgray, thin] (0,\y) -- (8,\y); - } - \foreach \x in {0,...,7} { - \draw[armlightgray, thin] (\x,0) -- (\x,7); - \foreach \y in {1,...,7} { - \draw[armgray, thick] (\x,\y - 0.05) -- (\x,\y + 0.05); - \draw[armgray, thick] (\x - 0.05,\y) -- (\x + 0.05,\y); - \draw[white, thick] (\x - 0.01,\y + 0.01) rectangle (\x + 0.01,\y - 0.01); - } - } - \end{tikzpicture} - \end{subfigure}$endif$ - } - \end{figure} - \clearpage - \restoregeometry +\providecommand{\subtitle}[1]{% add subtitle to \maketitle + \apptocmd{\@title}{\par {\large #1 \par}}{}{} } \makeatother +$endif$ +\subtitle{$subtitle$} +$endif$ +\author{$for(author)$$author$$sep$ \and $endfor$} +\date{$date$} +$if(beamer)$ +$if(institute)$ +\institute{$for(institute)$$institute$$sep$ \and $endfor$} +$endif$ +$if(titlegraphic)$ +\titlegraphic{\includegraphics{$titlegraphic$}} +$endif$ +$if(logo)$ +\logo{\includegraphics{$logo$}} +$endif$ +$endif$ -\color{darkgray} \begin{document} +$if(has-frontmatter)$ +\frontmatter +$endif$ +$if(title)$ +$if(beamer)$ +\frame{\titlepage} +$else$ +\maketitle +$endif$ +$if(abstract)$ +\begin{abstract} +$abstract$ +\end{abstract} +$endif$ +$endif$ - \maketitle - \tableofcontents - \newpage - $body$ +$for(include-before)$ +$include-before$ + +$endfor$ +$if(toc)$ +$if(toc-title)$ +\renewcommand*\contentsname{$toc-title$} +$endif$ +$if(beamer)$ +\begin{frame}[allowframebreaks] +$if(toc-title)$ + \frametitle{$toc-title$} +$endif$ + \tableofcontents[hideallsubsections] +\end{frame} +$else$ +{ +$if(colorlinks)$ +\hypersetup{linkcolor=$if(toccolor)$$toccolor$$else$$endif$} +$endif$ +\setcounter{tocdepth}{$toc-depth$} +\tableofcontents +} +$endif$ +$endif$ +$if(lof)$ +\listoffigures +$endif$ +$if(lot)$ +\listoftables +$endif$ +$if(linestretch)$ +\setstretch{$linestretch$} +$endif$ +$if(has-frontmatter)$ +\mainmatter +$endif$ +$body$ + +$if(has-frontmatter)$ +\backmatter +$endif$ +$if(natbib)$ +$if(bibliography)$ +$if(biblio-title)$ +$if(has-chapters)$ +\renewcommand\bibname{$biblio-title$} +$else$ +\renewcommand\refname{$biblio-title$} +$endif$ +$endif$ +$if(beamer)$ +\begin{frame}[allowframebreaks]{$biblio-title$} + \bibliographytrue +$endif$ + \bibliography{$for(bibliography)$$bibliography$$sep$,$endfor$} +$if(beamer)$ +\end{frame} +$endif$ + +$endif$ +$endif$ +$if(biblatex)$ +$if(beamer)$ +\begin{frame}[allowframebreaks]{$biblio-title$} + \bibliographytrue + \printbibliography[heading=none] +\end{frame} +$else$ +\printbibliography$if(biblio-title)$[title=$biblio-title$]$endif$ +$endif$ + +$endif$ +$for(include-after)$ +$include-after$ +$endfor$ \end{document} diff --git a/tools/docker/Dockerfile b/tools/docker/Dockerfile index 1a0c261c..b0b0bf41 100644 --- a/tools/docker/Dockerfile +++ b/tools/docker/Dockerfile @@ -1,11 +1,11 @@ -# SPDX-FileCopyrightText: Copyright 2021 Arm Limited and/or its affiliates +# SPDX-FileCopyrightText: Copyright 2021-2026 Arm Limited and/or its affiliates # SPDX-License-Identifier: Apache-2.0 # syntax=docker/dockerfile:1 -# We use Ubuntu 20.04 (Long term Support, LTS) to avoid major updates +# We use Ubuntu 24.04 (Long term Support, LTS) to avoid major updates # in the tools used to build the specification to avoid changes in the # appearance of the PDFs. -FROM ubuntu:20.04 +FROM ubuntu:24.04 ENV DEBIAN_FRONTEND="noninteractive" # The option --no-install-recommends is used to prevent apt from # installing the texlive-*-doc packages. diff --git a/tools/generate-pdfs.sh b/tools/generate-pdfs.sh index 104cacc3..9737fa9d 100755 --- a/tools/generate-pdfs.sh +++ b/tools/generate-pdfs.sh @@ -1,7 +1,7 @@ #!/usr/bin/env bash set -ex -# SPDX-FileCopyrightText: Copyright 2021-2022 Arm Limited and/or its affiliates +# SPDX-FileCopyrightText: Copyright 2021-2026 Arm Limited and/or its affiliates # SPDX-License-Identifier: Apache-2.0 # # Licensed under the Apache License, Version 2.0 (the "License"); @@ -42,7 +42,11 @@ function generate_pdfs_from_md() { mkdir -p pdfs tmp # Convert svg image to pdf for use in pdf generation via pandoc. -inkscape -z Arm_logo_blue_RGB.svg -e tmp/Arm-logo-blue-RGB.pdf +inkscape \ + --batch-process \ + --export-type=pdf \ + --export-filename=tmp/Arm-logo-blue-RGB.pdf \ + Arm_logo_blue_RGB.svg generate_pdfs_from_md ./cmse/cmse.md ./pdfs/cmse.pdf generate_pdfs_from_md ./morello/morello.md ./pdfs/morello.pdf diff --git a/tools/hyperref-check.sh b/tools/hyperref-check.sh index 7634702d..97b12b61 100755 --- a/tools/hyperref-check.sh +++ b/tools/hyperref-check.sh @@ -1,12 +1,16 @@ #!/usr/bin/env bash -# SPDX-FileCopyrightText: Copyright 2021-2022 Arm Limited and/or its affiliates +# SPDX-FileCopyrightText: Copyright 2021-2026 Arm Limited and/or its affiliates # SPDX-License-Identifier: Apache-2.0 set -ex # Convert svg image to pdf for use in pdf generation via pandoc. mkdir -p pdfs tmp -inkscape -z Arm_logo_blue_RGB.svg -e tmp/Arm-logo-blue-RGB.pdf +inkscape \ + --batch-process \ + --export-type=pdf \ + --export-filename=tmp/Arm-logo-blue-RGB.pdf \ + Arm_logo_blue_RGB.svg # Extracting all broken hyperref detected by PDFTex for file in "./main/acle.md" "./morello/morello.md" "./mve_intrinsics/mve.md" "./neon_intrinsics/advsimd.md" \ From bc104d8a87921b76e4ea1ec479522f7622ba0019 Mon Sep 17 00:00:00 2001 From: Claudio Bantaloukas Date: Tue, 31 Mar 2026 12:52:54 +0000 Subject: [PATCH 6/7] Separate build-pdfs steps for clarity --- .github/workflows/ci.yml | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 94118275..5571905c 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -12,9 +12,9 @@ jobs: image: docker.io/library/ubuntu:24.04 steps: - uses: actions/checkout@v6.0.2 - - name: check the correctness of the sources and generate the PDFs + # The step below is equivalent to the Dockerfile in tools/docker + - name: Install required dependencies run: | - # This is equivalent to the Dockerfile in tools/docker apt-get update \ && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \ texlive-latex-base \ @@ -29,16 +29,16 @@ jobs: librsvg2-bin \ nodejs - # this is equivalent to the entrypoint of the Dockerfile in tools/docker + # The steps below are equivalent to the entrypoint of the Dockerfile in tools/docker + - name: Check that the internal links in the markdown files are correct + run: ./tools/hyperref-check.sh || exit 1 - # Check that the internal links in the markdown files are correct - ./tools/hyperref-check.sh || exit 1 - - # Recreate the full markdown files from the templates and check that the saved ones are consistent. - ./tools/generate-intrinsics-specs.sh || exit 1 - - ./tools/generate-pdfs.sh || exit 1 + - name: Recreate the full markdown files from the templates and check that the saved ones are consistent. + run: ./tools/generate-intrinsics-specs.sh || exit 1 + - name: Create PDFs + run: ./tools/generate-pdfs.sh || exit 1 + - uses: actions/upload-artifact@v7 with: name: pdfs From 6767454a4145224ba2b163e2196562d74012ac31 Mon Sep 17 00:00:00 2001 From: Claudio Bantaloukas Date: Tue, 31 Mar 2026 12:53:17 +0000 Subject: [PATCH 7/7] Update final files copyright dates --- mve_intrinsics/mve.md | 4 ++-- neon_intrinsics/advsimd.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/mve_intrinsics/mve.md b/mve_intrinsics/mve.md index f653ebf3..5372ead9 100644 --- a/mve_intrinsics/mve.md +++ b/mve_intrinsics/mve.md @@ -4,7 +4,7 @@ version: 2021Q4 date-of-issue: 11 January 2022 # LaTeX specific variables landscape: true -copyright-text: Copyright 2019-2022 Arm Limited and/or its affiliates . +copyright-text: Copyright 2019-2026 Arm Limited and/or its affiliates . draftversion: true # Jekyll specific variables header_counter: true @@ -12,7 +12,7 @@ toc: true --- diff --git a/neon_intrinsics/advsimd.md b/neon_intrinsics/advsimd.md index 630ca2c6..37793135 100644 --- a/neon_intrinsics/advsimd.md +++ b/neon_intrinsics/advsimd.md @@ -12,7 +12,7 @@ toc: true ---