[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [virtio] We need fixes to the csd and csprd before we can load them
On Tue, Mar 25, 2014 at 04:56:58PM -0400, Chet Ensign wrote:
> Michael, Paul does raise a key point. Our mechanics with the specification
> documents is that the listings in the This version / Previous version / Latest
> version links all point to *some* file, some physical artifact. In the case of
> multi-part specifications, it will point to Part 1 and readers are expected to
> figure out there are also parts 2, 3, etc. But we do take them to something,
> not a directory. And in fact, it isn't clear what we'll do with the Latest
> version link if there's no file at the end of the link.
Hmm I think this should not be a problem:
in draft 01 latest version link pointed at the HTML,
that in turn includes links to all the rest of formats
right on the title page.
> I can understand that you view the TeX files as the final source if there are
> any discrepancies and in that sense they are definitive. On the other hand,
> it's not clear how many people are actually going to be in a position to read
> the TeX in any useful way.
>
> However, to go forward with TeX as the authoritative source, I think the point
> Paul has raised with me is right - we'll need to point to *something* - even if
> it is just a readme file that explains the organization of the TeX files to the
> readers. I don't think the ZIP file is the answer there because that would
> still leave someone like me going "ok - so what have I got here?"
>
> /chet
Well I made it so README.txt is the first one alphabetically and
the first in zip listing, so almost any tool should
display it prominently at the top.
Once one reads this file, the question should be really easy to answer.
But if you prefer, how about we tweak README.txt like this:
--->
This is one component of a Work Product that also includes:
Abstract:
http://docs.oasis-open.org/virtio/virtio/v1.0/csd01/tex/abstract.tex
Introduction:
http://docs.oasis-open.org/virtio/virtio/v1.0/csd01/tex/introduction.tex
Main specification content:
http://docs.oasis-open.org/virtio/virtio/v1.0/csd01/tex/content.tex
Conformance targets and clauses:
http://docs.oasis-open.org/virtio/virtio/v1.0/csd01/tex/conformance.tex
Acknowledgements:
http://docs.oasis-open.org/virtio/virtio/v1.0/csd01/tex/acknowledgements.tex
TeX source files for generating output in pdf and html format:
http://docs.oasis-open.org/virtio/virtio/v1.0/csd01/tex/
<----
(tweak URIs as needed) and link to that as the authoritative file.
will this address all concerns?
Pls let me know.
>
> On Tue, Mar 25, 2014 at 4:32 PM, Paul Knight <paul.knight@oasis-open.org>
> wrote:
>
> Hi Michael,
>
> We have never before (AFAIK) pointed to a directory as one of the
> "Specification URIs", and particularly not as the "Authoritative" version.
>
> I'm copying Robin Cover, who is the OASIS Library architect. We don't want
> to get into a position where we have to re-architect the OASIS Library to
> support a publication, or (more likely) retract a publication because it
> cannot be supported in the long term.
>
> I should also say that I have some serious reservations about the approach
> of declaring the TeX source to be the "Authoritative" version. Simply
> looking at the practical (publication-related) aspects of listing TeX
> instead of the PDF (or HTML) as the version as Authoritative, I don't see
> any gain.
>
> I haven't read the TC meeting minutes to see if there was some specific
> reason for selecting TeX as the "Authoritative" version, but it seems to be
> causing a lot of pain for very little meaningful gain...
>
> The only downside I can see to listing PDF as the authoritative version is
> that the TC has voted for TeX, and it would likely require another vote to
> override that, and thus a delay until the next TC meeting.
>
> So at this point, I'd like to get Robin's opinion on two points:
> A - listing a directory instead of a single file as one of the
> "Specification URIs" on the front page
> B - Listing a collection of TeX files and related elements
> (e.g., as in http://docs.oasis-open.org/virtio/virtio/v1.0/csd01/tex/)
> (even as a ZIP file) as "Authoritative".
>
> Apologies for introducing a new concern here...
>
> Best regards,
> Paul
>
>
> On Tue, Mar 25, 2014 at 8:30 AM, Michael S. Tsirkin <mst@redhat.com> wrote:
>
> On Tue, Mar 25, 2014 at 01:42:31PM +0200, Michael S. Tsirkin wrote:
> > OK but we also need to point people at the content files:
> > introduction.tex
> > content.tex
> > conformance.tex
> >
> > So what I will do is include in the zip file a text file README.txt
> > listing these, with this text:
> >
> > This is one component of a Work Product that also
> > includes:
> >
> > Introduction: introduction.tex
> > Main specification content: content.tex
> > Conformance targets and clauses: conformance.tex
> > TeX source files for generating pdf and html format.
>
> And having said that, is anything wrong with
> just pointing at the tex directory as we did?
> At the top of that directory people will see README.txt
> and if they click that they see the explanation
> where to look.
>
> There's also the full zip file with everything
> included for people who want it.
>
> Acceptable?
>
>
> >
> > On Mon, Mar 24, 2014 at 05:25:42PM -0400, Chet Ensign wrote:
> > > Yes, that'll work fine. Thanks.
> > >
> > >
> > > On Mon, Mar 24, 2014 at 5:13 PM, Michael S. Tsirkin <mst@redhat.com
> > wrote:
> > >
> > > On Mon, Mar 24, 2014 at 02:29:03PM -0400, Chet Ensign wrote:
> > > > First of all, best wishes to you and your family. I still
> recall the
> > > excitement
> > > > when my daughter was born!
> > > >
> > > > We noted that the TeX was voted as authoritative. If that is
> the case
> > > then
> > > > you'll need to add the TeX directory to the This version and
> Latest
> > > version
> > > > links and - is there a master driver file from which all the
> others are
> > > > processed or assembled? I never did work with TeX but
> assuming there is,
> > > that I
> > > > suppose would be the file to point to. You'll also have to
> take the
> > > > (Authoritative) designation off the PDF files.
> > >
> > > Hmm yes but the master file is mostly empty - it just has names
> > > of included sub-files.
> > > I think it's best to point at a zip archive with
> > > all the necessary files.
> > > Is that OK?
> > >
> > > >
> > > > On Sun, Mar 23, 2014 at 9:45 PM, Rusty Russell <
> rusty@rustcorp.com.au>
> > > wrote:
> > > >
> > > > Hi,
> > > >
> > > > My wife went into labor on Friday morning, so
> things are a
> > > bit
> > > > hectic here. Michael, can you please organise this?
> > > >
> > > > We had voted to make the TeX source authoritative for
> this version,
> > > BTW.
> > > >
> > > > Thanks,
> > > > Rusty.
> > > >
> > > > "Michael S. Tsirkin" <mst@redhat.com> writes:
> > > > > On Thu, Mar 20, 2014 at 01:15:13PM -0400, Chet Ensign
> wrote:
> > > > >> Members of the VIRTIO TC,
> > > > >>
> > > > >> We are working on your Committee Spec Draft and public
> review for
> > > the
> > > > 2nd csprd
> > > > >> for VIRTIO (https://tools.oasis-open.org/issues/browse
> /
> > > TCADMIN-1638 and
> > > > /
> > > > >> tools.oasis-open.org/issues/browse/TCADMIN-1641).
> > > > >>
> > > > >> In working on these, we have encountered some items
> that need to
> > > be
> > > > fixed. As
> > > > >> you produce the documents, we ask that you make these
> and send us
> > > an
> > > > updated
> > > > >> set of zip files. Here is what we need:
> > > > >>
> > > > >> 1) cover page changes needed for csd02
> > > > >>
> > > > >> - This version:
> > > > >>
> > > > >> -- both tex and pdf are listed as authoritative.
> obviously 2
> > > versions
> > > > can’t be
> > > > >> authoritative. since pdf has been authoritative
> before, it seems
> > > best to
> > > > stay
> > > > >> with that but regardless, please indicate one
> authoritative source
> > > > (Latest,
> > > > >> Previous, This)
> > > > >>
> > > > >> -- assuming PDF is labelled authoritative, remove /tex
> directory.
> > > It is
> > > > >> indicated in the Additional artifacts section below
> > > > >>
> > > > >> - Previous version:
> > > > >> -- Change links to
> > > > >> http://docs.oasis-open.org/virtio/virtio/v1.0/csprd01/
> > > > virtio-v1.0-csprd01.pdf
> > > > >> http://docs.oasis-open.org/virtio/virtio/v1.0/csprd01/
> > > > virtio-v1.0-csprd01.html
> > > > >>
> > > > >> -- Label the PDF version (Authoritative)
> > > > >>
> > > > >> - Latest version:
> > > > >> -- Label the PDF version (Authoritative)
> > > > >>
> > > > >> - Editors:
> > > > >> -- Pawel’s link under ARM goes to a download page not
> to the
> > > company
> > > > page.
> > > > >> Should be changed to http://www.arm.com
> > > > >>
> > > > >> - Citation format:
> > > > >> We updated our citation model a few months ago to
> include the
> > > editors
> > > > and the
> > > > >> Latest version link. Please update the citation block
> to read:
> > > > >>
> > > > >> [VIRTIO-v1.0]
> > > > >>
> > > > >> <italics>Virtual I/O Device (VIRTIO) Version 1.0</>.
> Edited by
> > > Michael
> > > > S.
> > > > >> Tsirkin, Cornelia Huck, and Pawel Moll. 11 March 2014.
> OASIS
> > > Committee
> > > > >> Specification Draft 02. http://docs.oasis-open.org/
> virtio/virtio/
> > > v1.0/
> > > > csd02/
> > > > >> virtio-v1.0-csd02.html. Latest version: http://
> docs.oasis-open.org
> > > /
> > > > virtio/
> > > > >> virtio/v1.0/virtio-v1.0.html.
> > > > >>
> > > > >> *Note that “OASIS” is also added before “Committee
> Specification
> > > Draft
> > > > 02” for
> > > > >> the csd and before "Committee Specification Draft 02 /
> Public
> > > Review
> > > > Draft 02"
> > > > >> for the csprd.
> > > > >>
> > > > >> - Notices:
> > > > >> Set copyright year to 2014
> > > > >>
> > > > >> - In PDF, for footer:
> > > > >> Set copyright year to 2014.
> > > > >>
> > > > >> 2) cover page changes needed for csprd02:
> > > > >>
> > > > >> - Same changes as for the csd02 files.
> > > > >>
> > > > >> -- Plus: The ZIP file contains all the individual html
> files for
> > > the
> > > > footnotes,
> > > > >> but they are not needed. They should be removed. I
> think the TC
> > > removed
> > > > them
> > > > >> in the csd02 files, but not in the csprd02 files.
> (csprd02
> > > footnotes
> > > > work fine
> > > > >> without the files - the footnotes are embedded and
> linked in the
> > > main
> > > > .html
> > > > >> file.)
> > > > >>
> > > > >> -- We need a red-lined DIFF file in PDF between
> csprd02 and
> > > csprd01 that
> > > > >> displays the changes. We point out this to reviewers
> in order to
> > > limit
> > > > the
> > > > >> public review comments to only those that changed.
> > > > >
> > > > > Due to the huge number of formatting and text movement
> changes, we
> > > ended
> > > > > up with almost all of the file red-lined. On the TC,
> we voted to
> > > > > produce csprd02 and csd02 without this DIFF and start
> producing
> > > DIFF
> > > > > files from version 03.
> > > > >
> > > > > I hope this is acceptable.
> > > > >
> > > > >> 3) We need a comment resolution log from the TC for
> comments
> > > received in
> > > > >> csprd01
> > > > >
> > > > > I actually wrote a script to append the resolution
> changelog as
> > > last
> > > > > part of the file, but this was done after csd02/csprd02
> were
> > > approved.
> > > > > Do you think appending the log is an acceptable change
> to make
> > > > > without re-doing the voting?
> > > > >
> > > > >> Thanks - if you can send me those files when they are
> ready, I'll
> > > update
> > > > the
> > > > >> ticket and we will continue to process the spec.
> > > > >>
> > > > >> Thanks & best,
> > > > >>
> > > > >> /chet
> > > > >
> > > > > I'll work on this shortly - unless Rusty already
> started?
> > > > >
> > > > >
> > > > >>
> > > > >>
> > > > >> --
> > > > >>
> > > > >> /chet
> > > > >> ----------------
> > > > >> Chet Ensign
> > > > >> Director of Standards Development and TC
> Administration
> > > > >> OASIS: Advancing open standards for the information
> society
> > > > >> http://www.oasis-open.org
> > > > >>
> > > > >> Primary: +1 973-996-2298
> > > > >> Mobile: +1 201-341-1393
> > > > >>
> > > > >> Check your work using the Support Request Submission
> Checklist at
> > > http:/
> > > > /
> > > > >> www.oasis-open.org/committees/download.php/47248/
> > > > >> tc-admin-submission-checklist.html
> > > > >>
> > > > >> TC Administration information and support is available
> at http://
> > > > >> www.oasis-open.org/resources/tcadmin
> > > > >>
> > > > >> Follow OASIS on:
> > > > >> LinkedIn: http://linkd.in/OASISopen
> > > > >> Twitter: http://twitter.com/OASISopen
> > > > >> Facebook: http://facebook.com/oasis.open
> > > >
> > > >
> > > >
> > > >
> > > > --
> > > >
> > > > /chet
> > > > ----------------
> > > > Chet Ensign
> > > > Director of Standards Development and TC Administration
> > > > OASIS: Advancing open standards for the information society
> > > > http://www.oasis-open.org
> > > >
> > > > Primary: +1 973-996-2298
> > > > Mobile: +1 201-341-1393
> > > >
> > > > Check your work using the Support Request Submission
> Checklist at http://
> > > > www.oasis-open.org/committees/download.php/47248/
> > > > tc-admin-submission-checklist.html
> > > >
> > > > TC Administration information and support is available at
> http://
> > > > www.oasis-open.org/resources/tcadmin
> > > >
> > > > Follow OASIS on:
> > > > LinkedIn: http://linkd.in/OASISopen
> > > > Twitter: http://twitter.com/OASISopen
> > > > Facebook: http://facebook.com/oasis.open
> > >
> > >
> ---------------------------------------------------------------------
> > > To unsubscribe from this mail list, you must leave the OASIS TC
> that
> > > generates this mail. Follow this link to all your TCs in OASIS
> at:
> > > https://www.oasis-open.org/apps/org/workgroup/portal/
> my_workgroups.php
> > >
> > >
> > >
> > >
> > >
> > > --
> > >
> > > /chet
> > > ----------------
> > > Chet Ensign
> > > Director of Standards Development and TC Administration
> > > OASIS: Advancing open standards for the information society
> > > http://www.oasis-open.org
> > >
> > > Primary: +1 973-996-2298
> > > Mobile: +1 201-341-1393
> > >
> > > Check your work using the Support Request Submission Checklist at
> http://
> > > www.oasis-open.org/committees/download.php/47248/
> > > tc-admin-submission-checklist.html
> > >
> > > TC Administration information and support is available at http://
> > > www.oasis-open.org/resources/tcadmin
> > >
> > > Follow OASIS on:
> > > LinkedIn: http://linkd.in/OASISopen
> > > Twitter: http://twitter.com/OASISopen
> > > Facebook: http://facebook.com/oasis.open
>
>
>
>
> --
> Paul Knight - Tel: +1 781-861-1013
> OASIS - Advancing open standards for the information society
> Document Process Analyst
>
>
>
>
>
> --
>
> /chet
> ----------------
> Chet Ensign
> Director of Standards Development and TC Administration
> OASIS: Advancing open standards for the information society
> http://www.oasis-open.org
>
> Primary: +1 973-996-2298
> Mobile: +1 201-341-1393
>
> Check your work using the Support Request Submission Checklist at http://
> www.oasis-open.org/committees/download.php/47248/
> tc-admin-submission-checklist.html
>
> TC Administration information and support is available at http://
> www.oasis-open.org/resources/tcadmin
>
> Follow OASIS on:
> LinkedIn: http://linkd.in/OASISopen
> Twitter: http://twitter.com/OASISopen
> Facebook: http://facebook.com/oasis.open
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]