Re: Pre-publication steps

Hi Phil,

Thanks for the instructions.

I just finished the changes to get the doc ready to be published.
HTML is valid, Links are resolvable, except one 
(http://www.w3.org/TR/annotation-model/#motivations) which the fragment 
is not valid anymore.

I also generated the diff file, but when I put it into the others links 
(with the item "Change History") section it replaced the list of 
contributors. Would you mind taking care of this part?

And I also checked a snapshot of the current version of the doc on the 
PubRules checker: no errors, but some warnings of "please verify".

Please, let me know if I can help with anything else.

[]'s

Newton.

Em 11/12/15 15:10, Phil Archer escreveu:
> Riccardo, Eric, Newton,
>
> I think it's the three of you who are doing most work to prepare the 
> docs for publication (with luck, Eric, we can vote next week to 
> publish the DUV immediately after Christmas ;-) )
>
> Before publication there are a number of steps that need to be 
> followed. I am happy to take on some of this as your team contact, 
> however, I will be travelling Monday-Tuesday and so time is tight. Our 
> webmaster is expecting a raft of publications on Thursday and so we 
> need to be prepared.
>
> The order of these steps is not important but here's a list:
>
> 1. Spelling needs to be checked. Please run the text through a spell 
> checker set to US English (warning- Europeans write 'organisation,' 
> Americans write 'organization' etc.)
>
> 2. Weird thing about W3C, we give the word Web a capital W (when it 
> refers to the WWW).
>
> 3. HTML must be valid. The validator is at https://validator.w3.org.
>
> Warnings are OK, actual errors are not. The most common errors are 
> unclosed elements, or extra closing elements that don't match an 
> opening one etc. As discussed, the <section> elements are what drives 
> the ToC and numbering.
>
>
> Also, all links must resolve, so use the link checker too 
> http://validator.w3.org/checklink
>
> It has a habit of reporting some URLs as unavailable but when you try 
> them in the browser, they're fine. If this happens it's because the 
> check sends an HTTP HEAD request, not a GET - and some servers are set 
> up not to respond to HEAD requests.
>
>
> 4. Note that ReSpec does a lot of the work for you - and it does do a 
> *lot* of work. For example, it writes in ids for every section and 
> every heading that doesn't already have one. It also adds in RDFa 
> markup and Web ARIA info. That's why the published docs have far more 
> markup than you put in. If you copy and paste *from* a published doc, 
> it will have all that in there and it won't do any harm, but it may 
> surprise you to see it :-)
>
> 5. Thanks for including the change logs - they're important.
>
> 6. The ReSpec config is important of course. This is what writes in 
> all the top matter. If you look at the source code of 
> view-source:http://w3c.github.io/sdw/UseCases/SDWUseCasesAndRequirements.html 
> you'll see all the config options, including the section on 
> 'otherLinks'. That's where you can put the links to the GH repo, the 
> Diff etc.
>
> 7. The diff! ReSpec even does that for you. Click the reSpec icon on 
> the top right of the doc and choose to save. You'll see various 
> options, one of which is to save the diff - and voila - you have a 
> diff marked doc you can save. It refers to the URL you defined as the 
> previous version.
>
> Then if you really want to finish the job there is our PubRules checker
> https://www.w3.org/2005/07/pubrules This checks for many things, most 
> of which are handled by ReSpec, but not all. Documents that don't pass 
> PubRules won't be published.
>
> You can do all this. The only thing you can't do is to install the 
> documents on w3.org which I will do of course. The more of this you're 
> able to do, the more chance there is of us meeting the deadline.
>
> The documents need to be installed and PubRules on Wednesday. And I 
> need to send a publication request to the webmaster.
>
> I'll do my best to help between now and then of course. I'll be in a 2 
> day project meeting and so will have some ability to tune out from 
> time to time.
>
> Phil.
>
>
>