Re: Pre-publication steps

Thanks Riccardo, that's v helpful. I'll take it from here - PubRules 
does throw up some very odd requirements that I've become used to over 
the years ;-)

Cheers

Phil

On 14/12/2015 20:08, Riccardo Albertoni wrote:
> Hi Phil,
> Thanks for the instructions,
> I think DQV is almost ready with the Pre-publication steps.
> You can find the html generated by ReSpec at
> http://w3c.github.io/dwbp/publishing-snapshots/WD-vocab-dqv-20151214/Overview.html
>
> Still some issues are found by PubRules,
> but sincerely I am not sure  how to fix them,
> any suggestion?
>
>   if you need more details on the steps we did you can see below.
>
> Regards,
> Riccardo
>
> On 11 December 2015 at 18:10, Phil Archer <phila@w3.org> wrote:
>
>> 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.)
>>
> Done
>
>
>> 2. Weird thing about W3C, we give the word Web a capital W (when it refers
>> to the WWW).
>>
> Done
>
> 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.
>>
>> It is valid,
> https://validator.w3.org/nu/?doc=http%3A%2F%2Fw3c.github.io%2Fdwbp%2Fvocab-dqg.html
>
>>
>> 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.
>>
>
> I have got rid of most of the  invalid links,
> we have still few  links which are marked as broken,
> I would not consider those links as  problematic:
> They  are "broken URI fragments" which  are either  links to classes/
> properties we are still in progress in DQV (for which we use   <a
> href="#">... </a> ), or pointers to a class or propriety in a RDF file
> (e.g., http://www.w3.org/2002/07/owl#DatatypeProperty).
> If you need more detail, you can take a look at
> https://validator.w3.org/checklink?uri=http%3A%2F%2Fw3c.github.io%2Fdwbp%2Fvocab-dqg.html&hide_type=all&depth=&check=Check
>
>
>
>> 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.
>>
>> I have added  the changes history also under the section "Changes:" in the
> document header.
>
>
>> 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.
>>
>> Sorry but I am not adding GH repo. After publishing the  DQV FPWD, we had
> at least a commenter complaining  that he could not raise issues on
> github.. So we decided to remove the GH repo to avoid to   cause confusion
> to people who wanted raise issue.
>
>
>> 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.
>>
>
> I have added the diff link.
> http://w3c.github.io/dwbp/diffs/dqvdiff-20151214.html
>   Not sure how understandable it is but anyway we have it :)
> The dump of diff is in the subdirectory diffs/ .
>
>
>> 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.
>>
>>
> You can find the html generated by ReSpec at
> http://w3c.github.io/dwbp/publishing-snapshots/WD-vocab-dqv-20151214/Overview.html
>
>
>
>
>> 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.
>>
>>
>>
>> --
>>
>>
>> Phil Archer
>> W3C Data Activity Lead
>> http://www.w3.org/2013/data/
>>
>> http://philarcher.org
>> +44 (0)7887 767755
>> @philarcher1
>>
>>
>> --
>> This message has been scanned by E.F.A. Project and is believed to be
>> clean.
>>
>>
>>
>
>

-- 


Phil Archer
W3C Data Activity Lead
http://www.w3.org/2013/data/

http://philarcher.org
+44 (0)7887 767755
@philarcher1

Received on Monday, 14 December 2015 21:18:21 UTC