Re: [RFC PATCH v1 0/2] Embed files as PDF attachments

["Michael S. Tsirkin" <mst@redhat.com>]

On Sun, Sep 15, 2024 at 02:31:26PM +0300, Manos Pitsidianakis wrote:
> On Sun, 15 Sept 2024 at 14:11, Michael S. Tsirkin <mst@redhat.com> wrote:
> >
> > On Sun, Sep 15, 2024 at 10:56:29AM +0300, Manos Pitsidianakis wrote:
> > > The PDF specs allow for file attachments to documents. This can be used
> > > to make the VIRTIO PDF spec a single source of truth by embedding
> > > related files.
> > >
> > > This series attaches the virtio-queue.h header file as a proof of
> > > concept. It can be inspected and extracted using a compliant PDF viewer
> > > such as Adobe's or Firefox's integrated PDF reader.
> > >
> > > (Note: I'm not sure if Chrome supports it, my local version does not,
> > > neither does Chromium.)
> > >
> > > Programmatically extracting files is also possible, allowing for
> > > downstream projects to update their headers by accessing the upstream
> > > pdf file.
> > >
> > > Example using the `pdfdetach` utility from the Xpdf package of tools
> > > (`poppler-utils` package on debian/ubuntu):
> > >
> > >   $ pdfdetach -list virtio-v1.3-csd01.pdf
> > >   1 embedded files
> > >   1: virtio-queue.h
> > >   $ pdfdetach -save 1 virtio-v1.3-csd01.pdf
> > >   $ file virtio-queue.h
> > >   virtio-queue.h: C source, ASCII text
> >
> >
> > Really cool, thank you Manos!
> 
> Hello Michael,
> 
> Forgot to mention on my cover letter: We are interested in this not
> just for virtio-queue.h but for defining normative definitions of
> constants and memory layouts of structures for transports/devices. For
> example if we take all the inline code listings of a device \section
> and generate a file (to avoid having them checked into source control
> and have two instances/sources of truth of the definitions, tex and .h
> files) we can add a final \subsection at the end, for example
> something like:
> 
> diff --git a/device-types/sound/description.tex
> b/device-types/sound/description.tex
> index 54c9c8e..d79e66e 100644
> --- a/device-types/sound/description.tex
> +++ b/device-types/sound/description.tex
> @@ -1177,3 +1177,9 @@ \subsubsection{Control
> Elements}\label{sec:Device Types / Sound Device / Device
>  \begin{itemize}
>  \item The device MUST NOT set undefined \field{mask} values.
>  \end{itemize}
> +
> +\subsection[virtio-snd.h]{virtio-snd.h}\label{sec:virtio-snd.h}
> +\label{sec:virtio-snd.h}
> +\attachsource{virtio-snd.h}
> +All definitions in this header file are for normative reference.

Yes, we could import the headers from Linux.

> Also, I have made changes to show the filename instead of an icon and
> attached a screenshot of how it appears in my Firefox (with the cursor
> hovering over the filename link).

Sounds good.
Getting ready for LPC so don't have the time to test it properly.

> 
> > > Manos Pitsidianakis (2):
> > >   specvars.tex: Add \virtioauthor command
> > >   Embed virtio-queue.h as PDF attachment
> > >
> > >  commands-html.tex |  7 +++++++
> > >  commands-pdf.tex  | 10 ++++++++++
> > >  headerfile.tex    |  2 ++
> > >  specvars.tex      |  3 ++-
> > >  virtio.tex        |  1 +
> > >  5 files changed, 22 insertions(+), 1 deletion(-)
> > >
> > >
> > > base-commit: b495841a8e80d12c1130f8868f4128866291142d
> > > --
> > > γαῖα πυρί μιχθήτω
> > >
> >
> 
> 
> -- 
> Manos Pitsidianakis
> Emulation and Virtualization Engineer at Linaro Ltd