Re: First attempt at DocBook V5.1-CSPRD01

Thanks very much Norm. I'll take a look again today although at this point any final tweaks can be handled without further approval. It will just be any last corrections to the cover pages, same as I would normally do.

On the reference book, thanks for the link. Now that I see it is your O'Reilly title, I agree. It wouldn't be appropriate to put a copy on the OASIS system. Perhaps you can call it something other than "reference" - that word suggests that it is something that ought to be an official publication from the TC. In fact, I had a query a year or so back from someone in Japan asking where the user documentation was. I found and directed him to the previous edition but he came back and asked why OASIS wasn't publishing it. Maybe phrase it something like "Additional information on using the standard can be found in "DocBook 5.1: The Definitive Guide" by Norm Walsh... citation, etc."

On the feedback, yes, I understand what you're saying. Other TCs have been unhappy that they had to stop using other channels for comments too. The reason that the TC Process requires that the TC only accept comments via the <tc-shortname>-comment@ is to provide a channel that protects the interests of the TC. Anyone using that mailing list effective agrees to the same IPR terms as those the TC operates under and, should a dispute ever arise, OASIS can demonstrate the submitter's awareness of the terms on which they submitted their work. If someone hands a TC member an idea on a cocktail napkin - and then comes back later looking for royalties or something because the TC used it - no such protection exists. And that isn't just hypothetical - there was a case last year where something similar happened and we had to take a TC document down.

Again, thanks for making the changes and I'll take a look today.

Best,

/chet

On Tue, Dec 16, 2014 at 4:15 PM, Norman Walsh <ndw@nwalsh.com> wrote:

Chet Ensign <chet.ensign@oasis-open.org> writes:
> I've been through the files and they look good. Real close to ready-to-publish.
> Here are some tweaks and next steps, mostly minor formatting notes.
>
> 1) First thing, we'll need to have both a Committee Spec Draft copy
> (...-csd01.xxx) *and* the Committee Spec Public Review Draft (...-csprd01.xxx) to
> load. You can bundle them and approve them all in 1 ZIP file and I'll load them
> separately.

Ok. I've put everything in a single zip that I put on Kavi.

> 2) In addition to the HTML document, we need a copy of the editable source and a
> PDF.

Ok.

> 3) The purple for the text headings is different from the one in our template. The
> one in our template is RGB 59,0,111

I think that's in

http://docs.oasis-open.org/templates/DocBook/spec-0.6/css/oasis-spec.css

> 4) I see that in the catalog file, the comment says to send comments to docbook@.
> It should use docbook-comment@lists.oasis-open.org. Only TC members can send to
> docbook@ but anyone can subscribe and send to docbook-comment@

Ok.

> Docbook.html
>
> 1) For the Committee Specification Draft, the stage description under the title
> will be:
>
> Committee Specification Draft 01

Fixed.

> For the public review copy, it will be:
>
> Committee Specification Draft 01 /
> Public Review Draft 01

Ok.

> 2) The approval date will be set to whatever date the TC approves the CSD/CSPRD
> obviously.

Right. I've dated it tomorrow.

> 3) Under Specification URIs we use "This version" instead of both caps "This
> Version"

Fixed.

> 4) Under "This version," you'll also need to include links to the editable source
> and PDF:
>
> http://docs.oasis-open.org/docbook/docbook/v5.1/csd01/docbook-v5.1-csd01.xml
> http://docs.oasis-open.org/docbook/docbook/v5.1/csd01/docbook-v5.1-csd01.pdf
>
> and in the public review copy
>
>
> http://docs.oasis-open.org/docbook/docbook/v5.1/csprd01/docbook-v5.1-csprd01.xml
>
> http://docs.oasis-open.org/docbook/docbook/v5.1/csprd01/docbook-v5.1-csprd01.pdf
>
> The same also is true for the "Latest version" links
>
> 5) For the link under Technical Committee, please use
> https://www.oasis-open.org/committees/docbook/. The link that's there now doesn't
> take the reader to the TC's public page.

Ok.

> 6) Additional artifacts looks good. Related Work should be lowercase 'w'.
> Namespace should be lowercase n.

Ok.

> 7) Under Status, at the end of the last paragraph, we now include a sentence that
> reads:
>
> "Any other numbered Versions and other technical work produced by the Technical
> Committee (TC) are listed at
> https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=docbook#technical."

Ok.

> In the second paragraph, I'd link "Send a Comment" to
> https://www.oasis-open.org/committees/comments/index.php?wg_abbrev=docbook

Ok.

> I'm not sure about including the sentence about the 'non-normative' errata. Errata
> are supposed to be approved and published along with the standards they correct. I
> think I'd prefer it if you remove the sentence.

Ok.

> 8) Here is what to use for the citation format - for the Committee Spec Draft
>
> [DocBook-5.1]
> <ital>DocBook Version 5.1</>. Edited by Norman Walsh. 18 November 2014. OASIS
> Committee Specification Draft 01.
> http://docs.oasis-open.org/docbook/docbook/v5.1/csd01/docbook-v5.1-csd01.html.
> Latest version: http://docs.oasis-open.org/docbook/docbook/v5.1/docbook-v5.1.html
> .
>
> and for the public review draft
>
> [DocBook-5.1]
> <ital>DocBook Version 5.1</>. Edited by Norman Walsh. 18 November 2014. OASIS
> Committee Specification Draft 01 / Public Review Draft 01.
> http://docs.oasis-open.org/docbook/docbook/v5.1/csprd01/docbook-v5.1-csprd01.html.
> Latest version: http://docs.oasis-open.org/docbook/docbook/v5.1/docbook-v5.1.html
> .

Ok.

> 9) In section 4. Conformance, the second paragraph refers to "reference
> documentation" that describes additional constraints. Where is that document? Is
> it something separate from this publication?

Yes, that's http://docbook.org/tdg51/en/html/docbook.html

I don't think it's practical to publish that document as part of the
specification, it's simply too large. However, if you want to mirror it
on docs.oasis-open.org, that's probably doable.

> 10) In the Introduction, there is a sentence that reads: "The current list of
> outstanding requests is available through the SourceForge tracker interface. This
> is also the preferred mechanism for submitting new requests." -- I realize that
> the SourceForge project has been there for a long time however technically it
> violates TC Process to accept comments from any other source than
> docbook-comment@lists.oasis-open.org. I'd be more comfortable if you would remove
> the "This is also the preferred..." sentence or replace it with one pointing
> people to docbook-comment@. Copying comments from that list to the tracker is not
> a problem but soliciting comments there is.

I'm not sure I understand how the process expects to control how
members of the technical committee receive suggestions. If someone
writes one on the back of a chewing gum wrapper and hands it to a
member of the committee in the subway, I don't see how the committee
member can be forbidden from mentioning it at the next meeting.

However, I've updated that paragraph.

> As far as the next steps go, they'd be these:
>
> - Once the revised files are ready to go, package them all into a ZIP file and
> load it to the Kavi site.

I believe they are here.

https://www.oasis-open.org/apps/org/workgroup/docbook/download.php/54757/docbook-drafts-2014-12-16.zip

If you want to take another look, that would be great. I'll get the
minutes to record the appropriate things tomorrow.

Be seeing you,
norm

--

Norman Walsh <ndw@nwalsh.com> | So, are you working on finding that bug
http://nwalsh.com/ | now, or are you leaving it until later?
| Yes.

/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

docbook-tc message