ReSpec and references

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

ReSpec and references

Shane McCarron
So.... today during the PFWG Editors meeting, I learned that there is a
W3C standard way to do citations: http://www.w3.org/2001/06/manual/#citation

Sadly, this is not the way ReSpec does it - and it is not super easy to
change ReSpec to do it this way.  I also think it is stupid, but I think
lots of the pubrules are stupid...

Anyway, What I was wondering is if there is a way to extend the current
reference architecture so that it could magically do the text leading up
to the reference AND the reference itself - wrapping them in the silly
cite and a elements, inserting abbr elements as needed.  My first
thought was to do something like this:

[[[lead in reference string]REFERENCE]] - that would be backward
compatible so existing specs wouldn't change and we wouldn't need to
change the bibliography file.  On the other hand, it would not magically
deal with abbreviations...

Another idea was that we just continue to use [[REFERENCE]], but allow
an extension to the biblio file that, if present, would supply the
lead-in text, the reference, and any necessary abbreviations.  This
would require changes to any spec that used ReSpec and used references
that were so annotated though.  That seems like a bad idea.

Finally, I considered some more subtle extension combined with changing
the biblio file.  Like [[@REFERENCE]] would mean insert a reference and
the standard lead-in for it.  [[REFERENCE]] would work as it always had,
albeit also adding the surrounding <cite> element.

Thoughts?

--
Shane P. McCarron                          Phone: +1 763 786-8160 x120
Managing Director                            Fax: +1 763 786-8180
ApTest Minnesota                            Inet: [hidden email]



Reply | Threaded
Open this post in threaded view
|

Re: ReSpec and references

Gregg Kellogg
I think the proper way to deal with this is through using fragments. For instance, [[CSS#named-pages]]. The question is, how to extract the relevant information to make a reasonable reference?

Ultimately, bibliography information should be scoured from the documents themselves, presumably marked up with RDFa, as you've helped facilitate. Other documents might be processed using a GRDDL-like process to construct similar information, then a reference processor can make reasonable references using information defined in the document itself.

For example, from the recent RDFa-core document, we get statements such as the following:

@base <http://www.w3.org/2010/02/rdfa/drafts/2010/WD-rdfa-core-20100803/> .
@prefix bibo: <http://purl.org/ontology/bibo/> .
@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix xhv: <http://www.w3.org/1999/xhtml/vocab#> .

<> dcterms:title "RDFa Core 1.1";
  dcterms:issued "2010-08-03T05:00:00+0000"^^<http://www.w3.org/2001/XMLSchema#dateTime>;
   dcterms:publisher [ a foaf:Organization;
     foaf:homepage <http://www.w3.org/>;
     foaf:name "World Wide Web Consotrium"];
   bibo:editor [ a foaf:Person;
     foaf:mbox <mailto:[hidden email]>;
     foaf:name "Ben Adida";
     foaf:workplaceHomepage <http://creativecommons.org/>],
   [ a foaf:Person;
     foaf:mbox <mailto:[hidden email]>;
     foaf:name "Mark Birbeck";
     foaf:workplaceHomepage <http://webbackplane.com/>],
   [ a foaf:Person;
     foaf:homepage <http://blog.halindrome.com/>;
     foaf:mbox <mailto:[hidden email]>;
     foaf:name "Shane McCarron";
     foaf:workplaceHomepage <http://www.aptest.com/>],
   [ a foaf:Person;
     foaf:mbox <mailto:[hidden email]>;
     foaf:name "Ivan Herman";
     foaf:workplaceHomepage <http://www.w3.org/>];
<#accessing-the-processor-graph> a bibo:Chapter .
<#chaining> a bibo:Chapter .
<#changing-the-evaluation-context> a bibo:Chapter .
<#compact-uris> a bibo:Chapter .
<#conformance> a bibo:Chapter .
<#creating-a-new-item-with--typeof> a bibo:Chapter .
<#determining-the-subject-with-neither--about-nor--typeof> a bibo:Chapter .

Actually, the code could be a bit better, and extract section titles as well, for example:

<#accessing-the-processor-graph> a bibo:Chapter .
  dcterms:title "7.6.1 Accessing the Processor Graph" .

A reference could then be made to [[RDFA-CORE#accessing-the-processor-graph]] which could create something like the following:

...as discussed in <a href="http://www.w3.org/2010/02/rdfa/drafts/2010/WD-rdfa-core-20100803/accessing-the-processor-graph">Section 7.6.1 Accessing the Processor Graph</a> of [<cite><a href="#ref-RDFA-CORE">RDFA-CORE</a></cite>]

Of course, given the RDF graph, we don't need to maintain biblio files, and could simply make a reference to [[http://www.w3.org/2010/02/rdfa/drafts/2010/WD-rdfa-core-20100803/accessing-the-processor-graph]], which could extract everything needed for making a reference from the RDF itself. Biblio files are useful when the source isn't in a standard RDF graph and statements need to either be created by hand, or though a separate processing step. It should be easy enough to process the existing biblio files to create information in RDFa format suitable for creating such references.

Gregg

On Jul 28, 2010, at 12:28 PM, Shane McCarron wrote:

> So.... today during the PFWG Editors meeting, I learned that there is a
> W3C standard way to do citations: http://www.w3.org/2001/06/manual/#citation
>
> Sadly, this is not the way ReSpec does it - and it is not super easy to
> change ReSpec to do it this way.  I also think it is stupid, but I think
> lots of the pubrules are stupid...
>
> Anyway, What I was wondering is if there is a way to extend the current
> reference architecture so that it could magically do the text leading up
> to the reference AND the reference itself - wrapping them in the silly
> cite and a elements, inserting abbr elements as needed.  My first
> thought was to do something like this:
>
> [[[lead in reference string]REFERENCE]] - that would be backward
> compatible so existing specs wouldn't change and we wouldn't need to
> change the bibliography file.  On the other hand, it would not magically
> deal with abbreviations...
>
> Another idea was that we just continue to use [[REFERENCE]], but allow
> an extension to the biblio file that, if present, would supply the
> lead-in text, the reference, and any necessary abbreviations.  This
> would require changes to any spec that used ReSpec and used references
> that were so annotated though.  That seems like a bad idea.
>
> Finally, I considered some more subtle extension combined with changing
> the biblio file.  Like [[@REFERENCE]] would mean insert a reference and
> the standard lead-in for it.  [[REFERENCE]] would work as it always had,
> albeit also adding the surrounding <cite> element.
>
> Thoughts?
>
> --
> Shane P. McCarron                          Phone: +1 763 786-8160 x120
> Managing Director                            Fax: +1 763 786-8180
> ApTest Minnesota                            Inet: [hidden email]
>
>
>


Reply | Threaded
Open this post in threaded view
|

Re: ReSpec and references

Shane McCarron
I agree that something like this would be really cool.  It would require
more work than I really want to put in right now - and it would require
instrumentation of all W3C specs in order for it to be maximally
useful.  That's a good idea, but it seems like it might be above my pay
grade.

Still pondering...

On 7/29/2010 2:43 PM, Gregg Kellogg wrote:

> I think the proper way to deal with this is through using fragments. For instance, [[CSS#named-pages]]. The question is, how to extract the relevant information to make a reasonable reference?
>
> Ultimately, bibliography information should be scoured from the documents themselves, presumably marked up with RDFa, as you've helped facilitate. Other documents might be processed using a GRDDL-like process to construct similar information, then a reference processor can make reasonable references using information defined in the document itself.
>
> For example, from the recent RDFa-core document, we get statements such as the following:
>
> @base<http://www.w3.org/2010/02/rdfa/drafts/2010/WD-rdfa-core-20100803/>  .
> @prefix bibo:<http://purl.org/ontology/bibo/>  .
> @prefix dcterms:<http://purl.org/dc/terms/>  .
> @prefix foaf:<http://xmlns.com/foaf/0.1/>  .
> @prefix rdf:<http://www.w3.org/1999/02/22-rdf-syntax-ns#>  .
> @prefix xhv:<http://www.w3.org/1999/xhtml/vocab#>  .
>
> <>  dcterms:title "RDFa Core 1.1";
>    dcterms:issued "2010-08-03T05:00:00+0000"^^<http://www.w3.org/2001/XMLSchema#dateTime>;
>     dcterms:publisher [ a foaf:Organization;
>       foaf:homepage<http://www.w3.org/>;
>       foaf:name "World Wide Web Consotrium"];
>     bibo:editor [ a foaf:Person;
>       foaf:mbox<mailto:[hidden email]>;
>       foaf:name "Ben Adida";
>       foaf:workplaceHomepage<http://creativecommons.org/>],
>     [ a foaf:Person;
>       foaf:mbox<mailto:[hidden email]>;
>       foaf:name "Mark Birbeck";
>       foaf:workplaceHomepage<http://webbackplane.com/>],
>     [ a foaf:Person;
>       foaf:homepage<http://blog.halindrome.com/>;
>       foaf:mbox<mailto:[hidden email]>;
>       foaf:name "Shane McCarron";
>       foaf:workplaceHomepage<http://www.aptest.com/>],
>     [ a foaf:Person;
>       foaf:mbox<mailto:[hidden email]>;
>       foaf:name "Ivan Herman";
>       foaf:workplaceHomepage<http://www.w3.org/>];
> <#accessing-the-processor-graph>  a bibo:Chapter .
> <#chaining>  a bibo:Chapter .
> <#changing-the-evaluation-context>  a bibo:Chapter .
> <#compact-uris>  a bibo:Chapter .
> <#conformance>  a bibo:Chapter .
> <#creating-a-new-item-with--typeof>  a bibo:Chapter .
> <#determining-the-subject-with-neither--about-nor--typeof>  a bibo:Chapter .
>
> Actually, the code could be a bit better, and extract section titles as well, for example:
>
> <#accessing-the-processor-graph>  a bibo:Chapter .
>    dcterms:title "7.6.1 Accessing the Processor Graph" .
>
> A reference could then be made to [[RDFA-CORE#accessing-the-processor-graph]] which could create something like the following:
>
> ...as discussed in<a href="http://www.w3.org/2010/02/rdfa/drafts/2010/WD-rdfa-core-20100803/accessing-the-processor-graph">Section 7.6.1 Accessing the Processor Graph</a>  of [<cite><a href="#ref-RDFA-CORE">RDFA-CORE</a></cite>]
>
> Of course, given the RDF graph, we don't need to maintain biblio files, and could simply make a reference to [[http://www.w3.org/2010/02/rdfa/drafts/2010/WD-rdfa-core-20100803/accessing-the-processor-graph]], which could extract everything needed for making a reference from the RDF itself. Biblio files are useful when the source isn't in a standard RDF graph and statements need to either be created by hand, or though a separate processing step. It should be easy enough to process the existing biblio files to create information in RDFa format suitable for creating such references.
>
> Gregg
>
> On Jul 28, 2010, at 12:28 PM, Shane McCarron wrote:
>
>    
>> So.... today during the PFWG Editors meeting, I learned that there is a
>> W3C standard way to do citations: http://www.w3.org/2001/06/manual/#citation
>>
>> Sadly, this is not the way ReSpec does it - and it is not super easy to
>> change ReSpec to do it this way.  I also think it is stupid, but I think
>> lots of the pubrules are stupid...
>>
>> Anyway, What I was wondering is if there is a way to extend the current
>> reference architecture so that it could magically do the text leading up
>> to the reference AND the reference itself - wrapping them in the silly
>> cite and a elements, inserting abbr elements as needed.  My first
>> thought was to do something like this:
>>
>> [[[lead in reference string]REFERENCE]] - that would be backward
>> compatible so existing specs wouldn't change and we wouldn't need to
>> change the bibliography file.  On the other hand, it would not magically
>> deal with abbreviations...
>>
>> Another idea was that we just continue to use [[REFERENCE]], but allow
>> an extension to the biblio file that, if present, would supply the
>> lead-in text, the reference, and any necessary abbreviations.  This
>> would require changes to any spec that used ReSpec and used references
>> that were so annotated though.  That seems like a bad idea.
>>
>> Finally, I considered some more subtle extension combined with changing
>> the biblio file.  Like [[@REFERENCE]] would mean insert a reference and
>> the standard lead-in for it.  [[REFERENCE]] would work as it always had,
>> albeit also adding the surrounding<cite>  element.
>>
>> Thoughts?
>>
>> --
>> Shane P. McCarron                          Phone: +1 763 786-8160 x120
>> Managing Director                            Fax: +1 763 786-8180
>> ApTest Minnesota                            Inet: [hidden email]
>>
>>
>>
>>      
>
>    

--
Shane P. McCarron                          Phone: +1 763 786-8160 x120
Managing Director                            Fax: +1 763 786-8180
ApTest Minnesota                            Inet: [hidden email]



Reply | Threaded
Open this post in threaded view
|

Re: ReSpec and references

Robin Berjon-2
In reply to this post by Shane McCarron
Hey,

sorry for not answering earlier, I've been on vacation!

On Jul 28, 2010, at 21:28 , Shane McCarron wrote:
> Sadly, this is not the way ReSpec does it - and it is not super easy to change ReSpec to do it this way.  I also think it is stupid, but I think lots of the pubrules are stupid...

Now now, that's not quite the spirit ;-) This doesn't read like a pubrule to me, it's just from the manual of style. I tend to think that that's open to reasonable interpretation — what isn't is checked by the tools (and hopefully that part isn't stupid).

In this case I don't see this as a strong requirement. First, editors will often spontaneously make the first mention of a reference properly expanded. Second, they will know better what "first mention" is, whether it's the one in the abstract or the one in the intro or both, whether to reintroduce it in the 77th subsection of the 42nd section, etc. Thirdly, a number of such references are self-explicit (e.g. [XML]). Finally, there's a link *right there* to the reference section that has the full name and the link. I'd say we're good.

> Anyway, What I was wondering is if there is a way to extend the current reference architecture so that it could magically do the text leading up to the reference AND the reference itself - wrapping them in the silly cite and a elements, inserting abbr elements as needed.  My first thought was to do something like this:
>
> [[[lead in reference string]REFERENCE]] - that would be backward compatible so existing specs wouldn't change and we wouldn't need to change the bibliography file.  On the other hand, it would not magically deal with abbreviations...

I'd like to avoid that if at all possible. The point of picking an HTML-based format with a limited set of shortcuts was to avoid the wiki-language conundrum of simplifying things to the point where you've invented a syntax that makes the raw HTML look good.

> Another idea was that we just continue to use [[REFERENCE]], but allow an extension to the biblio file that, if present, would supply the lead-in text, the reference, and any necessary abbreviations.  This would require changes to any spec that used ReSpec and used references that were so annotated though.  That seems like a bad idea.

Yup, breaking existing content bad :)

> Finally, I considered some more subtle extension combined with changing the biblio file.  Like [[@REFERENCE]] would mean insert a reference and the standard lead-in for it.  [[REFERENCE]] would work as it always had, albeit also adding the surrounding <cite> element.

Adding the <cite> is fine (I see you've done that, great!). I'm in favour of [[@REFERENCE]] if someone wants to pick it up, but I don't consider it high priority enough to put in the work myself.

--
Robin Berjon - http://berjon.com/




Reply | Threaded
Open this post in threaded view
|

Re: ReSpec and references

Shane McCarron
  I agree with your conclusion, and I also don't have any energy for
it.  It seems, as I said, silly.

On 8/17/2010 8:38 AM, Robin Berjon wrote:

> Hey,
>
> sorry for not answering earlier, I've been on vacation!
>
> On Jul 28, 2010, at 21:28 , Shane McCarron wrote:
>> Sadly, this is not the way ReSpec does it - and it is not super easy to change ReSpec to do it this way.  I also think it is stupid, but I think lots of the pubrules are stupid...
> Now now, that's not quite the spirit ;-) This doesn't read like a pubrule to me, it's just from the manual of style. I tend to think that that's open to reasonable interpretation — what isn't is checked by the tools (and hopefully that part isn't stupid).
>
> In this case I don't see this as a strong requirement. First, editors will often spontaneously make the first mention of a reference properly expanded. Second, they will know better what "first mention" is, whether it's the one in the abstract or the one in the intro or both, whether to reintroduce it in the 77th subsection of the 42nd section, etc. Thirdly, a number of such references are self-explicit (e.g. [XML]). Finally, there's a link *right there* to the reference section that has the full name and the link. I'd say we're good.
>
>> Anyway, What I was wondering is if there is a way to extend the current reference architecture so that it could magically do the text leading up to the reference AND the reference itself - wrapping them in the silly cite and a elements, inserting abbr elements as needed.  My first thought was to do something like this:
>>
>> [[[lead in reference string]REFERENCE]] - that would be backward compatible so existing specs wouldn't change and we wouldn't need to change the bibliography file.  On the other hand, it would not magically deal with abbreviations...
> I'd like to avoid that if at all possible. The point of picking an HTML-based format with a limited set of shortcuts was to avoid the wiki-language conundrum of simplifying things to the point where you've invented a syntax that makes the raw HTML look good.
>
>> Another idea was that we just continue to use [[REFERENCE]], but allow an extension to the biblio file that, if present, would supply the lead-in text, the reference, and any necessary abbreviations.  This would require changes to any spec that used ReSpec and used references that were so annotated though.  That seems like a bad idea.
> Yup, breaking existing content bad :)
>
>> Finally, I considered some more subtle extension combined with changing the biblio file.  Like [[@REFERENCE]] would mean insert a reference and the standard lead-in for it.  [[REFERENCE]] would work as it always had, albeit also adding the surrounding<cite>  element.
> Adding the<cite>  is fine (I see you've done that, great!). I'm in favour of [[@REFERENCE]] if someone wants to pick it up, but I don't consider it high priority enough to put in the work myself.
>

--
Shane P. McCarron                          Phone: +1 763 786-8160 x120
Managing Director                            Fax: +1 763 786-8180
ApTest Minnesota                            Inet: [hidden email]