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

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

[Manos Pitsidianakis]

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

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
-- 
γαῖα πυρί μιχθήτω

[RFC PATCH v1 1/2] specvars.tex: Add \virtioauthor command

[Manos Pitsidianakis]

Add a macro that expands to the spec author "OASIS Virtual I/O Device
(VIRTIO) TC". This will be used in subsequent commits to define the
author of attached files in the pdf build.

Signed-off-by: Manos Pitsidianakis <manos.pitsidianakis@linaro.org>
---
 specvars.tex | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/specvars.tex b/specvars.tex
index a80557a..7d3c8f7 100644
--- a/specvars.tex
+++ b/specvars.tex
@@ -1,4 +1,5 @@
 \input{setup-generated.tex}
+\newcommand{\virtioauthor}{OASIS Virtual I/O Device (VIRTIO) TC}
 \newcommand{\virtioversion}{Virtual I/O Device (VIRTIO) Version \virtiorev}
 \newcommand{\virtiospecfile}{virtio-v\virtiorev-\virtiodraftstage\virtioworkingdraft}
 \newcommand{\virtiourlbase}{https://docs.oasis-open.org/virtio/virtio/v\virtiorev/\virtiodraftstage\virtioworkingdraft}
@@ -15,7 +16,7 @@
 
 % PDF setup
 \hypersetup{
-pdfauthor = {OASIS Virtual I/O Device (VIRTIO) TC},
+pdfauthor = {\virtioauthor},
 pdftitle = {Virtual I/O Device (VIRTIO) Version \virtiorev},
 pdfsubject = {Virtual I/O Device (VIRTIO) Version \virtiorev},
 pdfkeywords = {VIRTIO, Virtual I/O Device},
-- 
γαῖα πυρί μιχθήτω

[RFC PATCH v1 2/2] Embed virtio-queue.h as PDF attachment

[Manos Pitsidianakis]

Using the TeX package `attachfile2` we're able to attach the C header
file as a PDF standards-compliant attachment in the PDF document,
allowing it to be a single source of truth for related files.

Signed-off-by: Manos Pitsidianakis <manos.pitsidianakis@linaro.org>
---
 commands-html.tex |  7 +++++++
 commands-pdf.tex  | 10 ++++++++++
 headerfile.tex    |  2 ++
 virtio.tex        |  1 +
 4 files changed, 20 insertions(+)

diff --git a/commands-html.tex b/commands-html.tex
index 488eacb..144bbb2 100644
--- a/commands-html.tex
+++ b/commands-html.tex
@@ -180,3 +180,10 @@
 \vspace{0.2in}
 }
 
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%% VIRTIO C header file (.h) PDF attachments - expand to nothing
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\newcommand{\attachsource}[1]{%
+}%
diff --git a/commands-pdf.tex b/commands-pdf.tex
index 23289d8..62d4169 100644
--- a/commands-pdf.tex
+++ b/commands-pdf.tex
@@ -196,3 +196,13 @@
 \vspace{0.2in}
 }
 
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%% VIRTIO C header file (.h) PDF attachments
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\newcommand{\attachsource}[1]{%
+{%
+This file is available as a PDF attachment %
+\attachfile[icon=Paperclip,mimetype=text/x-c,author=\virtioauthor{}]{#1}%
+}%
+}%
diff --git a/headerfile.tex b/headerfile.tex
index 767005c..d194031 100644
--- a/headerfile.tex
+++ b/headerfile.tex
@@ -1,5 +1,7 @@
 \chapter[virtio_queue.h]{virtio_queue.h}\label{sec:virtio-queue.h}
 \label{sec:virtio-ring.h}
+\attachsource{virtio-queue.h}
+
 This file is also available at the link
 \virtiourlh.
 All definitions in this section are for non-normative reference
diff --git a/virtio.tex b/virtio.tex
index 37e49b1..94f508f 100644
--- a/virtio.tex
+++ b/virtio.tex
@@ -38,6 +38,7 @@
 \usepackage{underscore}
 \usepackage{xstring}
 \usepackage{enumitem}
+\usepackage{attachfile2}
 \IfFileExists{ellipsis.sty}{\usepackage{ellipsis}}{
 \message{!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!}
 \message{LaTeX Warning: Missing ellipsis.sty: dots (...) will look ugly}
-- 
γαῖα πυρί μιχθήτω

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

[Michael S. Tsirkin]

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!

> 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
> -- 
> γαῖα πυρί μιχθήτω
> 

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

[Manos Pitsidianakis]

[-- Attachment #1: Type: text/plain, Size: 3058 bytes --]

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.

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


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

[-- Attachment #2: 6192.png --]
[-- Type: image/png, Size: 51860 bytes --]

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

[Michael S. Tsirkin]

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