Use of LaTeX for the specification

Use of LaTeX for the specification

[Alex Bennée]

Hi,

I recently updated my distro to Trixie and found that HTML generation is
broken. 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

RE: Use of LaTeX for the specification

[Parav Pandit]

> 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


> 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

Re: Use of LaTeX for the specification

[Alex Bennée]

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

Re: Use of LaTeX for the specification

[Michael S. Tsirkin]

On Mon, Sep 29, 2025 at 07:22:52PM +0100, Alex Bennée wrote:
> 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. 


Alex pls note HTML generation is using htlatex not xetex


> > 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.


What is the command line you are using for this example?

> >> 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

Re: Use of LaTeX for the specification

[Matias Ezequiel Vara Larsen]

On Mon, Sep 29, 2025 at 03:41:18PM +0100, Alex Bennée wrote:
> 
> Hi,
> 
> I recently updated my distro to Trixie and found that HTML generation is
> broken. 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

I think that is a great idea. I wonder if we can do it in the current
Github repo. Do you mean to automatically generate `.pdf` from HEAD for
example?

Matias

Re: Use of LaTeX for the specification

[Alex Bennée]

Matias Ezequiel Vara Larsen <mvaralar@redhat.com> writes:

> On Mon, Sep 29, 2025 at 03:41:18PM +0100, Alex Bennée wrote:
>> 
>> Hi,
>> 
>> I recently updated my distro to Trixie and found that HTML generation is
>> broken. 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
>
> I think that is a great idea. I wonder if we can do it in the current
> Github repo. Do you mean to automatically generate `.pdf` from HEAD for
> example?

Yes

I did something similar when we were drafting the virtio-msg spec:

  https://github.com/Linaro/virtio-msg-spec/releases

>
> Matias

-- 
Alex Bennée
Virtualisation Tech Lead @ Linaro

Re: Use of LaTeX for the specification

[Michael S. Tsirkin]

On Mon, Sep 29, 2025 at 03:41:18PM +0100, Alex Bennée wrote:
> 
> Hi,
> 
> I recently updated my distro to Trixie and found that HTML generation is
> broken. 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?

Frankly because there's a template someone else wrote that
makes the output fit OASIS required format.


> 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?

OASIS does not mandate a specific format, but it does mandate
specific *formatting*.

> Thanks,
> 
> -- 
> Alex Bennée
> Virtualisation Tech Lead @ Linaro