Re: Use of LaTeX for the specification

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

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