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

["Michael S. Tsirkin" <mst@redhat.com>]

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