OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

virtio message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


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


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

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


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



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]