Respec: Missing document type for an edited recommendation?

[iherman]

When publishing an Edited Recommendation, the document generated by respec leads to a pubrules checker error, namely:

"It must indicate its relationship to previous related Recommendations (e.g., an indication that a Recommendation supersedes, obsoletes, or subsumes another, or that a Recommendation is an editorial revision) and must link to the most recent Recommendation (if any) having the same major revision number. The document thus links to two important resources: the previous edition of the Recommendation via the status section, and the previous draft (the Proposed [Edited] Recommendation) via the "Previous version" link."

Of course, I can add something by hand (and I will), but that is the kind of boilerplate I would expect respec to do. However, there is no way to indicate that. (There is a 'previous recommendation' field, and that correctly generates a header, but that does not seem to be enough:-(

[darobin]

Indeed, I don't believe that we have that. Templates have been added progressively based on when people needed them; it's entirely possible that this case has not happened yet. ReSpec is ~5 years old so it's plausible that this is the first document started post-2009 to have been to Rec and Rec again :) (Assuming no conversions.)

[halindrome]

We actually have already done this at least once. The text isn't
boilerplate though. It gets included in the sotd section by the author.
There is a way to have a previous recommendation link in the header in
addition to the previous version. RDFa Core 1.1 first recommendation
actually does this (as it supersedes RDFa Syntax 1.0). Ivan, if you would
like me to make the requisite changes I can do that. Just let me know.

On Fri, Feb 6, 2015 at 7:04 AM, Robin Berjon [email protected]
wrote:

Indeed, I don't believe that we have that. Templates have been added
progressively based on when people needed them; it's entirely possible that
this case has not happened yet. ReSpec is ~5 years old so it's plausible
that this is the first document started post-2009 to have been to Rec and
Rec again :) (Assuming no conversions.)

—
Reply to this email directly or view it on GitHub
https://github.com/w3c/respec/issues/399#issuecomment-73233246.

Shane McCarron
[email protected]

[darobin]

Yeah, but if it doesn't generate the boilerplate that's a bug!

[halindrome]

Understood. I just don't think ER is an actual document type. I think the
document type is REC. There is no specific boilerplate that could be
generated that would satisfy all situations. At least I don't think there
is. I will contemplate this a bit though.

On Fri, Feb 6, 2015 at 8:28 AM, Robin Berjon [email protected]
wrote:

Yeah, but if it doesn't generate the boilerplate that's a bug!

—
Reply to this email directly or view it on GitHub
https://github.com/w3c/respec/issues/399#issuecomment-73243904.

Shane McCarron
[email protected]

[darobin]

Well, we already have an option for prevRecommendation (IIRC). I guess that maybe if we had prevRecRelationship = supersedes | obsoletes | subsumes | edits we could perhaps generate a paragraph indicating the relationship in a way that just works? It's not much, but it's one thing less to think about — clearly @iherman would have liked something :)

@iherman Can you give us more details (text, markup, whatever) as to what exactly would have made your life easiest?

[iherman]

On 06 Feb 2015, at 16:51 , Robin Berjon [email protected] wrote:

Well, we already have an option for prevRecommendation (IIRC). I guess that maybe if we had prevRecRelationship = supersedes | obsoletes | subsumes | edits we could perhaps generate a paragraph indicating the relationship in a way that just works? It's not much, but it's one thing less to think about — clearly @iherman would have liked something :)

@iherman Can you give us more details (text, markup, whatever) as to what exactly would have made your life easiest?

To be honest, I do not know exactly. I just added the simplest possible text manually of the form:

This is an editorial revision of the version of this Recommendatation published on XXth of YY, 201Z.

I have also added a reference to the section listing the changes, but that of course pre-supposes that such a section exists:-)

Mind you, the documents have not yet published or even checked by the webmaster:-)

Ivan

—
Reply to this email directly or view it on GitHub.

---

Ivan Herman, W3C
Digital Publishing Activity Lead
Home: http://www.w3.org/People/Ivan/
mobile: [phone]
ORCID ID: http://orcid.org/0000-0003-0782-2704

[saschanaz]

@marcoscaceres Any idea what is the action item here? What should be done?

[marcoscaceres]

@saschanaz, IIRC, we need to add a new specStatus: EDITED-REC.

The respecConf must then include:

• prevRecURI

And we should generate the boiler plate that @iherman mentions: "The document thus links to two important resources: the previous edition of the Recommendation via the status section, and the previous draft (the Proposed [Edited] Recommendation) via the "Previous version" link."

We should find a few "Edited Recommendation" to see exactly what boilerplate they use. Note that, in addition to "Edited Recommendation", there is also an "Amended Recommendation" (AMEND-REC maybe?) which has the same requirements as an edited recommendation, as per the W3C Process doc. We could basically use the same code/template for both.

[plehegar]

For Edited Recommendation that only contain editorial changes, there is no change in the status section except a short mention that it only contains editorial changes compared to the previous publication.
For Amended Recommendations (contains substantive changes but not published by a Working Group), we do have a special patent policy boilerplate. See https://www.w3.org/pubrules/doc/rules/?profile=REC-AMENDED#patPolReq .
For Edited Recommendation that contains substantive changes, they follow the same requirement as normal REC. We don't differentiate.

[plehegar]

Note that there is no previous Proposed Recommendation in the case of an Edited Recommendation that only contains editorial changes. We follow the path REC->REC, as illustrated in https://www.w3.org/2018/Process-20180201/#rec-modify .

[saschanaz]

So this is a summary of what I understand:

1. New specStatus: "EDITED-REC" for editorial changes
   
   
   
   • It should add a short mention that it only contains editorial changes compared to the previous publication
   
   
   • No need to require explicit prevRecURI because the previous version should be REC
   
   
2. New specStatus: "AMEND-REC"
   
   
   
   • Include https://www.w3.org/pubrules/doc/rules/?profile=REC-AMENDED#patPolReq
   
   

Is there anything I missed?

[marcoscaceres]

Ah, yes, prevRecURI won't be needed: I was thinking that would have been a dated URI. The rest sounds right (or at least to start with).

[saschanaz]

The Pubrules uses REC-AMENDED so maybe we should follow it.

Understood. I just don't think ER is an actual document type. I think the document type is REC.

I kind of agree with this, as it's REC->REC not REC->EDITED-REC. Maybe the suggested prevRecRelationship would be better... Thoughts?

[marcoscaceres]

I kind of agree with this, as it's REC->REC not REC->EDITED-REC.

I guess it depends on what shows up at the top of the document (and in the SoTD). If it's just "W3C Recommendation", then agree.

The problem remains:

"except a short mention that it only contains editorial changes compared to the previous publication."

It's possible that Editor's can just manually add this, in which case "REC->REC" holds.

prevRecRelationship

or maybe recHasBeenEdited: true?