[virtio-comment] [PATCH v2 0/7] doc build updates and terminology definitions

[virtio-comment] [PATCH v2 0/7] doc build updates and terminology definitions

[Alex Bennée]

Hi,

This contains both my previously posted build system tweaks and an
updated revision of the terminology patch I posted last week with a
further patch to tighten up the language in the Notifications section.

Alex Bennée (7):
  README.md: convert html to proper Markdown format
  CONTRIBUTING.md: convert html to proper MarkDown
  LICENSE.md: convert html to proper MarkDown
  Makefile: add some simple make automations
  make-setup-generated: optionally add GIT metadata
  introduction.tex: introduce a glossary of terms
  content.tex: tighten up the definition of notification.

 CONTRIBUTING.md         |  22 ++--
 LICENSE.md              |   9 +-
 Makefile                |  26 ++++
 README.md               | 258 ++++++++++++++++------------------------
 content.tex             |   8 +-
 introduction.tex        |  21 ++++
 make-setup-generated.sh |  34 +++++-
 makehtml.sh             |   2 +-
 8 files changed, 194 insertions(+), 186 deletions(-)
 create mode 100644 Makefile

-- 
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: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
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/

[virtio-comment] [PATCH v2 0/7] doc build updates and terminology definitions

[Alex Bennée]

Hi,

This contains both my previously posted build system tweaks and an
updated revision of the terminology patch I posted last week with a
further patch to tighten up the language in the Notifications section.

Alex Bennée (7):
  README.md: convert html to proper Markdown format
  CONTRIBUTING.md: convert html to proper MarkDown
  LICENSE.md: convert html to proper MarkDown
  Makefile: add some simple make automations
  make-setup-generated: optionally add GIT metadata
  introduction.tex: introduce a glossary of terms
  content.tex: tighten up the definition of notification.

 CONTRIBUTING.md         |  22 ++--
 LICENSE.md              |   9 +-
 Makefile                |  26 ++++
 README.md               | 258 ++++++++++++++++------------------------
 content.tex             |   8 +-
 introduction.tex        |  21 ++++
 make-setup-generated.sh |  34 +++++-
 makehtml.sh             |   2 +-
 8 files changed, 194 insertions(+), 186 deletions(-)
 create mode 100644 Makefile

-- 
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: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
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/

[virtio-comment] [PATCH v2 1/7] README.md: convert html to proper Markdown format

[Alex Bennée]

There is no point embedding HTML inside the markdown document. It just
makes it messy to edit. The boilerplate text is maintained.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Cc: Robin Cover <robin@oasis-open.org>
---
 README.md | 258 +++++++++++++++++++++---------------------------------
 1 file changed, 100 insertions(+), 158 deletions(-)

diff --git a/README.md b/README.md
index 2bdf485..8bb10e0 100644
--- a/README.md
+++ b/README.md
@@ -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 --to=virtio-comment@lists.oasis-open.org 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 --to=virtio-comment@lists.oasis-open.org 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:robin@oasis-open.org">Robin Cover</a> and <a href="mailto:chet.ensign@oasis-open.org">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:robin@oasis-open.org) and [Chet Ensign](mailto:chet.ensign@oasis-open.org). 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/).
-- 
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: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
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/

[virtio-comment] [PATCH v2 2/7] CONTRIBUTING.md: convert html to proper MarkDown

[Alex Bennée]

There is no point embedding HTML inside the markdown document. It just
makes it messy to edit. The boilerplate text is maintained.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Cc: Robin Cover <robin@oasis-open.org>
---
 CONTRIBUTING.md | 22 +++++++---------------
 1 file changed, 7 insertions(+), 15 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 1330a98..f07cb32 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -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.
-- 
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: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
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/

[virtio-comment] [PATCH v2 3/7] LICENSE.md: convert html to proper MarkDown

[Alex Bennée]

There is no point embedding HTML inside the markdown document. It just
makes it messy to edit. The boilerplate text is maintained.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Cc: Robin Cover <robin@oasis-open.org>
---
 LICENSE.md | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/LICENSE.md b/LICENSE.md
index ef558ec..600b966 100644
--- a/LICENSE.md
+++ b/LICENSE.md
@@ -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.
-- 
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: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
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/

[virtio-comment] [PATCH v2 4/7] Makefile: add some simple make automations

[Alex Bennée]

This is just a helpful shortcut, especially when editing the documents
within an IDE which will offer up make targets to build the documents.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
---
 Makefile | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)
 create mode 100644 Makefile

diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..4c7dc66
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,26 @@
+# -*- Mode: makefile -*-
+#
+# Basic Makefile to aid automation of document building
+#
+
+.PHONY: all
+all:
+	./makeall.sh
+
+.PHONY: html
+html:
+	./makehtml.sh
+
+.PHONY: clean
+clean:
+	git clean -fd
+
+.PHONY: help
+help:
+	@echo "Build the VIRTIO specification documents."
+	@echo ""
+	@echo "Possible operations are:"
+	@echo
+	@echo " $(MAKE)         Build everything"
+	@echo " $(MAKE) html    Build local html"
+	@echo " $(MAKE) clean   Remove all intermediate files"
-- 
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: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
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/

[virtio-comment] [PATCH v2 5/7] make-setup-generated: optionally add GIT metadata

[Alex Bennée]

This isn't a full conversion to git based metadata but it allows for
local builds to add git commit and tree status to the final built
product. The normal formal build process is unaffected and uses
manually updated VERSION, REVISION and REVISION-DATE metadata.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
---
 Makefile                |  2 +-
 make-setup-generated.sh | 34 ++++++++++++++++++++++++++++++----
 makehtml.sh             |  2 +-
 3 files changed, 32 insertions(+), 6 deletions(-)

diff --git a/Makefile b/Makefile
index 4c7dc66..1698557 100644
--- a/Makefile
+++ b/Makefile
@@ -9,7 +9,7 @@ all:
 
 .PHONY: html
 html:
-	./makehtml.sh
+	./makehtml.sh local
 
 .PHONY: clean
 clean:
diff --git a/make-setup-generated.sh b/make-setup-generated.sh
index f15d148..be63bb7 100755
--- a/make-setup-generated.sh
+++ b/make-setup-generated.sh
@@ -1,17 +1,34 @@
 #! /bin/sh
+#
+# Generate version and metadata preamble for the document
+#
 
+# By default we base the version on the directory metadata
 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'`
+
+
+# If a second argument is passed we extract what we can from git
+# metadata (closest lightweight tag) and local tree status. This
+# allows locally generated copies to be tagged appropriately.
+#
+# The formal build process skips this.
+if ! test -z "$2"; then
+    TAG=$(git describe --dirty --tags)
+    # base date on now
+    DATESTR=$(date +'%d %B %Y')
+    COMMIT=$(git rev-parse --short HEAD)
+
+    # Finally check if we have un-committed changes in the tree
+    if ! git diff-index --quiet HEAD -- ; then
+        COMMIT="$COMMIT with local changes"
+    fi
 fi
 
 case "$1" in
     *-wd*)
 	STAGE=wd
 	STAGENAME="Working Draft"
-	WORKINGDRAFT=`basename "$1" | sed 's/.*-wd//'`
 	;;
     *-os*)
 	STAGE=os
@@ -40,6 +57,15 @@ case "$1" in
 	exit 1
 esac
 
+#
+# Finally if we are building a local draft copy append the commit
+# details to the end of the working draft
+#
+if ! test -z "$COMMIT" ; then
+    STAGEEXTRATITLE="$STAGEEXTRATITLE (@ git $COMMIT)"
+fi
+
+
 #Prepend OASIS unless already there
 case "$STAGENAME" in
 	OASIS*)
diff --git a/makehtml.sh b/makehtml.sh
index e18c350..099746c 100755
--- a/makehtml.sh
+++ b/makehtml.sh
@@ -1,7 +1,7 @@
 #!/bin/sh
 
 SPECDOC=${SPECDOC:-`cat REVISION`}
-./make-setup-generated.sh "$SPECDOC"
+./make-setup-generated.sh "$SPECDOC" $1
 
 cp virtio-html.tex $SPECDOC.tex
 
-- 
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: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
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/

[virtio-comment] [PATCH v2 6/7] introduction.tex: introduce a glossary of terms

[Alex Bennée]

It is useful to have a glossary of common terms at the front of the
document to define common terms we are going to use throughout the
specification.

Cc: Nikos Dragazis <ndragazis@arrikto.com>
Cc: Stefan Hajnoczi <stefanha@redhat.com>
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>

---
v2
  - drop host/guest terminology
  - clarify Device/Driver
  - add Transport
---
 introduction.tex | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/introduction.tex b/introduction.tex
index 33da3ec..292b78c 100644
--- a/introduction.tex
+++ b/introduction.tex
@@ -81,6 +81,27 @@ \section{Terminology}\label{Terminology}
 
 The key words ``MUST'', ``MUST NOT'', ``REQUIRED'', ``SHALL'', ``SHALL NOT'', ``SHOULD'', ``SHOULD NOT'', ``RECOMMENDED'', ``MAY'', and ``OPTIONAL'' in this document are to be interpreted as described in \hyperref[intro:rfc2119]{[RFC2119]}.
 
+\subsection{Glossary}\label{intro:Glossary}
+
+The following are definitions of common terms used throughout the specification.
+
+\begin{description}
+\item[Device] The series of configuration, control and operation
+  mechanisms that make a Virtio device. The implementation details of
+  the device should be transparent to the Driver.
+\item[Driver] The software (usually part of a kernel) which accesses
+  the device interface.
+\item[Notification] An asynchronous signal sent to either the Device
+  or the Driver to indicate an event has occurred. For Device to
+  Driver notifications this is typically an device interrupt although
+  the details are a function of the transport.
+\item[Doorbell] A mechanism for the Driver to trigger a notification
+  to the device. The mechanism is a function of the transport but it
+  is typically an MMIO register.
+\item[Transport] The bus level abstraction that the Driver and Device
+  interface with.
+\end{description}
+
 \subsection{Legacy Interface: Terminology}\label{intro:Legacy
 Interface: Terminology}
 
-- 
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: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
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/

[virtio-comment] [PATCH v2 7/7] content.tex: tighten up the definition of notification.

[Alex Bennée]

Repeat the language from the Terminology section and slightly reword
the remaining section of the paragraph.

Suggested-by: Nikos Dragazis <ndragazis@arrikto.com>
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
---
 content.tex | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/content.tex b/content.tex
index 91735e3..d2c9a48 100644
--- a/content.tex
+++ b/content.tex
@@ -161,9 +161,11 @@ \subsection{Legacy Interface: A Note on Feature
 \section{Notifications}\label{sec:Basic Facilities of a Virtio Device
 / Notifications}
 
-The notion of sending a notification (driver to device or device
-to driver) plays an important role in this specification. The
-modus operandi of the notifications is transport specific.
+A notification is a asynchronous signal sent to either the Device or
+the Driver to indicate an event has occurred. The mechanism of how a
+notification is triggered (from driver to device or from device to
+driver) is transport specific. Notifications play an important role in
+this specification.
 
 There are three types of notifications: 
 \begin{itemize}
-- 
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: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
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/

[virtio-comment] Re: [PATCH v2 0/7] doc build updates and terminology definitions

[Alex Bennée]

Alex Bennée <alex.bennee@linaro.org> writes:

> Hi,
>
> This contains both my previously posted build system tweaks and an
> updated revision of the terminology patch I posted last week with a
> further patch to tighten up the language in the Notifications section.

Ping?

-- 
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: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
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/

[virtio-comment] Re: [PATCH v2 6/7] introduction.tex: introduce a glossary of terms

[Stefan Hajnoczi]

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

On Fri, Jul 24, 2020 at 04:42:50PM +0100, Alex Bennée wrote:
> +\subsection{Glossary}\label{intro:Glossary}
> +
> +The following are definitions of common terms used throughout the specification.
> +
> +\begin{description}
> +\item[Device] The series of configuration, control and operation
> +  mechanisms that make a Virtio device. The implementation details of

This definition is self-referential.

How about:

  The embodiment of a device type consisting of configuration space,
  virtqueues, and a transport.

This also requires defining "device type":

  A set of configuration space and virtqueue structure definitions that
  offer I/O functionality.

> +  the device should be transparent to the Driver.

I'm not sure about this "should" statement. Maybe this concept can be
worked into the first sentence or dropped. "May", "can", "should",
"must" are only used in the normative spec sections.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: [virtio-comment] [PATCH v2 0/7] doc build updates and terminology definitions

[Stefan Hajnoczi]

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

The HTML -> Markdown conversion is hard to review.

Can you share a command-line that reviewers can run to verify that the
text is unchanged?

Stefan

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: [virtio-comment] [PATCH v2 0/7] doc build updates and terminology definitions

[Alex Bennée]

Stefan Hajnoczi <stefanha@redhat.com> writes:

> The HTML -> Markdown conversion is hard to review.
>
> Can you share a command-line that reviewers can run to verify that the
> text is unchanged?

Hmm not sure - I just eyeballed the two in githubs web-ui. That said
I've just noticed some of the example code formatting is a little messed
up so I should tweak that.

-- 
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: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
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/