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?
> 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.
> On Mon, Nov 25, 2013 at 10:22 AM, Paul Knight <>
> 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 <>
>
wrote: >
>
On Mon, 25 Nov 2013 15:57:52 +0200 >
"Michael S. Tsirkin" <> 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 <> wrote: >
> > >
> >
> On Mon, 25 Nov 2013 14:21:55 +0200 >
> > > "Michael S. Tsirkin" <> 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 >
