gmane.org.w3c.specifications

Re: Let's update the Respec documentation!

2013-05-24T18:03:12

WG-NOTEs, especially for FPWD need clarification of the best practice.

for a note it is specStatus: "WG-NOTE",    (perhaps the other various options should be removed)

for FPWD NOTE I believe it is specStatus: "FPWD" , with sotd mentioning that it is Note track (if needed)  (despite the ever-confusing FPWD-NOTE option) 

regards, Frederick

Frederick Hirsch
Nokia



On May 24, 2013, at 12:40 PM, ext Richard Ishida wrote:

Re: Update on the publication process project

Tobie Langel — 2013-05-24T17:55:12


On Friday, May 24, 2013 at 7:26 PM, Gregg Kellogg wrote:

I'm sure there are more correct ways of doing this than I did. But this was working within minutes and serves our purpose perfectly.

--tobie

Re: Let's update the Respec documentation!

Richard Ishida — 2013-05-24T16:40:35

Add somewhere How to publish a FPWD of a document not intended to become 
a Rec.

Iirc, off the top of my head, I think the secret formula is:

[1] set
        specStatus: "FPWD",

[2] add the following line
noRecTrack: true,

[3] add a sentence to the following as per
   <p id="sotd">... The Working Group expects this document to become a 
Working Group Note.</p>


hth
RI



On 24/05/2013 12:17, Robin Berjon wrote:

Re: Update on the publication process project

Tobie Langel — 2013-05-24T12:49:17

Hacked a script that pulls tr.rdf data and turns it into palatable JSON. 

Now to combine it with the ordered list of authors/editors of specref and profit.

Should be able to deploy the output later today.

I'll keep the process manual for now. We can always automate it later on.

--tobie 


On Tuesday, May 21, 2013 at 1:34 PM, Marcos Caceres wrote:

Re: Let's update the Respec documentation!

Robin Berjon — 2013-05-24T11:17:19

And you're all very happy to know that aren't you? I mean, whoa, a wiki 
page and all! Maybe if we knew where it is we could even edit it!

*cough*

Here's the link:

     https://github.com/darobin/respec/wiki/DocumentationRewrite

Re: Let's update the Respec documentation!

Robin Berjon — 2013-05-24T09:14:21

Hi all,

thanks for getting the ball rolling Marcos.

On 23/05/2013 21:18 , Marcos Caceres wrote:

I've put up a wiki page where we can agree on how to best do this.

*GO WILD* If there's even one small problem you've had, one small aspect 
that you think could be clearer, then we want to know.

Let's update the Respec documentation!

Marcos Caceres — 2013-05-23T19:18:07

Hi Respec Users,

Robin and I are trying to organize a doc sprint to update the Respec documentation [1] and we would really like some help. If this is something you could help with, check out this bug:

https://github.com/darobin/respec/issues/224

In the first pass, we want to reorganize the docs (what we already have, how to split the docs into smaller, clearer bits) and capture that on GitHub.

If you've been using Respec for a while, this is a chance for you to give a little back :) You might also learn a few new undocumented tricks/features.

[1] http://dev.w3.org/2009/dap/ReSpec.js/documentation.html

PS: Sorry if you get this email twice.

Re: ReSpec using external references service is now live

Marcos Caceres — 2013-05-22T17:05:25


On Wednesday, May 22, 2013 at 2:13 PM, Robin Berjon wrote:


Working beautifully! Awesome work Tobie on the new referencing service! :D

ReSpec using external references service is now live

Robin Berjon — 2013-05-22T13:13:39

Dear all,

it's something that we tinkered with several times, but that has finally 
been done and enabled (by Tobie — thanks!). Instead of shipping with its 
references database, ReSpec now consults an external service.

This has several implications:

• The code size that goes over the wire has dropped from 150k to 88k. 
That's a 42% drop. On a decent network, the FOUC is almost gone.

• If you were doing some monkey-patching of the references system in 
spite of multiple warnings that it will break, then the odds are good 
that you have breakage. Last I checked most people had stopped doing 
that so I hope things are okay.

• You can still have references private to your draft using localBiblio.

• When you want to make a change to the references, the place to do so 
is now: https://github.com/tobie/specref. This still requires editing 
the JSON file (for now). But the big advantage is that there is now no 
need to wait for a ReSpec build before your change will show up. As soon 
as a pull reque

Re: Update on the publication process project

Marcos Caceres — 2013-05-21T11:34:28



On Tuesday, May 21, 2013 at 12:19 PM, Robin Berjon wrote:


I'm sure I've asked for this a few times.  

Absolutely. Would make keeping Respec's biblio up to date a breeze!

Re: Update on the publication process project

Robin Berjon — 2013-05-21T11:19:33

One thing that I recall was brought up during the TPAC session (but I 
forget who said it) was that it would be useful to have some JSON dump 
of the TR information so that people could write their own interfaces. I 
forget if what came out was that that dump already existed but people 
didn't know where to find it, or if it wasn't but was easy to generate, 
but I recall (dimly) that there was general agreement that it could be 
useful (especially if CORS-accessible).

Update on the publication process project

Philippe Le Hegaret — 2013-05-20T16:08:12

Hi folks,

some of you may remember the TPAC session we had last year on the
publication process, ie pubrules and /TR. Here is an update on some of
our (small) progress.

Denis, who is spending his last weeks with us, has been working on
rewriting from scratch a good chunk of our back end tools for
publication. The current tools are basically ancient and are getting
more and more unusable. As such, he came up with a new DB to maintain
all the information on /TR documents and is currently trying to get it
up and running before his departure. The difficulty was to represent all
the corner cases the webmaster faces when handling publications.

Once he is done, there will be no visible change from the point of view
of the editors and our site users. The main change will be in the back
end. However, the new DB will be a lot more flexible and will allow us
to add new information more easily. One of the information that I'm
interested in exposing is the links to editor's drafts, which will allow
us to generate a ve

Re: Respec bugs

Richard Ishida — 2013-05-07T14:55:46

I guess that what threw me initially was the specStatus name FPWD-NOTE, 
which I think should be just FP-NOTE or some such - since a NOTE that is 
published straight away isn't a WD.  I read it as FPWD intended to 
eventually become a NOTE. Wrong!

It would be helpful to add a note (small n) to 
http://dev.w3.org/2009/dap/ReSpec.js/documentation.html#saving-the-generated-specification 
to clarify this. It currently says (my emphasis):

"Some of the header notably depends on whether the specification is on 
"Rec-track", *which is the case if* the specStatus is one of: "FPWD", 
"WD", "LC", "CR", "PR", "PER", or "REC"."

which gives the impression that FPWD what you pick for docs intended for 
the Rec track, and doesn't hint to you that you can actually have a FPWD 
but still set noRecTrack to true.  Presumably that same applies to WD, 
if you take a few iterations before NOTE publication.

RI


On 07/05/2013 15:44, Robin Berjon wrote:

Re: Respec bugs

Richard Ishida — 2013-05-07T14:44:58

These two issues are also solved by selecting FPWD rather than 
FPWD-NOTE, and setting noRecTrack to true.  I added a sentence to the 
user-supplied para in the SOTD to say "The Working Group expects this 
document to become a Working Group Note.", since otherwise respec 
doesn't add anything.

So the moral of the story seems to be to do the three things above if 
you want to publish a FPWD of a document intended to be a WG NOTE.


RI


On 07/05/2013 13:05, Richard Ishida wrote:

Re: Respec bugs

Robin Berjon — 2013-05-07T14:44:52

Yes, that happens to be the way to publish a first public Note. You have 
to not make it a Note. Don't blame ReSpec for that :)

Re: Respec bugs

Ian Jacobs — 2013-05-07T14:44:40

On May 7, 2013, at 9:28 AM, Robin Berjon <robin< at >w3.org> wrote:



Notes were used for about everything 20 years ago. Over time we decided to try this model:

 * There are 2 formal end states for W3C tech reports: Rec and Note.
 * There are 2 formal start states: WD and Note.  (Thus, Note can be both start and end state).
 * If a group plans to work on a thing that they intend to make a note, they should publish WD, WD, WD, Note.
 * Of course even something that you think you are done with you may choose to revise later. So a "Note" means "done" in the
   sense of "at least for now we think we are done."

Ian



 

--
Ian Jacobs <ij< at >w3.org>      http://www.w3.org/People/Jacobs
Tel:                                          +1 718 260 9447

Re: Respec bugs

Richard Ishida — 2013-05-07T14:41:02

This goes away if you select FPWD rather than FPWD-NOTE, and set 
noRecTrack to true.

RI


On 07/05/2013 13:14, Richard Ishida wrote:

Re: Respec bugs

Robin Berjon — 2013-05-07T14:28:46

To be honest I have no clue whatsoever what FPWD-NOTE is supposed to do. 
At some point there was a lot of confusion over the process to publish 
Notes, and this confusion is supported in the code. I *think* that the 
correct thing is to remove everything related to Notes that isn't final 
since those are handled by the WD process.

I still think that the Note process makes no sense whatsoever, but 
that's a battle I've given up on :)

Re: Respec bugs

Richard Ishida — 2013-05-07T14:22:51

Scratch [4]. Looks like you need to choose FPWD, rather than FPWD-NOTE, 
and set noRecTrack to true.

I'd recommend changing FPWD-NOTE to FPNOTE to make things clearer, if 
that is really what is intended.

RI


On 07/05/2013 14:41, Richard Ishida wrote:

Re: Respec bugs

Richard Ishida — 2013-05-07T13:41:55

[sending here for the sake of completeness]

[4] the This Version link that is generated is
http://www.w3.org/TR/2013/NOTE-klreq-20130514/

it should be
http://www.w3.org/TR/2013/WD-klreq-20130514/

since this is just a FPWD.

RI


On 07/05/2013 13:14, Richard Ishida wrote:

Re: Respec bugs

Marcos Caceres — 2013-05-07T12:15:05

Hi Richard, 

On Tuesday, May 7, 2013 at 1:05 PM, Richard Ishida wrote:


Here:
https://github.com/darobin/respec/issues

The above is a bug with pub rules, so you will need to ask the maintainer of pub rules about that one.  "//www.w3.org/StyleSheets/TR/W3C-WG-NOTE" is a perfectly valid URI (the validator should just prepend "http" to it).