Hi Norm,
My apologies for not getting you feedback on this sooner. Several things have made it a bit crazy lately.
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.
2) In addition to the HTML document, we need a copy of the editable source and a PDF.
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
4) I see that in the catalog file, the comment says to send comments to docbook@. It should use . Only TC members can send to docbook@ but anyone can subscribe and send to docbook-comment@
Docbook.html
1) For the Committee Specification Draft, the stage description under the title will be:
Committee Specification Draft 01
For the public review copy, it will be:
Committee Specification Draft 01 /
Public Review Draft 01
2) The approval date will be set to whatever date the TC approves the CSD/CSPRD obviously.
3) Under Specification URIs we use "This version" instead of both caps "This Version"
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.
6) Additional artifacts looks good. Related Work should be lowercase 'w'. Namespace should be lowercase n.
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."
That helps people who want to know if the TC has other technical work besides this one.
In the second paragraph, I'd link "Send a Comment" to https://www.oasis-open.org/committees/comments/index.php?wg_abbrev=docbook
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.
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.
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?
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 . 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.
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.
- The TC can approve that working draft as a CSD and approve it for public review using a motion like this:
"I move that the TC approve DocBook Version 5.1 and all associated artifacts packaged together in <URL to ZIP file in TC's Kavi document repository> as a Committee Specification Draft and designate the HTML version of the specification as authoritative. I also move that the Committee Specification Draft be released for public review."
- After the motion has passed and your minutes are published with the motion and vote recorded, someone should fill out a CSD request at https://www.oasis-open.org/resources/tc-admin-requests/committee-specification-draft-creation-upload-request and a corresponding public review request at https://www.oasis-open.org/resources/tc-admin-requests/30-day-committee-specification-draft-public-review-request . That puts two tickets in my TC Admin JIRA queue so that it is on the record that you've assigned it to me.
I'll then take it from there - working with you to make any last minutes tweaks, loading the files to docs.oasis-open.org/docbook/ and getting the public review started.
Anyhow, that's what I saw with my review. You've got something very close to being ready to go. Congrats on all the work! Let me know how I can help in the next phase.
Best,
/chet
On Tue, Nov 18, 2014 at 10:51 AM, Norman Walsh <> wrote:
Hi folks,
Attached, please find a ZIP file containing my first attempt at
DocBook V5.1 CSPRD01. Feedback welcome. Chet, if you would be so kind
as to double-check that I've crossed all the correct OASIS i's and
dotted all the t's, I'd really appreciate that.
If the ZIP doesn't come through, you can get it here:
http://nwalsh.com/scratch/docbook-v5.1-csprd01/
Assuming my attempt passes muster, I think we should vote to make this
a Committee Specification tomorrow. Or whatever the OASIS process calls
the official thing now.
Be seeing you,
norm
--
Norman Walsh <> | O for a Muse of fire, that would
http://www.oasis-open.org/docbook/ | ascend / The brightest heaven of
Chair, DocBook Technical Committee | invention, / A kingdom for a
| stage, princes to act / And
| monarchs to behold the swelling
| scene!--William Shakespeare, Henry
| V
--
/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
