Re: [virtio] Starter Document in Latex format (was Re: [virtio] Starter

Subject: Re: [virtio] Starter Document in Latex format (was Re: [virtio] Starter Document for Virtual I/O Device (VIRTIO)) Version 1.0

Hi all,

An answer for Michael's question is below, in-line.

Also one more point - there needs to be some meaningful content in the "Conformance" section before the specification can move to the Public Review stage or beyond. (Required by the TC Process.)

On Mon, Nov 25, 2013 at 11:15 AM, Michael S. Tsirkin <mst@redhat.com> wrote:

On Mon, Nov 25, 2013 at 11:05:33AM -0500, Paul Knight wrote:
> Hi all,
>
> I wanted to mention one other item, after looking through the specification in
> detail. (Nice work, by the way!!)
>
> This is regarding Section 7 (virtio_ring.h listing). It's fine to include
> this, but the TC Process [1] has specific requirements for handling listings
> like this:
>
> "All normative computer language definitions must be provided in separate plain
> text files [...]"
>
> (Actually, if Section 7 is declared to be non-normative, you could avoid this,
> but I imagine implementers might appreciate it anyway...)

Well it is non-normative actually.
Do we need to include specific text to mark it as such?

It is not required to mark it as non-normative (in order for it to be published, anyway), but by default, everything is considered to be normative unless otherwise labeled.

Some TCs have found it helpful to use a distinctive font or background shading to identify "examples", and use an example statement such as "Non-normative examples use this paragraph style".

For this approach, see

http://docs.oasis-open.org/odata/odata/v4.0/csprd03/part1-protocol/odata-v4.0-csprd03-part1-protocol.html#_Toc369182979

Best regards,

Paul

> You will need to provide the file for this, and also a pointer to it from the
> front pages.
> Details:
> - under "Additional artifacts:" on the front page, change the bullet "XML
> schemas" to something like
>
> Example driver listing:
> http://docs.oasis-open.org/virtio/virtio/v1.0/csd01/listings/
>
> - Also, within Section 7, note that the file is available - using text like:
> "This file is available at the link provided in the "Additional artifacts"
> section on the front page."
>
> [using this indirect reference, only the front page needs to be changed as the
> Work Product moves through various stages - the reference text in Section 7
> would remain static]
>
> [1] https://www.oasis-open.org/policies-guidelines/tc-process#specQuality (see
> particularly section 7(a)).
>
> Best regards,
> Paul
>

Will do. Including the link directly is not hard either -
we re-compile it all at each stage, anyway.

A nice feature of automated publishing!

> On Mon, Nov 25, 2013 at 10:22 AM, Paul Knight <paul.knight@oasis-open.org>
> wrote:
>
> Hi all,
>
> I'm glad to see that the TC has settled on using LaTeX to produce the
> Virtio specification.
>
> The HTML and PDF versions look like they are on the right track, but will
> need to have a number of adjustments to match the publication formats used
> for OASIS Work Products (as opposed to the "working draft" formats, which
> omit several elements which are pretty tricky).
>
> Since (by using LaTeX) you will be handling every aspect of producing the
> PDF and HTML files, you'll need a complete example of the expected front
> pages. That is in the attached ZIP file.
>
> Assuming you want to have a formal Public Review when you publish the first
> Committee Specification Draft, you will actually need to produce TWO
> parallel sets of files:
> - Committee Specification Draft 01 (csd01)
> - Committee Specification Public Review Draft 01 (csprd01)
>
> In the attached ZIP file, I've included examples of the expected
> publishable csd01 front pages (in HTML, PDF, and source DOC formats), the
> publishable csprd01 front pages (DOC only), and our internal checklist of
> changes from csd01 to csprd01.
>
> You'll need to follow these front page formats exactly as you prepare the
> documents for publication.
> Chet and I are very happy to review your planned materials before you
> submit them. Our experience has been that it takes a few iterations to get
> everything completely ready, especially for the first (csd01/csprd01)
> publication.
>
> Best regards,
> Paul
>
>
> On Mon, Nov 25, 2013 at 9:49 AM, Cornelia Huck <cornelia.huck@de.ibm.com>
> wrote:
>
> On Mon, 25 Nov 2013 15:57:52 +0200
> "Michael S. Tsirkin" <mst@redhat.com> wrote:
>
> > On Mon, Nov 25, 2013 at 02:09:14PM +0100, Cornelia Huck wrote:
> > > On Mon, 25 Nov 2013 13:58:36 +0100
> > > Cornelia Huck <cornelia.huck@de.ibm.com> wrote:
> > >
> > > > On Mon, 25 Nov 2013 14:21:55 +0200
> > > > "Michael S. Tsirkin" <mst@redhat.com> wrote:
>
> > > > - There are a lot of field names, defines, etc. inline, which
> probably
> > > > need some kind of visual differentiation (\verbatim{}?) How is
> this
> > >
> > > s/verbatim/texttt/
> > >
> > > At least that's what I've used in similar documents.
> > >
> > > > handled in other standards?
> >
> > Also if you are inclined to do this conversion all over,
> > please take a look at pre-defined virtioattribute/virtioproperty/
> > virtiodescription etc in commands-pdf.tex and commands-html.tex
> >
> > These have the advantage of already being supported in html.
> >
>
> I hadn't looked at the defined environments yet, but this looks like a
> good idea. I'll see what I can do.
>
>
>
>
>
> --
> Paul Knight - Tel: +1 781-861-1013
> OASIS - Advancing open standards for the information society
> Document Process Analyst
>
>
>
>
>
> --
> Paul Knight - Tel: +1 781-861-1013
> OASIS - Advancing open standards for the information society
> Document Process Analyst
>

--
Paul Knight - Tel: +1 781-861-1013
OASIS - Advancing open standards for the information society
Document Process Analyst

virtio message