Re: First attempt at DocBook V5.1-CSPRD01

[Norman Walsh <ndw@nwalsh.com>]

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.

Attachment: signature.asc
Description: PGP signature