docbook-tc — archive

First attempt at DocBook V5.1-CSPRD01

From: Chet Ensign <[email protected]>
To: [email protected]
Date: Mon, 08 Dec 2014 22:40:00 -0000

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 [email protected] . 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 [email protected] . 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 < [email protected] > 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 < [email protected] > 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