Re: Use of LaTeX for the specification

["Alex Bennée" <alex.bennee@linaro.org>]

Parav Pandit <parav@nvidia.com> writes:

>> From: Alex Bennée <alex.bennee@linaro.org>
>> Sent: 29 September 2025 08:11 PM
>> 
>> 
>> Hi,
>> 
>> I recently updated my distro to Trixie and found that HTML generation is
>> broken. 
>
> I test html and pdf generation regularly on merging patches.
> And it seems to work for me with below version.
> Which one are you using that fails?
>
> XeTeX 3.141592653-2.6-0.999993 (TeX Live 2022/dev/Debian)
> kpathsea version 6.3.4/dev
> Copyright 2021 SIL International, Jonathan Kew and Khaled Hosny.
> There is NO warranty.  Redistribution of this software is
> covered by the terms of both the XeTeX copyright and
> the Lesser GNU General Public License.
> For more information about these matters, see the file
> named COPYING and the XeTeX source.
> Primary author of XeTeX: Jonathan Kew.
> Compiled with ICU version 70.1; using 70.1
> Compiled with zlib version 1.2.11; using 1.2.11
> Compiled with FreeType2 version 2.11.1; using 2.11.1
> Compiled with Graphite2 version 1.3.14; using 1.3.14
> Compiled with HarfBuzz version 2.7.4; using 2.7.4
> Compiled with libpng version 1.6.37; using 1.6.37
> Compiled with pplib version v2.05 less toxic i hope
> Compiled with fontconfig version 2.13.1; using 2.13.1

➜  xetex --version
XeTeX 3.141592653-2.6-0.999996 (TeX Live 2025/dev/Debian)
kpathsea version 6.4.0/dev
Copyright 2024 SIL International, Jonathan Kew and Khaled Hosny.
There is NO warranty.  Redistribution of this software is
covered by the terms of both the XeTeX copyright and
the Lesser GNU General Public License.
For more information about these matters, see the file
named COPYING and the XeTeX source.
Primary author of XeTeX: Jonathan Kew.
Compiled with ICU version 76.1; using 76.1
Compiled with zlib version 1.3.1; using 1.3.1
Compiled with FreeType2 version 2.13.3; using 2.13.3
Compiled with Graphite2 version 1.3.14; using 1.3.14
Compiled with HarfBuzz version 10.2.0; using 10.2.0
Compiled with libpng version 1.6.47; using 1.6.48
Compiled with pplib version v2.2
Compiled with fontconfig version 2.15.0; using 2.15.0

It also fails run with the texlive distro:

📦[alex@texlive virtio-spec.git]> xetex --version
XeTeX 3.141592653-2.6-0.999997 (TeX Live 2025)
kpathsea version 6.4.1
Copyright 2025 SIL International, Jonathan Kew and Khaled Hosny.
There is NO warranty.  Redistribution of this software is
covered by the terms of both the XeTeX copyright and
the Lesser GNU General Public License.
For more information about these matters, see the file
named COPYING and the XeTeX source.
Primary author of XeTeX: Jonathan Kew.
Compiled with ICU version 76.1; using 76.1
Compiled with zlib version 1.3.1; using 1.3.1
Compiled with FreeType2 version 2.13.3; using 2.13.3
Compiled with Graphite2 version 1.3.14; using 1.3.14
Compiled with HarfBuzz version 10.2.0; using 10.2.0
Compiled with libpng version 1.6.46; using 1.6.46
Compiled with pplib version v2.2
Compiled with fontconfig version 2.13.1; using 2.15.0

>
>
>> As far as I can tell this comes down to the use of \cline as shown in this
>> minimal example:
>> 
>>   \documentclass{article}
>>   \usepackage{hhline}
>>   \begin{document}
>>   \begin{tabular}{ |l||l|l| }
>>   \hline
>>   Bits & Device Specific & Purpose \\
>>   \cline{1-2}
>>   Read / Write & Device Specific & \\
>>   \cline{1-2}
>>   Purpose & Device Specific & \\
>>   \hline
>>   \end{tabular}
>>   \end{document}
>> 
>> which results in TeX ending early:
>> 
>>   ! Undefined control sequence.
>>   \f:HBorder ...border-top:1px solid \#\hline:color
>>                                                     ;"></td>
>>   l.8 R
>>        ead / Write & Device Specific & \\
>>   ?
>>   ! Emergency stop.
>> 
>> I'm liaising with Debian and the TexLive authors to try and figure out whats
>> going on. However it does raise a bigger question for the specification - why do
>> we use LaTeX?
>> 
>> I don't doubt that is a powerful typesetting system but its arcane syntax is a
>> bit of a barrier to entry especially for casual contributors. With the recent
>> breakage I wonder if I'm the canary in the coal mine and this will potentially be
>> a problem for everyone else once their TeX setups upgrade.
>> 
>> I'd like to augment the repo with some GitHub actions so we can keep an upto
>> date rendered draft available as well as some lint checks so we can avoid
>> introducing dodgy markup. But firstly I want to ask is LaTeX the right source
>> format for the spec going forward? Is this something mandated by OASIS or
>> just an accident of history?
>> 
>> Thanks,
>> 
>> --
>> Alex Bennée
>> Virtualisation Tech Lead @ Linaro

-- 
Alex Bennée
Virtualisation Tech Lead @ Linaro