Skip to contentSkip to conversation

some tweaks to the document build process

RFC PATCH Superseded Alex Bennée 3 participants 16 messages Mar 27, 2020 – Apr 30, 2020

Subsystems (2)

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore
#0 lore raw

cover some tweaks to the document build process

Hi,

I was reviewing someones virtio-spec and realised that I wasn't quite sure what it had been built from. Seeing as the standard is hosted in git I've tried to clean up some of the automation to make it clearer what a particular rendering was built from. Going forward it would be nice to use signed annotated tags for the final build version but I don't know how much of the boilerplate is down to OASIS requirements.

What do people think? Is this worth improving on?

Alex Bennée (8):
README.md: convert html to proper Markdown format CONTRIBUTING.md: convert to proper MarkDown LICENSE.md: convert html to proper MarkDown makeall.sh: add explicit shebang to script Cleanup old changelog files
Remove all mentioned of subversion
make*: remove reliance on REVISION-DATE and use git
Makefile: add simple make automation with clean target

 CONTRIBUTING.md         |   22 +-
 LICENSE.md              |    9 +-
 Makefile                |   17 +
 README.md               |  258 ++++------
 REVISION-DATE           |    1 -
 cl-cs01.tex             |   86 ----
 cl-cs02.tex             |   52 --
 cl-cs03.tex             |  328 ------------
 cl-cs04.tex             |  134 -----
 cl-csprd02.tex          | 1043 ---------------------------------------
 cl-csprd03.tex          |  400 ---------------
 getchangelog.pl         |  114 -----
 git-svn.txt             |   34 --
 make-setup-generated.sh |   54 +-
 makeall.sh              |    3 +-
 makediff.sh             |    1 -
 makediffall.sh          |    1 -
 makediffwithbase.sh     |    1 -
 maketex.sh              |    1 -
 makezip.sh              |   11 +-
 20 files changed, 169 insertions(+), 2401 deletions(-)
 create mode 100644 Makefile
 delete mode 100644 REVISION-DATE
 delete mode 100644 cl-cs01.tex
 delete mode 100644 cl-cs02.tex
 delete mode 100644 cl-cs03.tex
 delete mode 100644 cl-cs04.tex
 delete mode 100644 cl-csprd02.tex
 delete mode 100644 cl-csprd03.tex
 delete mode 100755 getchangelog.pl
 delete mode 100644 git-svn.txt
Signature · 18 lines
2.20.1


This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/
#1 lore raw

RFC PATCH 1/8 README.md: convert html to proper Markdown format

---
 README.md | 258 +++++++++++++++++++++---------------------------------
 1 file changed, 100 insertions(+), 158 deletions(-)
README.md +100 -158
index 2bdf485..8bb10e0 100644
@@ -1,173 +1,115 @@
-<div>
-<h2>README</h2>
+Members of the [OASIS Virtual I/O Device (VIRTIO) TC](https://www.oasis-open.org/committees/virtio/) create and manage technical content in this TC GitHub repository ( [https://github.com/oasis-tcs/virtio-spec](https://github.com/oasis-tcs/virtio-spec) ) as part of the TC's chartered work (_i.e._, the program of work and deliverables described in its [charter](https://www.oasis-open.org/committees/virtio/charter.php)).
 
-<p>Members of the <a href="https://www.oasis-open.org/committees/virtio/">OASIS Virtual I/O Device (VIRTIO) TC</a> create and manage technical content in this TC GitHub repository ( <a href="https://github.com/oasis-tcs/virtio-spec">https://github.com/oasis-tcs/virtio-spec</a> ) as part of the TC's chartered work (<i>i.e.</i>, the program of work and deliverables described in its <a href="https://www.oasis-open.org/committees/virtio/charter.php">charter</a>).</p>
+OASIS TC GitHub repositories, as described in [GitHub Repositories for OASIS TC Members' Chartered Work](https://www.oasis-open.org/resources/tcadmin/github-repositories-for-oasis-tc-members-chartered-work), are governed by the OASIS [TC Process](https://www.oasis-open.org/policies-guidelines/tc-process), [IPR Policy](https://www.oasis-open.org/policies-guidelines/ipr), and other policies, similar to TC Wikis, TC JIRA issues tracking instances, TC SVN/Subversion repositories, etc. While they make use of public GitHub repositories, these TC GitHub repositories are distinct from [OASIS Open Repositories](https://www.oasis-open.org/resources/open-repositories), which are used for development of open source [licensed](https://www.oasis-open.org/resources/open-repositories/licenses) content.
 
-<p>OASIS TC GitHub repositories, as described in <a href="https://www.oasis-open.org/resources/tcadmin/github-repositories-for-oasis-tc-members-chartered-work">GitHub Repositories for OASIS TC Members' Chartered Work</a>, are governed by the OASIS <a href="https://www.oasis-open.org/policies-guidelines/tc-process">TC Process</a>, <a href="https://www.oasis-open.org/policies-guidelines/ipr">IPR Policy</a>, and other policies, similar to TC Wikis, TC JIRA issues tracking instances, TC SVN/Subversion repositories, etc.  While they make use of public GitHub repositories, these TC GitHub repositories are distinct from <a href="https://www.oasis-open.org/resources/open-repositories">OASIS Open Repositories</a>, which are used for development of open source <a href="https://www.oasis-open.org/resources/open-repositories/licenses">licensed</a> content.</p>
-</div>
+### Description
 
-<div>
-<h3>Description</h3>
+This repository includes the [authoritative source](https://github.com/oasis-tcs/virtio-spec/releases) of the VIRTIO (Virtual I/O) Specification document. VIRTIO document describes the specifications of the "virtio" family of devices. These devices are found in virtual environments, yet by design they look like physical devices to the guest within the virtual machine — and this document treats them as such. This similarity allows the guest to use standard drivers and discovery mechanisms.
 
-<p>This repository includes the <a href="https://github.com/oasis-tcs/virtio-spec/releases">authoritative source</a> of the VIRTIO (Virtual I/O) Specification document. VIRTIO document describes the specifications of the "virtio" family of devices. These devices are found in virtual environments, yet by design they look like physical devices to the guest within the virtual machine &mdash; and this document treats them as such. This similarity allows the guest to use standard drivers and discovery mechanisms. </p>
+The purpose of virtio and this specification is that virtual environments and guests should have a straightforward, efficient, standard and extensible mechanism for virtual devices, rather than boutique per-environment or per-OS mechanisms.
 
-<p>The purpose of virtio and this specification is that virtual environments and guests should have a straightforward, efficient, standard and extensible mechanism for virtual devices, rather than boutique per-environment or per-OS mechanisms.</p>
-</div>
+### Contributions
 
-<div>
-<h3>Contributions</h3>
-<p>As stated in this repository's <a href="https://github.com/oasis-tcs/virtio-spec/blob/master/CONTRIBUTING.md">CONTRIBUTING file</a>, contributors to this repository are expected to be Members of the OASIS virtio TC, for any substantive change requests.  Anyone wishing to contribute to this GitHub project and <a href="https://www.oasis-open.org/join/participation-instructions">participate</a> in the TC's technical activity is invited to join as an OASIS TC Member.  Public feedback is also accepted, subject to the terms of the <a href="https://www.oasis-open.org/policies-guidelines/ipr#appendixa">OASIS Feedback License</a>.</p>
-</div>
+As stated in this repository's [CONTRIBUTING file](https://github.com/oasis-tcs/virtio-spec/blob/master/CONTRIBUTING.md), contributors to this repository are expected to be Members of the OASIS virtio TC, for any substantive change requests. Anyone wishing to contribute to this GitHub project and [participate](https://www.oasis-open.org/join/participation-instructions) in the TC's technical activity is invited to join as an OASIS TC Member. Public feedback is also accepted, subject to the terms of the [OASIS Feedback License](https://www.oasis-open.org/policies-guidelines/ipr#appendixa).
 
+### Licensing
 
+Please see the [LICENSE](https://github.com/oasis-tcs/virtio-spec/blob/master/LICENSE.md) file for description of the license terms and OASIS policies applicable to the TC's work in this GitHub project. Content in this repository is intended to be part of the virtio TC's permanent record of activity, visible and freely available for all to use, subject to applicable OASIS policies, as presented in the repository [LICENSE](https://github.com/oasis-tcs/virtio-spec/blob/master/LICENSE.md) file.
 
-<div>
-<h3>Licensing</h3>
-<p>Please see the <a href="https://github.com/oasis-tcs/virtio-spec/blob/master/LICENSE.md">LICENSE</a> file for description of the license terms and OASIS policies applicable to the TC's work in this GitHub project. Content in this repository is intended to be part of the virtio TC's permanent record of activity, visible and freely available for all to use, subject to applicable OASIS policies, as presented in the repository <a href="https://github.com/oasis-tcs/virtio-spec/blob/master/LICENSE.md">LICENSE</a> file.</p>
-</div>
+### Further Description of this Repository
 
-<div>
+#### Building Instructions
 
-<h3>Further Description of this Repository</h3>
-<h4>Building Instructions</h4>
-Authoritative version of the specification is maintained in the
-TeX document format. PDF and HTML versions are made available for
-ease of use and review.
-In order to build the HTML and PDF versions of the spec you will need the
-TeX document production system.
-The easiest way to get it up and running is probably by installing
-<a href="https://www.tug.org/texlive/">Tex-Live</a>.
+Authoritative version of the specification is maintained in the TeX document format. PDF and HTML versions are made available for ease of use and review. In order to build the HTML and PDF versions of the spec you will need the TeX document production system. The easiest way to get it up and running is probably by installing [Tex-Live](https://www.tug.org/texlive/).
+
+Installation cheat sheet:
+
+Fedora:
+
+`sudo dnf install texlive-scheme-full`
 
-<dl>Installation cheat sheet:
-<dt>Fedora:</dt>
-<dd>
-<code>
-sudo dnf install texlive-scheme-full
-</code></dd>
-<dt>
 Ubuntu and other Debian derivatives:
-</dt>
-<dd>
-<code>
-sudo apt-get install texlive-full
-</code></dd>
-<dt>OSX:<dt>
-<dd>OSX users don't need to install Tex-Live because they already have
-<a href="http://www.tug.org/mactex/">MacTeX</a> installed.
-</dd>
-</dl>
-<dl>The build process generates a ZIP package file including the
-original TeX sources, as well as HTML and PDF formatted
-versions of the specification.
-<dt>To generate the ZIP package, run:<dt>
-<dd>
-<code>
-./makeall.sh
-</code>
-</dd>
-<dt>Troubleshooting notes:</dt>
-<dd> PDFs of the specification can be generated with
-either MicroSoft's Core fonts for the Web: Arial and Courier New,
-or Liberation fonts: Liberation Sans and Liberation Mono.
-Most systems come with one of these two variants included:
-should you get an error message about missing fonts,
-you will need to downloads and install one of the above
-font packages.
-<dd>
-</dl>
-<h4>Providing Feedback</h4>
-Feedback must be provided the <strong>virtio-comment</strong> mailing list,
-and archived in the mailing list archives.
-<p>See <A
-HREF="https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=virtio#feedback">
-https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=virtio#feedback</A>
-<p>Note that only plain text part of the message is archived, and all
-attachments are stripped. Accordingly, messages sent to the
-mailing list should use text/plain encoding and not
-have any attachments.
-<p>The preferred form of providing feedback is in form of a patch.
-A patch can be generated and sent by cloning the spec repository,
-creating a commit, formatting it as a patch and then sending it.
-For example:
-<code>
-<p>
-git clone https://github.com/oasis-tcs/virtio-spec.git<br>
-... edit spec text, and save ...<br>
-<p>
-git commit -a<br>
-... describe the proposed change, in the following format:<br>
-single line summary<br>
-<br>
-detailed description, including motivation for the change<br>
-<br>
-Signed-off-by: Name &lt;email&gt;<br>
-... then save and close the editor ... <br>
-<p>
-git format-patch -o proposal1/ HEAD~1..<br>
-... generates a new directory proposal1/ and a file starting with 0001- ...<br>
-<p>
-git send-email [email protected] proposal1/0001-*
-</code>
-<h4>Note for TC Members</h4>
-<p>TC Members should review TC specific
-process rules under "Further Description of this Repository"
-in <A
-HREF="https://github.com/oasis-tcs/virtio-admin">https://github.com/oasis-tcs/virtio-admin</A>.
-
-</div>
-<h4>Implementation discussion</h4>
-Implementation discussion should take place on the <strong>virtio-dev</strong> mailing list,
-and be archived in the mailing list archives.
-<p>See <A
-HREF="https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=virtio#feedback">
-https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=virtio#feedback</A>
-<p>This is the correct list to copy on Linux virtio UAPI change proposals.
-<p>Note that only the plain text part of the message is archived, and all
-attachments are stripped. Accordingly, messages sent to the
-mailing list should use text/plain encoding and not
-have any attachments.
-<h4>Use of github issues</h4>
-Note: according to the virtio TC rules, all official TC communication
-is taking place on one of the TC mailing lists.
-In particular, all comments must be provided on
-one of the TC mailing lists. Accordingly, the TC will not respond
-to comments provided in github issues: github issues are
-used solely to track integration of comments into the
-specification.<p>
+
+`sudo apt-get install texlive-full`
+
+OSX:
+
+OSX users don't need to install Tex-Live because they already have [MacTeX](http://www.tug.org/mactex/) installed.
+
+The build process generates a ZIP package file including the original TeX sources, as well as HTML and PDF formatted versions of the specification.
+
+To generate the ZIP package, run:
+
+`./makeall.sh`
+
+Troubleshooting notes:
+
+PDFs of the specification can be generated with either MicroSoft's Core fonts for the Web: Arial and Courier New, or Liberation fonts: Liberation Sans and Liberation Mono. Most systems come with one of these two variants included: should you get an error message about missing fonts, you will need to downloads and install one of the above font packages.
+
+#### Providing Feedback
+
+Feedback must be provided the **virtio-comment** mailing list, and archived in the mailing list archives.
+
+See [https://www.oasis-open.org/committees/tc\_home.php?wg\_abbrev=virtio#feedback](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=virtio#feedback)
+
+Note that only plain text part of the message is archived, and all attachments are stripped. Accordingly, messages sent to the mailing list should use text/plain encoding and not have any attachments.
+
+The preferred form of providing feedback is in form of a patch. A patch can be generated and sent by cloning the spec repository, creating a commit, formatting it as a patch and then sending it. For example:
+
+`git clone https://github.com/oasis-tcs/virtio-spec.git  
+... edit spec text, and save ...  
+`
+
+`git commit -a  
+... describe the proposed change, in the following format:  
+single line summary  
+  
+detailed description, including motivation for the change  
+  
+Signed-off-by: Name <email>  
+... then save and close the editor ...  
+`
+
+`git format-patch -o proposal1/ HEAD~1..  
+... generates a new directory proposal1/ and a file starting with 0001- ...  
+`
+
+`git send-email [email protected] proposal1/0001-*`
+
+#### Note for TC Members
+
+TC Members should review TC specific process rules under "Further Description of this Repository" in [https://github.com/oasis-tcs/virtio-admin](https://github.com/oasis-tcs/virtio-admin).
+
+#### Implementation discussion
+
+Implementation discussion should take place on the **virtio-dev** mailing list, and be archived in the mailing list archives.
+
+See [https://www.oasis-open.org/committees/tc\_home.php?wg\_abbrev=virtio#feedback](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=virtio#feedback)
+
+This is the correct list to copy on Linux virtio UAPI change proposals.
+
+Note that only the plain text part of the message is archived, and all attachments are stripped. Accordingly, messages sent to the mailing list should use text/plain encoding and not have any attachments.
+
+#### Use of github issues
+
+Note: according to the virtio TC rules, all official TC communication is taking place on one of the TC mailing lists. In particular, all comments must be provided on one of the TC mailing lists. Accordingly, the TC will not respond to comments provided in github issues: github issues are used solely to track integration of comments into the specification.
+
 To request a TC vote on resolving a specific comment:
-<ol>
-<li>Create a github issue, or edit an existing issue, with
-a short summary of the comment.
-The issue MUST specify
-the link to the latest proposal in the TC mailing list
-archives. <em>Note:</em> the link MUST be in the issue description itself -
-<em>not</em> in the comments.</li>
-<li>Reply by email to the comment email, requesting that the TC vote
-on resolving the issue.
-The mail requesting the vote should include the following, on a line by itself:<br>
-<code>
-Fixes: https://github.com/oasis-tcs/virtio-spec/issues/NNN
-</code>
-(NNN is the issue number)</li>
-<li>Please make sure to allow time for review between posting a comment
-and asking for a vote. </li>
-</ol>
-<h4>TC standing rules</h4>
+
+1.  Create a github issue, or edit an existing issue, with a short summary of the comment. The issue MUST specify the link to the latest proposal in the TC mailing list archives. _Note:_ the link MUST be in the issue description itself - _not_ in the comments.
+2.  Reply by email to the comment email, requesting that the TC vote on resolving the issue. The mail requesting the vote should include the following, on a line by itself:  
+    `Fixes: https://github.com/oasis-tcs/virtio-spec/issues/NNN` (NNN is the issue number)
+3.  Please make sure to allow time for review between posting a comment and asking for a vote.
+
+#### TC standing rules
+
 The TC adopted the following standing rule:
-<p>
-<em>
-Minor cleanups, including editorial formatting changes, spelling
-and typo fixes can be committed directly into git for approval as
-part of the next specification approval ballot.
-</em>
-<ol>
-<li>To request such a commit, reply by email to the comment email, requesting that the
-issue is resolved under the minor cleanups standing rule.
-</li>
-<li>Please make sure to allow time for review between posting a comment
-and asking for a commit. </li>
-</ol>
-
-<h3>Contact</h3>
-<p>Please send questions or comments about <a href="https://www.oasis-open.org/resources/tcadmin/github-repositories-for-oasis-tc-members-chartered-work">OASIS TC GitHub repositories</a> to <a href="mailto:[email protected]">Robin Cover</a> and <a href="mailto:[email protected]">Chet Ensign</a>.  For questions about content in this repository, please contact the TC Chair or Co-Chairs as listed on the the virtio TC's <a href="https://www.oasis-open.org/committees/virtio/">home page</a>.</p>
-</div>
+
+_Minor cleanups, including editorial formatting changes, spelling and typo fixes can be committed directly into git for approval as part of the next specification approval ballot._
+
+1.  To request such a commit, reply by email to the comment email, requesting that the issue is resolved under the minor cleanups standing rule.
+2.  Please make sure to allow time for review between posting a comment and asking for a commit.
+
+### Contact
+
+Please send questions or comments about [OASIS TC GitHub repositories](https://www.oasis-open.org/resources/tcadmin/github-repositories-for-oasis-tc-members-chartered-work) to [Robin Cover](mailto:[email protected]) and [Chet Ensign](mailto:[email protected]). For questions about content in this repository, please contact the TC Chair or Co-Chairs as listed on the the virtio TC's [home page](https://www.oasis-open.org/committees/virtio/).
Signature · 18 lines
2.20.1


This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/
#2 lore raw

[virtio-comment] Re: [virtio-dev] [RFC PATCH 1/8] README.md: convert html to proper Markdown format

Quoted 1 line · Alex Bennée

I don't mind, but OASIS admins asked us to keep the boiler plate as is. I assume it's fine as it's just re-formatting. Cc Robin Cover to make sure.

Quoted 289 lines
---
 README.md | 258 +++++++++++++++++++++---------------------------------
 1 file changed, 100 insertions(+), 158 deletions(-)
README.md +100 -158
index 2bdf485..8bb10e0 100644
@@ -1,173 +1,115 @@
-<div>
-<h2>README</h2>
+Members of the [OASIS Virtual I/O Device (VIRTIO) TC](https://www.oasis-open.org/committees/virtio/) create and manage technical content in this TC GitHub repository ( [https://github.com/oasis-tcs/virtio-spec](https://github.com/oasis-tcs/virtio-spec) ) as part of the TC's chartered work (_i.e._, the program of work and deliverables described in its [charter](https://www.oasis-open.org/committees/virtio/charter.php)).
 
-<p>Members of the <a href="https://www.oasis-open.org/committees/virtio/">OASIS Virtual I/O Device (VIRTIO) TC</a> create and manage technical content in this TC GitHub repository ( <a href="https://github.com/oasis-tcs/virtio-spec">https://github.com/oasis-tcs/virtio-spec</a> ) as part of the TC's chartered work (<i>i.e.</i>, the program of work and deliverables described in its <a href="https://www.oasis-open.org/committees/virtio/charter.php">charter</a>).</p>
+OASIS TC GitHub repositories, as described in [GitHub Repositories for OASIS TC Members' Chartered Work](https://www.oasis-open.org/resources/tcadmin/github-repositories-for-oasis-tc-members-chartered-work), are governed by the OASIS [TC Process](https://www.oasis-open.org/policies-guidelines/tc-process), [IPR Policy](https://www.oasis-open.org/policies-guidelines/ipr), and other policies, similar to TC Wikis, TC JIRA issues tracking instances, TC SVN/Subversion repositories, etc. While they make use of public GitHub repositories, these TC GitHub repositories are distinct from [OASIS Open Repositories](https://www.oasis-open.org/resources/open-repositories), which are used for development of open source [licensed](https://www.oasis-open.org/resources/open-repositories/licenses) content.
 
-<p>OASIS TC GitHub repositories, as described in <a href="https://www.oasis-open.org/resources/tcadmin/github-repositories-for-oasis-tc-members-chartered-work">GitHub Repositories for OASIS TC Members' Chartered Work</a>, are governed by the OASIS <a href="https://www.oasis-open.org/policies-guidelines/tc-process">TC Process</a>, <a href="https://www.oasis-open.org/policies-guidelines/ipr">IPR Policy</a>, and other policies, similar to TC Wikis, TC JIRA issues tracking instances, TC SVN/Subversion repositories, etc.  While they make use of public GitHub repositories, these TC GitHub repositories are distinct from <a href="https://www.oasis-open.org/resources/open-repositories">OASIS Open Repositories</a>, which are used for development of open source <a href="https://www.oasis-open.org/resources/open-repositories/licenses">licensed</a> content.</p>
-</div>
+### Description
 
-<div>
-<h3>Description</h3>
+This repository includes the [authoritative source](https://github.com/oasis-tcs/virtio-spec/releases) of the VIRTIO (Virtual I/O) Specification document. VIRTIO document describes the specifications of the "virtio" family of devices. These devices are found in virtual environments, yet by design they look like physical devices to the guest within the virtual machine — and this document treats them as such. This similarity allows the guest to use standard drivers and discovery mechanisms.
 
-<p>This repository includes the <a href="https://github.com/oasis-tcs/virtio-spec/releases">authoritative source</a> of the VIRTIO (Virtual I/O) Specification document. VIRTIO document describes the specifications of the "virtio" family of devices. These devices are found in virtual environments, yet by design they look like physical devices to the guest within the virtual machine &mdash; and this document treats them as such. This similarity allows the guest to use standard drivers and discovery mechanisms. </p>
+The purpose of virtio and this specification is that virtual environments and guests should have a straightforward, efficient, standard and extensible mechanism for virtual devices, rather than boutique per-environment or per-OS mechanisms.
 
-<p>The purpose of virtio and this specification is that virtual environments and guests should have a straightforward, efficient, standard and extensible mechanism for virtual devices, rather than boutique per-environment or per-OS mechanisms.</p>
-</div>
+### Contributions
 
-<div>
-<h3>Contributions</h3>
-<p>As stated in this repository's <a href="https://github.com/oasis-tcs/virtio-spec/blob/master/CONTRIBUTING.md">CONTRIBUTING file</a>, contributors to this repository are expected to be Members of the OASIS virtio TC, for any substantive change requests.  Anyone wishing to contribute to this GitHub project and <a href="https://www.oasis-open.org/join/participation-instructions">participate</a> in the TC's technical activity is invited to join as an OASIS TC Member.  Public feedback is also accepted, subject to the terms of the <a href="https://www.oasis-open.org/policies-guidelines/ipr#appendixa">OASIS Feedback License</a>.</p>
-</div>
+As stated in this repository's [CONTRIBUTING file](https://github.com/oasis-tcs/virtio-spec/blob/master/CONTRIBUTING.md), contributors to this repository are expected to be Members of the OASIS virtio TC, for any substantive change requests. Anyone wishing to contribute to this GitHub project and [participate](https://www.oasis-open.org/join/participation-instructions) in the TC's technical activity is invited to join as an OASIS TC Member. Public feedback is also accepted, subject to the terms of the [OASIS Feedback License](https://www.oasis-open.org/policies-guidelines/ipr#appendixa).
 
+### Licensing
 
+Please see the [LICENSE](https://github.com/oasis-tcs/virtio-spec/blob/master/LICENSE.md) file for description of the license terms and OASIS policies applicable to the TC's work in this GitHub project. Content in this repository is intended to be part of the virtio TC's permanent record of activity, visible and freely available for all to use, subject to applicable OASIS policies, as presented in the repository [LICENSE](https://github.com/oasis-tcs/virtio-spec/blob/master/LICENSE.md) file.
 
-<div>
-<h3>Licensing</h3>
-<p>Please see the <a href="https://github.com/oasis-tcs/virtio-spec/blob/master/LICENSE.md">LICENSE</a> file for description of the license terms and OASIS policies applicable to the TC's work in this GitHub project. Content in this repository is intended to be part of the virtio TC's permanent record of activity, visible and freely available for all to use, subject to applicable OASIS policies, as presented in the repository <a href="https://github.com/oasis-tcs/virtio-spec/blob/master/LICENSE.md">LICENSE</a> file.</p>
-</div>
+### Further Description of this Repository
 
-<div>
+#### Building Instructions
 
-<h3>Further Description of this Repository</h3>
-<h4>Building Instructions</h4>
-Authoritative version of the specification is maintained in the
-TeX document format. PDF and HTML versions are made available for
-ease of use and review.
-In order to build the HTML and PDF versions of the spec you will need the
-TeX document production system.
-The easiest way to get it up and running is probably by installing
-<a href="https://www.tug.org/texlive/">Tex-Live</a>.
+Authoritative version of the specification is maintained in the TeX document format. PDF and HTML versions are made available for ease of use and review. In order to build the HTML and PDF versions of the spec you will need the TeX document production system. The easiest way to get it up and running is probably by installing [Tex-Live](https://www.tug.org/texlive/).
+
+Installation cheat sheet:
+
+Fedora:
+
+`sudo dnf install texlive-scheme-full`
 
-<dl>Installation cheat sheet:
-<dt>Fedora:</dt>
-<dd>
-<code>
-sudo dnf install texlive-scheme-full
-</code></dd>
-<dt>
 Ubuntu and other Debian derivatives:
-</dt>
-<dd>
-<code>
-sudo apt-get install texlive-full
-</code></dd>
-<dt>OSX:<dt>
-<dd>OSX users don't need to install Tex-Live because they already have
-<a href="http://www.tug.org/mactex/">MacTeX</a> installed.
-</dd>
-</dl>
-<dl>The build process generates a ZIP package file including the
-original TeX sources, as well as HTML and PDF formatted
-versions of the specification.
-<dt>To generate the ZIP package, run:<dt>
-<dd>
-<code>
-./makeall.sh
-</code>
-</dd>
-<dt>Troubleshooting notes:</dt>
-<dd> PDFs of the specification can be generated with
-either MicroSoft's Core fonts for the Web: Arial and Courier New,
-or Liberation fonts: Liberation Sans and Liberation Mono.
-Most systems come with one of these two variants included:
-should you get an error message about missing fonts,
-you will need to downloads and install one of the above
-font packages.
-<dd>
-</dl>
-<h4>Providing Feedback</h4>
-Feedback must be provided the <strong>virtio-comment</strong> mailing list,
-and archived in the mailing list archives.
-<p>See <A
-HREF="https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=virtio#feedback">
-https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=virtio#feedback</A>
-<p>Note that only plain text part of the message is archived, and all
-attachments are stripped. Accordingly, messages sent to the
-mailing list should use text/plain encoding and not
-have any attachments.
-<p>The preferred form of providing feedback is in form of a patch.
-A patch can be generated and sent by cloning the spec repository,
-creating a commit, formatting it as a patch and then sending it.
-For example:
-<code>
-<p>
-git clone https://github.com/oasis-tcs/virtio-spec.git<br>
-... edit spec text, and save ...<br>
-<p>
-git commit -a<br>
-... describe the proposed change, in the following format:<br>
-single line summary<br>
-<br>
-detailed description, including motivation for the change<br>
-<br>
-Signed-off-by: Name &lt;email&gt;<br>
-... then save and close the editor ... <br>
-<p>
-git format-patch -o proposal1/ HEAD~1..<br>
-... generates a new directory proposal1/ and a file starting with 0001- ...<br>
-<p>
-git send-email [email protected] proposal1/0001-*
-</code>
-<h4>Note for TC Members</h4>
-<p>TC Members should review TC specific
-process rules under "Further Description of this Repository"
-in <A
-HREF="https://github.com/oasis-tcs/virtio-admin">https://github.com/oasis-tcs/virtio-admin</A>.
-
-</div>
-<h4>Implementation discussion</h4>
-Implementation discussion should take place on the <strong>virtio-dev</strong> mailing list,
-and be archived in the mailing list archives.
-<p>See <A
-HREF="https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=virtio#feedback">
-https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=virtio#feedback</A>
-<p>This is the correct list to copy on Linux virtio UAPI change proposals.
-<p>Note that only the plain text part of the message is archived, and all
-attachments are stripped. Accordingly, messages sent to the
-mailing list should use text/plain encoding and not
-have any attachments.
-<h4>Use of github issues</h4>
-Note: according to the virtio TC rules, all official TC communication
-is taking place on one of the TC mailing lists.
-In particular, all comments must be provided on
-one of the TC mailing lists. Accordingly, the TC will not respond
-to comments provided in github issues: github issues are
-used solely to track integration of comments into the
-specification.<p>
+
+`sudo apt-get install texlive-full`
+
+OSX:
+
+OSX users don't need to install Tex-Live because they already have [MacTeX](http://www.tug.org/mactex/) installed.
+
+The build process generates a ZIP package file including the original TeX sources, as well as HTML and PDF formatted versions of the specification.
+
+To generate the ZIP package, run:
+
+`./makeall.sh`
+
+Troubleshooting notes:
+
+PDFs of the specification can be generated with either MicroSoft's Core fonts for the Web: Arial and Courier New, or Liberation fonts: Liberation Sans and Liberation Mono. Most systems come with one of these two variants included: should you get an error message about missing fonts, you will need to downloads and install one of the above font packages.
+
+#### Providing Feedback
+
+Feedback must be provided the **virtio-comment** mailing list, and archived in the mailing list archives.
+
+See [https://www.oasis-open.org/committees/tc\_home.php?wg\_abbrev=virtio#feedback](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=virtio#feedback)
+
+Note that only plain text part of the message is archived, and all attachments are stripped. Accordingly, messages sent to the mailing list should use text/plain encoding and not have any attachments.
+
+The preferred form of providing feedback is in form of a patch. A patch can be generated and sent by cloning the spec repository, creating a commit, formatting it as a patch and then sending it. For example:
+
+`git clone https://github.com/oasis-tcs/virtio-spec.git  
+... edit spec text, and save ...  
+`
+
+`git commit -a  
+... describe the proposed change, in the following format:  
+single line summary  
+  
+detailed description, including motivation for the change  
+  
+Signed-off-by: Name <email>  
+... then save and close the editor ...  
+`
+
+`git format-patch -o proposal1/ HEAD~1..  
+... generates a new directory proposal1/ and a file starting with 0001- ...  
+`
+
+`git send-email [email protected] proposal1/0001-*`
+
+#### Note for TC Members
+
+TC Members should review TC specific process rules under "Further Description of this Repository" in [https://github.com/oasis-tcs/virtio-admin](https://github.com/oasis-tcs/virtio-admin).
+
+#### Implementation discussion
+
+Implementation discussion should take place on the **virtio-dev** mailing list, and be archived in the mailing list archives.
+
+See [https://www.oasis-open.org/committees/tc\_home.php?wg\_abbrev=virtio#feedback](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=virtio#feedback)
+
+This is the correct list to copy on Linux virtio UAPI change proposals.
+
+Note that only the plain text part of the message is archived, and all attachments are stripped. Accordingly, messages sent to the mailing list should use text/plain encoding and not have any attachments.
+
+#### Use of github issues
+
+Note: according to the virtio TC rules, all official TC communication is taking place on one of the TC mailing lists. In particular, all comments must be provided on one of the TC mailing lists. Accordingly, the TC will not respond to comments provided in github issues: github issues are used solely to track integration of comments into the specification.
+
 To request a TC vote on resolving a specific comment:
-<ol>
-<li>Create a github issue, or edit an existing issue, with
-a short summary of the comment.
-The issue MUST specify
-the link to the latest proposal in the TC mailing list
-archives. <em>Note:</em> the link MUST be in the issue description itself -
-<em>not</em> in the comments.</li>
-<li>Reply by email to the comment email, requesting that the TC vote
-on resolving the issue.
-The mail requesting the vote should include the following, on a line by itself:<br>
-<code>
-Fixes: https://github.com/oasis-tcs/virtio-spec/issues/NNN
-</code>
-(NNN is the issue number)</li>
-<li>Please make sure to allow time for review between posting a comment
-and asking for a vote. </li>
-</ol>
-<h4>TC standing rules</h4>
+
+1.  Create a github issue, or edit an existing issue, with a short summary of the comment. The issue MUST specify the link to the latest proposal in the TC mailing list archives. _Note:_ the link MUST be in the issue description itself - _not_ in the comments.
+2.  Reply by email to the comment email, requesting that the TC vote on resolving the issue. The mail requesting the vote should include the following, on a line by itself:  
+    `Fixes: https://github.com/oasis-tcs/virtio-spec/issues/NNN` (NNN is the issue number)
+3.  Please make sure to allow time for review between posting a comment and asking for a vote.
+
+#### TC standing rules
+
 The TC adopted the following standing rule:
-<p>
-<em>
-Minor cleanups, including editorial formatting changes, spelling
-and typo fixes can be committed directly into git for approval as
-part of the next specification approval ballot.
-</em>
-<ol>
-<li>To request such a commit, reply by email to the comment email, requesting that the
-issue is resolved under the minor cleanups standing rule.
-</li>
-<li>Please make sure to allow time for review between posting a comment
-and asking for a commit. </li>
-</ol>
-
-<h3>Contact</h3>
-<p>Please send questions or comments about <a href="https://www.oasis-open.org/resources/tcadmin/github-repositories-for-oasis-tc-members-chartered-work">OASIS TC GitHub repositories</a> to <a href="mailto:[email protected]">Robin Cover</a> and <a href="mailto:[email protected]">Chet Ensign</a>.  For questions about content in this repository, please contact the TC Chair or Co-Chairs as listed on the the virtio TC's <a href="https://www.oasis-open.org/committees/virtio/">home page</a>.</p>
-</div>
+
+_Minor cleanups, including editorial formatting changes, spelling and typo fixes can be committed directly into git for approval as part of the next specification approval ballot._
+
+1.  To request such a commit, reply by email to the comment email, requesting that the issue is resolved under the minor cleanups standing rule.
+2.  Please make sure to allow time for review between posting a comment and asking for a commit.
+
+### Contact
+
+Please send questions or comments about [OASIS TC GitHub repositories](https://www.oasis-open.org/resources/tcadmin/github-repositories-for-oasis-tc-members-chartered-work) to [Robin Cover](mailto:[email protected]) and [Chet Ensign](mailto:[email protected]). For questions about content in this repository, please contact the TC Chair or Co-Chairs as listed on the the virtio TC's [home page](https://www.oasis-open.org/committees/virtio/).
Signature · 6 lines
2.20.1


---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]

This publicly archived list offers a means to provide input to the OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and to minimize spam in the list archive, subscription is required before posting.

Subscribe: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/

#3 lore raw

RFC PATCH 2/8 CONTRIBUTING.md: convert to proper MarkDown

In reply to Alex Bennée
---
 CONTRIBUTING.md | 22 +++++++---------------
 1 file changed, 7 insertions(+), 15 deletions(-)
CONTRIBUTING.md +7 -15
index 1330a98..f07cb32 100644
@@ -1,20 +1,12 @@
-<div>
-<h2>Repository Contributions, Participation, and Public Access</h2>
+Repository Contributions, Participation, and Public Access
+----------------------------------------------------------
 
-<p><b>Who may Contribute?</b> Contributors to <a href="https://github.com/oasis-tcs/virtio-spec/">this repository</a> are expected to be <a href="https://www.oasis-open.org/policies-guidelines/oasis-defined-terms-2017-05-26#dMember">Members</a> of the
-<a href="https://www.oasis-open.org/committees/virtio/">OASIS Virtual I/O Device (VIRTIO) TC</a>, for any
-substantive contributions.  Anyone wishing to <a href="https://www.oasis-open.org/org/faq#committee-participation">participate</a>
-in the TC's technical activity is invited to <a href="https://www.oasis-open.org/committees/join">join</a> as a TC Member.
-<i>Member</i> in this context means any TC role or office other than OASIS TC Observer, per
-<a href="https://www.oasis-open.org/policies-guidelines/tc-process#membership">TC Process</a>
-(Member, Voting Member, Persistent Non-Voting Member; Chair, Secretary...)</p>
+**Who may Contribute?** Contributors to [this repository](https://github.com/oasis-tcs/virtio-spec/) are expected to be [Members](https://www.oasis-open.org/policies-guidelines/oasis-defined-terms-2017-05-26#dMember) of the [OASIS Virtual I/O Device (VIRTIO) TC](https://www.oasis-open.org/committees/virtio/), for any substantive contributions. Anyone wishing to [participate](https://www.oasis-open.org/org/faq#committee-participation) in the TC's technical activity is invited to [join](https://www.oasis-open.org/committees/join) as a TC Member. _Member_ in this context means any TC role or office other than OASIS TC Observer, per [TC Process](https://www.oasis-open.org/policies-guidelines/tc-process#membership) (Member, Voting Member, Persistent Non-Voting Member; Chair, Secretary...)
 
-<p>Persons who are not TC members are invited to open issues and provide comments using this repository's <a href="https://github.com/oasis-tcs/virtio-spec/issues/new">GitHub Issues</a> tracking facility or using the
-TC's <a href="https://www.oasis-open.org/committees/comments/index.php?wg_abbrev=virtio">comment list</a>.  All such content created in GitHub Issues and/or posted to the TC's <a href="https://lists.oasis-open.org/archives/virtio-comment/">archived comment list</a> is governed by the terms of the <a href="https://www.oasis-open.org/policies-guidelines/ipr#appendixa">OASIS Feedback License</a>.</p>
+Persons who are not TC members are invited to open issues and provide comments using this repository's [GitHub Issues](https://github.com/oasis-tcs/virtio-spec/issues/new) tracking facility or using the TC's [comment list](https://www.oasis-open.org/committees/comments/index.php?wg_abbrev=virtio). All such content created in GitHub Issues and/or posted to the TC's [archived comment list](https://lists.oasis-open.org/archives/virtio-comment/) is governed by the terms of the [OASIS Feedback License](https://www.oasis-open.org/policies-guidelines/ipr#appendixa).
 
-<p><b>Use of Contributions</b>.  As with all OASIS Technical Committee assets (TC <a href="https://wiki.oasis-open.org/">Wiki</a>, TC <a href="https://issues.oasis-open.org/secure/Dashboard.jspa">Issues Tracker</a>, TC <a href="https://lists.oasis-open.org/archives/">General Discussion List archives</a>, TC <a href="http://docs.oasis-open.org/">OASIS Library</a> assets), content placed into this GitHub repository is visible and publicly accessible.  Subject to applicable <a href="https://github.com/oasis-tcs/virtio-spec/blob/master/LICENSE.md">licensing</a> rules, the repository content may be re-used freely, including the creation and publication of derivative works.</p>
+**Use of Contributions**. As with all OASIS Technical Committee assets (TC [Wiki](https://wiki.oasis-open.org/), TC [Issues Tracker](https://issues.oasis-open.org/secure/Dashboard.jspa), TC [General Discussion List archives](https://lists.oasis-open.org/archives/), TC [OASIS Library](http://docs.oasis-open.org/) assets), content placed into this GitHub repository is visible and publicly accessible. Subject to applicable [licensing](https://github.com/oasis-tcs/virtio-spec/blob/master/LICENSE.md) rules, the repository content may be re-used freely, including the creation and publication of derivative works.
 
-<p><b>Cloning and forking</b>. May users clone and fork this repository?  Yes. Just as versioned content maintained in any OASIS TC's <a href="https://tools.oasis-open.org/version-control/browse/">SVN/Subversion repository</a> may be checked out to a remote SVN repository and used by anyone, this GitHub repository may be forked or cloned for use by any party.  Compare, <i>e.g.</i>, <tt>svn checkout https://tools.oasis-open.org/version-control/svn/dita/trunk/doctypes/ dita-doctypes</tt>.</p>
+**Cloning and forking**. May users clone and fork this repository? Yes. Just as versioned content maintained in any OASIS TC's [SVN/Subversion repository](https://tools.oasis-open.org/version-control/browse/) may be checked out to a remote SVN repository and used by anyone, this GitHub repository may be forked or cloned for use by any party. Compare, _e.g._, svn checkout https://tools.oasis-open.org/version-control/svn/dita/trunk/doctypes/ dita-doctypes.
 
-<p>Please see the <a href="https://github.com/oasis-tcs/virtio-spec/blob/master/README.md">README</a> for general description of this repository, and the <a href="https://github.com/oasis-tcs/virtio-spec/blob/master/LICENSE.md">LICENSE</a> file for licensing.</p>
-</div>
+Please see the [README](https://github.com/oasis-tcs/virtio-spec/blob/master/README.md) for general description of this repository, and the [LICENSE](https://github.com/oasis-tcs/virtio-spec/blob/master/LICENSE.md) file for licensing.
Signature · 18 lines
2.20.1


This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/
#4 lore raw

RFC PATCH 3/8 LICENSE.md: convert html to proper MarkDown

In reply to Alex Bennée
---
 LICENSE.md | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)
LICENSE.md +4 -5
index ef558ec..600b966 100644
@@ -1,7 +1,6 @@
-<div>
-<h2>License Terms</h2>
+License Terms
+-------------
 
-<p>Content in this GitHub code repository has been <a href="https://www.oasis-open.org/policies-guidelines/ipr#def-contribution">contributed</a> by OASIS TC Members, and is governed by the OASIS policies, including the <a href="https://www.oasis-open.org/policies-guidelines/ipr">Intellectual Property Rights (IPR) Policy</a>, the <a href="https://www.oasis-open.org/policies-guidelines/tc-process">Technical Committee (TC) Process</a>, <a href="https://www.oasis-open.org/policies-guidelines/bylaws">Bylaws</a>, and the Technical Committee's choice of <a href="https://www.oasis-open.org/policies-guidelines/ipr#def-ipr-mode">IPR Mode</a> (<i>viz</i>, <a href="https://www.oasis-open.org/policies-guidelines/ipr#Non-Assertion-Mode">Non-Assertion Mode</a>), including any applicable <a href="https://www.oasis-open.org/committees/virtio/ipr.php">declarations</a>. Feedback from non-TC members, if any, is governed by the terms of the <a href="https://www.oasis-open.org/policies-guidelines/ipr#appendixa">OASIS Feedback License</a>.</p>
+Content in this GitHub code repository has been [contributed](https://www.oasis-open.org/policies-guidelines/ipr#def-contribution) by OASIS TC Members, and is governed by the OASIS policies, including the [Intellectual Property Rights (IPR) Policy](https://www.oasis-open.org/policies-guidelines/ipr), the [Technical Committee (TC) Process](https://www.oasis-open.org/policies-guidelines/tc-process), [Bylaws](https://www.oasis-open.org/policies-guidelines/bylaws), and the Technical Committee's choice of [IPR Mode](https://www.oasis-open.org/policies-guidelines/ipr#def-ipr-mode) (_viz_, [Non-Assertion Mode](https://www.oasis-open.org/policies-guidelines/ipr#Non-Assertion-Mode)), including any applicable [declarations](https://www.oasis-open.org/committees/virtio/ipr.php). Feedback from non-TC members, if any, is governed by the terms of the [OASIS Feedback License](https://www.oasis-open.org/policies-guidelines/ipr#appendixa).
 
-<p>Description of this repository is presented in the <a href="https://github.com/oasis-tcs/virtio-spec/blob/master/README.md">README</a> file, and guidelines for contribution/participation are given in the <a href="https://github.com/oasis-tcs/virtio-spec/blob/master/CONTRIBUTING.md">CONTRIBUTING</a> file.</p>
-</div>
+Description of this repository is presented in the [README](https://github.com/oasis-tcs/virtio-spec/blob/master/README.md) file, and guidelines for contribution/participation are given in the [CONTRIBUTING](https://github.com/oasis-tcs/virtio-spec/blob/master/CONTRIBUTING.md) file.
Signature · 18 lines
2.20.1


This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/
#5 lore raw

RFC PATCH 4/8 makeall.sh: add explicit shebang to script

In reply to Alex Bennée
---
 makeall.sh | 2 ++
 1 file changed, 2 insertions(+)
makeall.sh +2 -0
index 20f568e..37e6c34 100755
@@ -1,3 +1,5 @@
+#!/bin/sh
+
 export SPECDOC=${SPECDOC:-`cat REVISION`}
 export DATESTR=${DATESTR:-`cat REVISION-DATE`}
 ./makezip.sh
Signature · 18 lines
2.20.1


This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/
Reviewed-by on v1 4/8
#6 lore raw

Re: [virtio-comment] [RFC PATCH 4/8] makeall.sh: add explicit shebang to script

Quoted 4 lines · On Fri, 27 Mar 2020 10:37:59 +0000 Alex Bennée <[email protected]> wrote:
---
 makeall.sh | 2 ++
 1 file changed, 2 insertions(+)

This publicly archived list offers a means to provide input to the OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and to minimize spam in the list archive, subscription is required before posting.

Subscribe: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/

#7 lore raw

RFC PATCH 5/8 Cleanup old changelog files

In reply to Alex Bennée

These are no longer included in the document although their contents will be forever available in the repositories history.

---
 cl-cs01.tex    |   86 ----
 cl-cs02.tex    |   52 ---
 cl-cs03.tex    |  328 ---------------
 cl-cs04.tex    |  134 -------
 cl-csprd02.tex | 1043 ------------------------------------------------
 cl-csprd03.tex |  400 -------------------
 6 files changed, 2043 deletions(-)
 delete mode 100644 cl-cs01.tex
 delete mode 100644 cl-cs02.tex
 delete mode 100644 cl-cs03.tex
 delete mode 100644 cl-cs04.tex
 delete mode 100644 cl-csprd02.tex
 delete mode 100644 cl-csprd03.tex
cl-cs01.tex deleted +0 -86
deleted file mode 100644
index 234e420..0000000
@@ -1,86 +0,0 @@
-418 & 11 Aug 2014 & Michael S. Tsirkin & { Acknowledge input from
-Brian Foley
-
-See \ref{chap:Acknowledgements}
-}
- \\
-417 & 11 Aug 2014 & Pawel Moll & {  VIRTIO-110: ARM's feedback for MMIO chapter, clarifications
-
-\begin{itemize}
-    \item Extra clarifications for QueueReady and ConfigGeneration
-    \item Added alignment requirement section, to formalise
-      hidden assumptions about register accesses
-\end{itemize}
-
-See \ref{sec:Virtio Transport Options / Virtio Over MMIO / MMIO
-Device Register Layout}, \ref{devicenormative:Virtio Transport
-Options / Virtio Over MMIO / MMIO Device Register Layout} and
-\ref{drivernormative:Virtio Transport
-Options / Virtio Over MMIO / MMIO Device Register Layout}
-}
- \\
-\hline
-\hline
-416 & 05 Aug 2014 & Pawel Moll & { VIRTIO-110: ARM's feedback for MMIO chapter, legacy section
-
-Make it clear that the legacy section is non-normative,
-removing all MUSTs.
-
-See \ref{sec:Virtio Transport Options / Virtio Over MMIO / Legacy
-interface}.
- } \\
-\hline
-415 & 05 Aug 2014 & Pawel Moll & { VIRTIO-110: ARM's feedback for MMIO chapter, trivial changes
-\begin{itemize}
-\item Typos and language mistakes in 4.2, 4.2.1, 4.2.2 and 4.2.2.2.
-\item Extra clarifications for InterruptACK.
-\end{itemize}
- } \\
-\hline
-414 & 04 Aug 2014 & Michael S. Tsirkin & { legacy: grammar fixup
-
-Legacy devices are "they" not "it".
-
-See \ref{sec:General Initialization And Device Operation / Device
-Initialization / Legacy Interface: Device Initialization}
-
-Resolves VIRTIO-113
- } \\
-\hline
-413 & 04 Aug 2014 & Michael S. Tsirkin & { legacy: consistently use past tense
-
-Paragraph with general description of feature negotiation
-for legacy devices mixed present and past tense.
-As rest of legacy sections all use past tense,
-fix the only instance of the present tense:
-s/do/did/ for consistency.
-
-It might be argued that legacy devices still have these
-properties so present tense is more appropriate, on the
-other hand, using the past tense helps stress the fact
-that current spec does not attempt to fully describe the legacy
-device/driver behaviour: this text is only here to serve as
-motivation for the transitional device/driver requirements.
-
-See \ref{sec:General Initialization And Device Operation / Device
-Initialization / Legacy Interface: Device Initialization}
-
-Resolves VIRTIO-112
- } \\
-\hline
-412 & 30 Jul 2014 & Michael S. Tsirkin & { VIRTIO-111: Fix minor typos
-
-Fix minor typos as reported in ARM's feedback.
-
-See \ref{drivernormative:Basic Facilities of a Virtio Device /
-Device Configuration Space}, \ref{sec:Basic Facilities of a
-Virtio Device / Device Configuration Space / Legacy Interface:
-Device Configuration Space}, \ref{sec:General Initialization And
-Device Operation / Device Operation / Supplying Buffers to The
-Device} and
-\ref{drivernormative:Device Types / Network Device / Device
-Operation / Control Virtqueue / Offloads State Configuration /
-Setting Offloads State}
- }
- \\
-\hline
cl-cs02.tex deleted +0 -52

52 lines not on this page · raw message

cl-cs03.tex deleted +0 -328

328 lines not on this page · raw message

cl-cs04.tex deleted +0 -134

134 lines not on this page · raw message

cl-csprd02.tex deleted +0 -1043

1,043 lines not on this page · raw message

cl-csprd03.tex deleted +0 -400

400 lines not on this page · raw message

Signature · 18 lines
2.20.1


This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/
#8 lore raw

RFC PATCH 6/8 Remove all mentioned of subversion

In reply to Alex Bennée

The repo hasn't been hosted in subversion for a while so the documents are no longer relevant to working with the repo. Also remove the unused code in the makezip.sh tool.

---
 getchangelog.pl | 114 ------------------------------------------------
 git-svn.txt     |  34 ---------------
 makezip.sh      |   9 +---
 3 files changed, 1 insertion(+), 156 deletions(-)
 delete mode 100755 getchangelog.pl
 delete mode 100644 git-svn.txt
getchangelog.pl deleted +0 -114
deleted file mode 100755
index 5619ce4..0000000
@@ -1,114 +0,0 @@
-#!/usr/bin/perl
-
-use strict;
-
-my $rev = undef;
-if ($#ARGV >= 0) {
-	$rev = shift @ARGV;
-} else {
-	open(REV, "git svn log REVISION|") || die;
-	while (<REV>) {
-		next unless (m/^(r[0-9]+)/);
-		#top revision is WD, skip it
-		if (not defined $rev) {
-			$rev = $1;
-			next;
-		} else {
-			$rev = $1;
-			last;
-		}
-	}
-}
-
-die unless $rev =~ m/^r([0-9]+)$/;
-$rev = $1;
-
-sub escapelatex {
-	my $s = shift;
-	$s =~ s/[\\]/\\textbackslash /go;
-	$s =~ s/([&#%{}\$])/\\$1/go;
-	$s =~ s/[~]/\\~{}/go;
-	$s =~ s/(https?:\S*)/\\url{$1}/go;
-#1st line always on a separate paragraph
-	$s =~ s/\n/\n\n/o;
-#Guess where new paragraph starts
-	$s =~ s/\\.\n/.\n\n/go;
-	$s =~ s/\n-/\n\n-/go;
-	return $s;
-}
-
-#map editors to authors
-my %editors = {};
-$editors{'rusty'} = 'Rusty Russell <[email protected]>';
-$editors{'hornet'} = 'Pawel Moll <[email protected]>';
-$editors{'cornelia.huck'} = 'Cornelia Huck <[email protected]>';
-$editors{'mstsirkin'} = 'Michael S. Tsirkin <[email protected]>';
-
-my $cl = "";
-my $signoff = undef;
-my $editor = undef;
-my $date = undef;
-my $r = undef;
-open(LOG, "git svn log *tex|") || die;
-my $line = undef;
-while (<LOG>) {
-	if (m/^------------------------------------------------------------------------$/) {
-		next if ($cl eq "");
-		# act on it
-		my $author;
-		if (defined $signoff) {
-			$author = $signoff;
-		} else {
-			$author = $editors{$editor};
-		}
-		#strip mail info
-		$author =~ s/\s*<.*//;
-		$cl = escapelatex($cl);
-		print "$r & $date & $author & { $cl } \\\\\n";
-		print "\\hline\n";
-
-		$cl = "";
-		$signoff = undef;
-		$editor = undef;
-		$date = undef;
-		$r = undef;
-
-		$line = 0;
-		next;
-	}
-	$line++;
-#r164 | mstsirkin | 2013-12-08 14:30:55 +0200 (Sun, 08 Dec 2013)| 6 lines
-
-	if ($line eq 1) {
-		die unless (m/^r[0-9]/);
-		my @rinfo = split(/\s*\Q|\E\s*/, $_);
-		$r = $rinfo[0];
-
-		die unless $r =~ m/^r([0-9]+)$/;
-		$r = $1;
-		last if ($r <= $rev);
-
-		$editor = $rinfo[1];
-		$date = $rinfo[2];
-		die unless ($date =~ m/^[^(]*\([^,]*,\s*([^)]+)\)\s*$/);
-		$date = $1;
-		next;
-	}
-	next if (m/^$/);
-
-	# First signature is the author: needed?
-	# ignore for now
-	#if (not defined $signoff and m/^Signed-off-by:\s*(.*)/) {
-	#	$signoff = $1;
-	#}
-	# skip signatures
-	next if (m/^\s*[A-Z][A-Za-z-]*-by:/);
-
-
-	# fix bug: wrong date in some commit logs
-	if (/Change accepted on VIRTIO TC Meeting, 3 December 2013/) {
-		$_ = "Change accepted on Virtio TC Meeting Minutes: Feb 25, 2014\n";
-	}
-
-	$cl .= $_;
-}
git-svn.txt deleted +0 -34
deleted file mode 100644
index e094217..0000000
@@ -1,34 +0,0 @@
-Using git svn with virtio svn repository:
-
-Initial clone (fetches all branches, takes a very long time):
-        git svn clone -s https://tools.oasis-open.org/version-control/svn/virtio
-Pull:
-        git svn rebase
-Push:
-        git svn dcommit
-
-Tagging 1.0 cs02 to match the released specification:
-        git branch -t v1.0-cs02
-
-Updating the trunk with all changes made on 1.0 branch:
-
-	git config --global svn.pushmergeinfo true
-	git checkout -b master origin/trunk
-	git svn fetch
-	git svn rebase -l
-	git merge --no-ff origin/v1.0
-		[ resolve merge conflicts ]
-	git svn dcommit
-
-Faster initial clone from git mirror (example using mst's mirror at kernel.org):
-
-	git clone git://git.kernel.org/pub/scm/virt/kvm/mst/virtio-text.git
-	cd virtio-text
-	git config --remove-section remote.origin
-	git svn init -s https://tools.oasis-open.org/version-control/svn/virtio
-	git svn rebase
-	git checkout -b trunk origin/trunk
-
-Updating a git mirror from git-svn repository (after setting up a
-remote named "mirror"):
-	git push mirror --prune +refs/remotes/origin/*:refs/heads/*
makezip.sh +1 -8
index 3c94f8e..806fa52 100755
@@ -3,15 +3,8 @@ export DATESTR=${DATESTR:-`cat REVISION-DATE`}
 rm -f $SPECDOC.zip
 if test -d .git; then
 	git archive --format=zip --prefix=tex/ -o $SPECDOC.zip HEAD
-elif test -d .svn; then
-	rm -fr export-from-svn
-	mkdir -p export-from-svn
-	svn export . export-from-svn/tex
-	cd export-from-svn/
-	zip ../$SPECDOC.zip tex/
-	cd ..
 else
-	echo Neither .git nor .svn found.
+	echo .git not found.
 	echo Falling back to generated list.
 fi
 zip -d $SPECDOC.zip tex/.gitattributes
Signature · 18 lines
2.20.1


This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/
#9 lore raw

RFC PATCH 7/8 make*: remove reliance on REVISION-DATE and use git

In reply to Alex Bennée

Rather than manually tweaking REVISION-DATE and loading it into DATESTR move all the logic into make-setup-generated.sh. While we are at it we can query git directly for the state of tree and use that to fill in the meta-data.

---
 REVISION-DATE           |  1 -
 make-setup-generated.sh | 54 +++++++++++++++++++++++++++++------------
 makeall.sh              |  1 -
 makediff.sh             |  1 -
 makediffall.sh          |  1 -
 makediffwithbase.sh     |  1 -
 maketex.sh              |  1 -
 makezip.sh              |  2 --
 8 files changed, 38 insertions(+), 24 deletions(-)
 delete mode 100644 REVISION-DATE
REVISION-DATE deleted +0 -1
deleted file mode 100644
index 59c9d17..0000000
@@ -1 +0,0 @@
-11 April 2019
make-setup-generated.sh +38 -16

84 lines not on this page · raw message

makeall.sh +0 -1
index 37e6c34..1e25b82 100755
@@ -1,7 +1,6 @@
 #!/bin/sh
 
 export SPECDOC=${SPECDOC:-`cat REVISION`}
-export DATESTR=${DATESTR:-`cat REVISION-DATE`}
 ./makezip.sh
 ./makehtml.sh
 ./makepdf.sh
makediff.sh +0 -1
index ef538c5..03f6731 100755
@@ -1,7 +1,6 @@
 #force revision and date in environment
 #this way they don't appear in the diff
 export SPECDOC=${SPECDOC:-`cat REVISION`}
-export DATESTR=${DATESTR:-`cat REVISION-DATE`}
 export FROMVERSION=${FROMVERSION:-`cat DIFFVERSION`}
 
 #make pdf diff using latexpand and latexdiff-fast
makediffall.sh +0 -1
index caff23e..f1a3333 100755
@@ -1,5 +1,4 @@
 export SPECDOC=${SPECDOC:-`cat REVISION`}
-export DATESTR=${DATESTR:-`cat REVISION-DATE`}
 export FROMVERSION=${FROMVERSION:-`cat DIFFVERSION`}
 ./makezip.sh
 mv -f $SPECDOC.zip $SPECDOC-diff-from-${FROMVERSION}.pdf
makediffwithbase.sh +0 -1
index 8cd3c7a..3916c83 100755
@@ -1,5 +1,4 @@
 export SPECDOC=${SPECDOC:-`cat REVISION`}
-export DATESTR=${DATESTR:-`cat REVISION-DATE`}
 ./makezip.sh
 ./makehtml.sh
 ./makepdf.sh
maketex.sh +0 -1
index c3b458f..1fee32b 100755
@@ -1,3 +1,2 @@
 export SPECDOC=${SPECDOC:-`cat REVISION`}-tex
-export DATESTR=${DATESTR:-`cat REVISION-DATE`}
 ./makezip.sh
makezip.sh +0 -2
index 806fa52..40b13cc 100755
@@ -1,5 +1,4 @@
 export SPECDOC=${SPECDOC:-`cat REVISION`}
-export DATESTR=${DATESTR:-`cat REVISION-DATE`}
 rm -f $SPECDOC.zip
 if test -d .git; then
 	git archive --format=zip --prefix=tex/ -o $SPECDOC.zip HEAD
@@ -15,6 +14,5 @@ zip $SPECDOC.zip listings/virtio_queue.h
 rm -fr tmpfilesforzip
 mkdir -p tmpfilesforzip/tex
 echo "$SPECDOC" > tmpfilesforzip/tex/REVISION
-echo "$DATESTR" > tmpfilesforzip/tex/REVISION-DATE
 cd tmpfilesforzip
 zip ../$SPECDOC.zip tex/*
Signature · 18 lines
2.20.1


This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/
#10 lore raw

RFC PATCH 7/8 make*: remove reliance on REVISION-DATE and use git]

Forgot to Cc list by mistake.
Apropos, please do not copy both virtio-dev and virtio-comment. virtio-dev is for implementation, virtio-comment for spec feedback.

----- Forwarded message from "Michael S. Tsirkin" <[email protected]> -----

Date: Thu, 30 Apr 2020 03:44:57 -0400
From: "Michael S. Tsirkin" <[email protected]>
To: Alex Bennée <[email protected]>
Subject: Re: [virtio-comment] [RFC PATCH 7/8] make*: remove reliance on REVISION-DATE and use git
Message-ID: <[email protected]>
In-Reply-To: <[email protected]>

Quoted 6 lines · Alex Bennée

Rather than manually tweaking REVISION-DATE and loading it into DATESTR move all the logic into make-setup-generated.sh. While we are at it we can query git directly for the state of tree and use that to fill in the meta-data.

I frankly find it more robust not to depend on current date, git tags, or anything like this. People should be able to generate exactly the same pdf/html from same sources without effort. Additionally, it needs to be possible to build from tarball, not just from git.

One exception where it's not possible ATM is with redline, that requires git. Would be nice to fix.

Quoted 197 lines
---
 REVISION-DATE           |  1 -
 make-setup-generated.sh | 54 +++++++++++++++++++++++++++++------------
 makeall.sh              |  1 -
 makediff.sh             |  1 -
 makediffall.sh          |  1 -
 makediffwithbase.sh     |  1 -
 maketex.sh              |  1 -
 makezip.sh              |  2 --
 8 files changed, 38 insertions(+), 24 deletions(-)
 delete mode 100644 REVISION-DATE
REVISION-DATE deleted +0 -1
deleted file mode 100644
index 59c9d17..0000000
@@ -1 +0,0 @@
-11 April 2019
make-setup-generated.sh +38 -16
index f15d148..2faea0b 100755
@@ -1,39 +1,61 @@
 #! /bin/sh
+#
+# Generate version and metadata preamble for the document
+#
 
-VERSION=1.1
-DATESTR=${DATESTR:-`cat REVISION-DATE 2>/dev/null`}
-if [ x"$DATESTR" = x ]; then
-    ISODATE=`git show --format=format:'%cd' --date=iso | head -n 1`
-    DATESTR=`date -d "$DATE" +'%d %B %Y'`
+# Currently this works of the closest lightweight tag but we can
+# update this when we start using proper signed and annotated tags.
+TAG=$(git describe 2> /dev/null)
+if [ x"$TAG" = x ]; then
+    # no tag on head
+    TAG=$(git describe --dirty --tags)
+    # base date on now
+    DATESTR=$(date +'%d %B %Y')
+    COMMIT=$(git rev-parse --short HEAD)
+else
+    # base date on tag
+    DATESTR=$(git log HEAD^..HEAD --format=format:"%cd" --date=format:"%d %B %Y")
+    COMMIT=""
+fi
+
+VERSION=$(cut -d'-' -f2 <<EOF
+$TAG
+EOF
+       )
+
+# Finally check if we have un-committed changes in the tree
+if git diff-index --quiet HEAD -- ; then
+    COMMIT="$COMMIT with local changes"
+fi
+
+if [ x"$COMMIT" = x ]; then
+    WORKINGDRAFT=""
+else
+    WORKINGDRAFT=" (@ git $COMMIT)"
 fi
 
 case "$1" in
     *-wd*)
 	STAGE=wd
 	STAGENAME="Working Draft"
-	WORKINGDRAFT=`basename "$1" | sed 's/.*-wd//'`
 	;;
     *-os*)
 	STAGE=os
 	STAGENAME="OASIS Standard"
-	WORKINGDRAFT=""
 	;;
     *-csd*)
 	STAGE=csd
-	WORKINGDRAFT=`basename "$1" | sed 's/.*-csd//'`
-	STAGENAME="Committee Specification Draft $WORKINGDRAFT"
+	STAGENAME="Committee Specification Draft$WORKINGDRAFT"
 	;;
     *-csprd*)
 	STAGE=csprd
-	WORKINGDRAFT=`basename "$1" | sed 's/.*-csprd//'`
-	STAGENAME="Committee Specification Draft $WORKINGDRAFT"
-	STAGEEXTRATITLE=" / \newline Public Review Draft $WORKINGDRAFT"
-	STAGEEXTRA=" / Public Review Draft $WORKINGDRAFT"
+	STAGENAME="Committee Specification Draft$WORKINGDRAFT"
+	STAGEEXTRATITLE=" / \newline Public Review Draft$WORKINGDRAFT"
+	STAGEEXTRA=" / Public Review Draft$WORKINGDRAFT"
 	;;
     *-cs*)
 	STAGE=cs
-	WORKINGDRAFT=`basename "$1" | sed 's/.*-cs//'`
-	STAGENAME="Committee Specification $WORKINGDRAFT"
+	STAGENAME="Committee Specification$WORKINGDRAFT"
 	;;
     *)
 	echo Unknown doc type >&2
@@ -54,7 +76,7 @@ cat > setup-generated.tex <<EOF
 % define VIRTIO Working Draft number and date
 \newcommand{\virtiorev}{$VERSION}
 \newcommand{\virtioworkingdraftdate}{$DATESTR}
-\newcommand{\virtioworkingdraft}{$WORKINGDRAFT}
+\newcommand{\virtioworkingdraft}{$COMMIT}
 \newcommand{\virtiodraftstage}{$STAGE}
 \newcommand{\virtiodraftstageextra}{$STAGEEXTRA}
 \newcommand{\virtiodraftstageextratitle}{$STAGEEXTRATITLE}
makeall.sh +0 -1
index 37e6c34..1e25b82 100755
@@ -1,7 +1,6 @@
 #!/bin/sh
 
 export SPECDOC=${SPECDOC:-`cat REVISION`}
-export DATESTR=${DATESTR:-`cat REVISION-DATE`}
 ./makezip.sh
 ./makehtml.sh
 ./makepdf.sh
makediff.sh +0 -1
index ef538c5..03f6731 100755
@@ -1,7 +1,6 @@
 #force revision and date in environment
 #this way they don't appear in the diff
 export SPECDOC=${SPECDOC:-`cat REVISION`}
-export DATESTR=${DATESTR:-`cat REVISION-DATE`}
 export FROMVERSION=${FROMVERSION:-`cat DIFFVERSION`}
 
 #make pdf diff using latexpand and latexdiff-fast
makediffall.sh +0 -1
index caff23e..f1a3333 100755
@@ -1,5 +1,4 @@
 export SPECDOC=${SPECDOC:-`cat REVISION`}
-export DATESTR=${DATESTR:-`cat REVISION-DATE`}
 export FROMVERSION=${FROMVERSION:-`cat DIFFVERSION`}
 ./makezip.sh
 mv -f $SPECDOC.zip $SPECDOC-diff-from-${FROMVERSION}.pdf
makediffwithbase.sh +0 -1
index 8cd3c7a..3916c83 100755
@@ -1,5 +1,4 @@
 export SPECDOC=${SPECDOC:-`cat REVISION`}
-export DATESTR=${DATESTR:-`cat REVISION-DATE`}
 ./makezip.sh
 ./makehtml.sh
 ./makepdf.sh
maketex.sh +0 -1
index c3b458f..1fee32b 100755
@@ -1,3 +1,2 @@
 export SPECDOC=${SPECDOC:-`cat REVISION`}-tex
-export DATESTR=${DATESTR:-`cat REVISION-DATE`}
 ./makezip.sh
makezip.sh +0 -2
index 806fa52..40b13cc 100755
@@ -1,5 +1,4 @@
 export SPECDOC=${SPECDOC:-`cat REVISION`}
-export DATESTR=${DATESTR:-`cat REVISION-DATE`}
 rm -f $SPECDOC.zip
 if test -d .git; then
 	git archive --format=zip --prefix=tex/ -o $SPECDOC.zip HEAD
@@ -15,6 +14,5 @@ zip $SPECDOC.zip listings/virtio_queue.h
 rm -fr tmpfilesforzip
 mkdir -p tmpfilesforzip/tex
 echo "$SPECDOC" > tmpfilesforzip/tex/REVISION
-echo "$DATESTR" > tmpfilesforzip/tex/REVISION-DATE
 cd tmpfilesforzip
 zip ../$SPECDOC.zip tex/*
Signature · 18 lines
2.20.1


This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/

----- End forwarded message -----

This publicly archived list offers a means to provide input to the OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and to minimize spam in the list archive, subscription is required before posting.

Subscribe: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/

#11 lore raw

RFC PATCH 8/8 Makefile: add simple make automation with clean target

In reply to Alex Bennée

This will remove all intermediate files in the checkout.

---
 Makefile | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)
 create mode 100644 Makefile
Makefile new file +17 -0
new file mode 100644
index 0000000..f11d871
@@ -0,0 +1,17 @@
+# -*- Mode: makefile -*-
+#
+# Basic Makefile to aid automation of document building
+#
+
+.PHONY: help
+help:
+	@echo "Build the VIRTIO specification documents."
+	@echo ""
+	@echo "Possible operations are:"
+	@echo
+	@echo " $(MAKE) clean                Remove all intermediate files"
+
+
+.PHONY: clean
+clean:
+	@rm -f (git ls-files --others --exclude-standard)
Signature · 18 lines
2.20.1


This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/
#12 lore raw

Re: [virtio-comment] [RFC PATCH 8/8] Makefile: add simple make automation with clean target

Quoted 19 lines · Alex Bennée

This will remove all intermediate files in the checkout.

---
 Makefile | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)
 create mode 100644 Makefile
Makefile new file +7 -0
new file mode 100644
index 0000000..f11d871
@@ -0,0 +1,17 @@
+# -*- Mode: makefile -*-
+#
+# Basic Makefile to aid automation of document building
+#
+
+.PHONY: help
+help:

Makefile line 17

Quoted 10 lines
Makefile new file +10 -0
+	@echo "Build the VIRTIO specification documents."
+	@echo ""
+	@echo "Possible operations are:"
+	@echo
+	@echo " $(MAKE) clean                Remove all intermediate files"
+
+
+.PHONY: clean
+clean:
+	@rm -f (git ls-files --others --exclude-standard)

This makefile is not going to work in a tarball, so how about just a shell script for now? E.g. makegitclean.sh?

Quoted 19 lines
Signature · 18 lines
2.20.1


This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/

This publicly archived list offers a means to provide input to the OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and to minimize spam in the list archive, subscription is required before posting.

Subscribe: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/

#13 lore raw
In reply to Alex Bennée
Quoted 8 lines · On Fri, 27 Mar 2020 10:37:55 +0000 Alex Bennée <[email protected]> wrote:

Hi,

I was reviewing someones virtio-spec and realised that I wasn't quite sure what it had been built from. Seeing as the standard is hosted in git I've tried to clean up some of the automation to make it clearer what a particular rendering was built from. Going forward it would be nice to use signed annotated tags for the final build version but I don't know how much of the boilerplate is down to OASIS requirements.

OASIS requirements are my concern here as well.

Quoted 7 lines

What do people think? Is this worth improving on?

Alex Bennée (8):
README.md: convert html to proper Markdown format CONTRIBUTING.md: convert to proper MarkDown LICENSE.md: convert html to proper MarkDown

We should double-check first if the html snippets in there are sourced into some official web page somewhere. If not, I'm all for converting this.

Quoted 2 lines

makeall.sh: add explicit shebang to script
Cleanup old changelog files

I'm not sure if there are any requirements for keeping this -- even if they are available in the history forever.

Quoted 1 line

Remove all mentioned of subversion

That's probably fine.

Quoted 26 lines

make*: remove reliance on REVISION-DATE and use git
Makefile: add simple make automation with clean target

 CONTRIBUTING.md         |   22 +-
 LICENSE.md              |    9 +-
 Makefile                |   17 +
 README.md               |  258 ++++------
 REVISION-DATE           |    1 -
 cl-cs01.tex             |   86 ----
 cl-cs02.tex             |   52 --
 cl-cs03.tex             |  328 ------------
 cl-cs04.tex             |  134 -----
 cl-csprd02.tex          | 1043 ---------------------------------------
 cl-csprd03.tex          |  400 ---------------
 getchangelog.pl         |  114 -----
 git-svn.txt             |   34 --
 make-setup-generated.sh |   54 +-
 makeall.sh              |    3 +-
 makediff.sh             |    1 -
 makediffall.sh          |    1 -
 makediffwithbase.sh     |    1 -
 maketex.sh              |    1 -
 makezip.sh              |   11 +-
 20 files changed, 169 insertions(+), 2401 deletions(-)
 create mode 100644 Makefile
 delete mode 100644 REVISION-DATE
Quoted 9 lines
 delete mode 100644 cl-cs01.tex
 delete mode 100644 cl-cs02.tex
 delete mode 100644 cl-cs03.tex
 delete mode 100644 cl-cs04.tex
 delete mode 100644 cl-csprd02.tex
 delete mode 100644 cl-csprd03.tex
 delete mode 100755 getchangelog.pl
 delete mode 100644 git-svn.txt

This publicly archived list offers a means to provide input to the OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and to minimize spam in the list archive, subscription is required before posting.

Subscribe: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/

#14 lore raw
Quoted 5 lines · Cornelia Huck
Quoted 2 lines · On Fri, 27 Mar 2020 10:37:55 +0000 Alex Bennée <[email protected]> wrote:

Hi,

Quoted 8 lines
Quoted 6 lines

I was reviewing someones virtio-spec and realised that I wasn't quite sure what it had been built from. Seeing as the standard is hosted in git I've tried to clean up some of the automation to make it clearer what a particular rendering was built from. Going forward it would be nice to use signed annotated tags for the final build version but I don't know how much of the boilerplate is down to OASIS requirements.

OASIS requirements are my concern here as well.

I've tried to do some digging although the Oasis website has a lot of policy documents. I think the most relevant one is:

https://docs.oasis-open.org/specGuidelines/ndr/namingDirectives.html

which as far as I can make out is mostly concerned that the final work product meets the naming standard by version and stage. Although ZIP files are mentioned a couple of times it is in the context of a file containing work products for local use. My personal interpretation is that if the final work products are correctly named and have the version information in them the rest is just ephemera. However I could be wrong so defer to anyone more familiar with the policies.

An random sampling of ZIP files on https://www.oasis-open.org/standards
has shown them all to just contain the individual work products without any extraneous REVISION/REVISION-DATE files.

Anyway I defer to those with more experience of the process and I'll leave the question of tex vs rst for another day ;-)

Signature · 17 lines
Alex Bennée

This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/
#15 lore raw
In reply to Alex Bennée
Quoted 10 lines · Alex Bennée

Hi,

I was reviewing someones virtio-spec and realised that I wasn't quite sure what it had been built from. Seeing as the standard is hosted in git I've tried to clean up some of the automation to make it clearer what a particular rendering was built from. Going forward it would be nice to use signed annotated tags for the final build version but I don't know how much of the boilerplate is down to OASIS requirements.

What do people think? Is this worth improving on?

Ping? Any other feedback?

Quoted 8 lines

Alex Bennée (8):
README.md: convert html to proper Markdown format CONTRIBUTING.md: convert to proper MarkDown LICENSE.md: convert html to proper MarkDown makeall.sh: add explicit shebang to script Cleanup old changelog files
Remove all mentioned of subversion
make*: remove reliance on REVISION-DATE and use git

I've been looking at other OASIS zipfiles and I think I could dump REVISION as well as it's all in the rendered docs.

Quoted 33 lines

Makefile: add simple make automation with clean target

 CONTRIBUTING.md         |   22 +-
 LICENSE.md              |    9 +-
 Makefile                |   17 +
 README.md               |  258 ++++------
 REVISION-DATE           |    1 -
 cl-cs01.tex             |   86 ----
 cl-cs02.tex             |   52 --
 cl-cs03.tex             |  328 ------------
 cl-cs04.tex             |  134 -----
 cl-csprd02.tex          | 1043 ---------------------------------------
 cl-csprd03.tex          |  400 ---------------
 getchangelog.pl         |  114 -----
 git-svn.txt             |   34 --
 make-setup-generated.sh |   54 +-
 makeall.sh              |    3 +-
 makediff.sh             |    1 -
 makediffall.sh          |    1 -
 makediffwithbase.sh     |    1 -
 maketex.sh              |    1 -
 makezip.sh              |   11 +-
 20 files changed, 169 insertions(+), 2401 deletions(-)
 create mode 100644 Makefile
 delete mode 100644 REVISION-DATE
 delete mode 100644 cl-cs01.tex
 delete mode 100644 cl-cs02.tex
 delete mode 100644 cl-cs03.tex
 delete mode 100644 cl-cs04.tex
 delete mode 100644 cl-csprd02.tex
 delete mode 100644 cl-csprd03.tex
 delete mode 100755 getchangelog.pl
 delete mode 100644 git-svn.txt
Signature · 17 lines
Alex Bennée

This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/