Revised APA Style

CSL Development
1

Replying to the list.

I have comments/questions about CSL proper, and some about your specific
modeling choices for the style. Note: I’m pretty exhausted and not
thinking too clearly, but will just send these anyway just to keep
things moving. Consider this rather stream-of-consciousness …

Simon Kornblith wrote:

I have a parser that is currently capable of parsing the following into
what appears to be proper APA style, at least for the bibliography. Let
me know what you think.

First this isn’t based on my draft schema, since I don’t use “field.”
Beyond that …

        <name and="symbol" initialize-with="." delimiter=", "/>

I don’t mean to backtrack on the “option” question, but if we’re going
to be consistent, wouldn’t the above be:

 <option name="and" value="symbol"/>

…?

Do we want to do that? Or switch back to all attributes? Does
consistency matter?

Also, do we need the separate name element?

        <label form="short" prefix=", " text-transform="capitalize"

suffix=“.”/>









Just noting another mild inconsistency. It might be nice given the
now-list nature of the variable attribute to be able to do:

...

… where the attribute value is understood as an ordered list, though
I’m not sure it’s possible (given need for choose among others; wonder,
though, if a choose itself could be a macro?).

        </substitute>
    </agent>
</macro>
<macro name="author-short">
    <agent field="author" form="short" and="symbol" delimiter=", ">
        <name/>
        <substitute>
            <agent field="editor"/>
            <agent field="translator"/>
            <choose>
                <if type="book">
                    <text field="title" form="short"

font-style=“italic”/>















So what do you think about this event thing then? Does it work, or do
need to tweak this?

        <group prefix=", ">
            <text term-name="from" suffix=" "/>
            <text field="URL"/>
        </group>
    </group>
</macro>
<macro name="title">
    <choose>
        <if type="book">
            <text field="title" font-style="italic"/>
        </if>

Here’s where I worry a little. In your modeling, you’re tying formatting
exclusively to type.

So the question is, do we retain the inheritance schema, where book and
article are understood as structural fallbacks?

If not, then we definitely need to avoid relying on type too much in the
styles, because it will fail in a lot of cases. Even if we keep it we
might want to be careful with using type too much.

Think more:

I think that’s it for now.

Bruce>

2

First this isn’t based on my draft schema, since I don’t use “field.”

Yes, but I thought in previous correspondence you mentioned that you
preferred “field” to “variable”? If you want “variable,” we can keep it.

Beyond that …

        <name and="symbol" initialize-with="." delimiter=", "/>

I don’t mean to backtrack on the “option” question, but if we’re going
to be consistent, wouldn’t the above be:

 <option name="and" value="symbol"/>

…?

Do we want to do that? Or switch back to all attributes? Does
consistency matter?

I thought we would use for context-level options, and
attributes for settings that apply only to a single element.

Also, do we need the separate name element?

Well, the other option is to replace:

With:

When we think about substitution, this calls for:


I think that we’re better off leaving things as they are.

        <label form="short" prefix=", " text-

transform=“capitalize”
suffix=“.”/>









Just noting another mild inconsistency. It might be nice given the
now-list nature of the variable attribute to be able to do:

...

… where the attribute value is understood as an ordered list, though
I’m not sure it’s possible (given need for choose among others;
wonder,
though, if a choose itself could be a macro?).

I’m not entirely sure why it’s an inconsistency. However, a macro has
to be an option. Otherwise we can’t format author-date styles
properly. One option is:

Another is to ditch entirely and use s, although the
problem is that substitute also suppresses future instances of the
field (so the editor doesn’t appear both first and in the position
for a book with an author and an editor, for example), while
doesn’t do this (although we could mimic this behavior with more
s, or add a suppress=“true” tag).

        </substitute>
    </agent>
</macro>
<macro name="author-short">
    <agent field="author" form="short" and="symbol"

delimiter=", ">






















So what do you think about this event thing then? Does it work, or do
need to tweak this?

It works. It’s kind of peculiar where I have later on, but it might be useful
for dealing with, e.g., conference proceedings.

        <group prefix=", ">
            <text term-name="from" suffix=" "/>
            <text field="URL"/>
        </group>
    </group>
</macro>
<macro name="title">
    <choose>
        <if type="book">
            <text field="title" font-style="italic"/>
        </if>

Here’s where I worry a little. In your modeling, you’re tying
formatting
exclusively to type.

So the question is, do we retain the inheritance schema, where book
and
article are understood as structural fallbacks?

Why not? and can both
be true. The fallbacks are useful for many reasons.

Simon

3

Simon Kornblith wrote:

First this isn’t based on my draft schema, since I don’t use “field.”

Yes, but I thought in previous correspondence you mentioned that you
preferred “field” to “variable”? If you want “variable,” we can keep it.

No, I prefer “variable”; “field” sounds to me to too-literally be
referring to a form or something, when it’s really an abstract data binding.

…

Also, do we need the separate name element?

Well, the other option is to replace:

Actually, I was not thinking about entirely removing the element (it is
needed); just wondering about doing:

<text variable="name"/>

I think that we’re better off leaving things as they are.

OK.

…

Another is to ditch entirely and use s, although the
problem is that substitute also suppresses future instances of the
field (so the editor doesn’t appear both first and in the position
for a book with an author and an editor, for example), while
doesn’t do this (although we could mimic this behavior with more
s, or add a suppress=“true” tag).

Yes, tricky. I guess might as well keep things as is.

…

        <event field="accessed">
            <month suffix=" "/>
            <day suffix=", "/>
            <year/>
        </event>

So what do you think about this event thing then? Does it work, or do
need to tweak this?

It works. It’s kind of peculiar where I have later on,

Hmm … missed that; you’re referring to this:

 <macro name="publisher">
     <group delimiter=": ">
         <event field="published">
             <place/>
         </event>
         <text field="publisher"/>
     </group>
 </macro>

This is not how I was envisioning it; I was thinking something like:

 <macro name="publisher">
   <agent variable="publisher" delimiter=":">
      <name/>
      <text variable="address"/> <!-- or "place" -->
   </agent>
 </macro>

E.g. a publisher is an agent object; not a simple string.

There are actually some cases in which there is more than one publisher,
BTW.

but it might be useful
for dealing with, e.g., conference proceedings.

        <group prefix=", ">
            <text term-name="from" suffix=" "/>
            <text field="URL"/>
        </group>
    </group>
</macro>
<macro name="title">
    <choose>
        <if type="book">
            <text field="title" font-style="italic"/>
        </if>

Here’s where I worry a little. In your modeling, you’re tying
formatting
exclusively to type.

So the question is, do we retain the inheritance schema, where book
and
article are understood as structural fallbacks?

Why not? and can both
be true. The fallbacks are useful for many reasons.

OK, agreed. But you see my point that types generally become less
important with the new choose conditional; right?

Bruce

4

Simon Kornblith wrote:

First this isn’t based on my draft schema, since I don’t use
“field.”

Yes, but I thought in previous correspondence you mentioned that you
preferred “field” to “variable”? If you want “variable,” we can
keep it.

No, I prefer “variable”; “field” sounds to me to too-literally be
referring to a form or something, when it’s really an abstract data
binding.

OK. This isn’t a difficult thing to change.

Also, do we need the separate name element?

Well, the other option is to replace:

Actually, I was not thinking about entirely removing the element
(it is
needed); just wondering about doing:

<text variable="name"/>

We could do this, if we didn’t care about putting attributes on <name/

(where they belong, IMHO). I also think it will actually make
things clearer in the long run, because the variables here are
different from the top-level variables and should be treated (and
validated) as such.

        <event field="accessed">
            <month suffix=" "/>
            <day suffix=", "/>
            <year/>
        </event>

So what do you think about this event thing then? Does it work,
or do
need to tweak this?

It works. It’s kind of peculiar where I have later on,

Hmm … missed that; you’re referring to this:

 <macro name="publisher">
     <group delimiter=": ">
         <event field="published">
             <place/>
         </event>
         <text field="publisher"/>
     </group>
 </macro>

This is not how I was envisioning it; I was thinking something like:

 <macro name="publisher">
   <agent variable="publisher" delimiter=":">
      <name/>
      <text variable="address"/> <!-- or "place" -->
   </agent>
 </macro>

E.g. a publisher is an agent object; not a simple string.

There are actually some cases in which there is more than one
publisher,
BTW.

This code still doesn’t specify how to format things if there are
multiple publishers. To do that, we’d need something like:

(assuming we want commas between publishers). But this is really a
fringe case, at least as far as I see it.

One more issue: what to do with locators in citations (which might be
either paragraph/paragraphs, page/pages, etc.). I suggest we allow
to take care of this. Maybe we should
also allow to handle the p./pp. issue in
the bibliography. What do you think?

Simon

5

I was just about to send this when you sent a reply to the list, Simon,
but will send anyway since I doubt this conflicts with it …

Bruce D’Arcus wrote:

This is not how I was envisioning it; I was thinking something like:

<macro name="publisher">
  <agent variable="publisher" delimiter=":">
     <name/>
     <text variable="address"/> <!-- or "place" -->
  </agent>
</macro>

E.g. a publisher is an agent object; not a simple string.

This presents an interesting conceptual problem, and I’m finding myself
getting a little confused.

When we have something like:

<text variable="container-title"/>

… we’re assuming a flat model, or least a flat encoding (that may
signal a relation).

But when we have:

  <macro name="publisher">
    <agent variable="publisher" delimiter=":">
       <name/>
       <text variable="address"/> <!-- or "place" -->
    </agent>
  </macro>

… we’re now no longer flat. The scope of the name and address has now
shifted from the cited resource to the related contributor (the publisher).

If we found that a problem, we’d probably want instead:

  <macro name="publisher">
    <agent variable="publisher" delimiter=":">
       <text variable="publisher-name"/>
       <text variable="publisher=address"/> <!-- or "place" -->
    </agent>
  </macro>

But in any case I’d say we’d have to document exactly what’s going on
from a logical and modeling standpoint in either case.

And if we went consistently flat, what value does the agent
element/object provide? E.g the above could be:

  <macro name="publisher">
    <group name="publisher" delimiter=":">
       <text variable="publisher-name"/>
       <text variable="publisher=address"/> <!-- or "place" -->
    </group>
  </macro>

… or even:

  <macro name="publisher-distributor">
    <group delimiter=":">
       <text variable="publisher-name distributor-name"/>
       <text variable="publisher=address distributor-address"/>
    </group>
  </macro>

So you see what I’m getting at Simon?

Bruce

6

As an experiment, I removed the agent, event and name elements from the
schema, and moved them to simple variables. It results in a much simpler
schema, and in stuff like this (I assume “author” is basically
"author-name" and so forth):

I’ve checked it in if you want to take a look Simon, though we can
always revert if there’s something dumb about this I’m not thinking
about at the moment.

Bruce

7

As an experiment, I removed the agent, event and name elements from
the
schema, and moved them to simple variables. It results in a much
simpler
schema, and in stuff like this (I assume “author” is basically
“author-name” and so forth):

I’ve checked it in if you want to take a look Simon, though we can
always revert if there’s something dumb about this I’m not thinking
about at the moment.

How do you format the contributors? You can’t just use
because editors/translators have to be formatted differently from
authors. And how do you do to specify contributor labels (a problem I
brought up in a previous email)?

How do you format dates? Date accessed is often formatted differently
from date published, so again, won’t work. Separating agent/
event elements from text elements does complicate the schema, but I
really can’t see how to avoid it.

Also, why …</

?

Simon

8

First, I think there are good reasons for most of the design decisions
of the current schema, so my thinking here is partly brain-storming to
see what the best alternative is. The thing is, if we’re going to do a
real alternative, we need to strive for both simplicity and consistency.
If I find myself getting confused, then there’s something wrong.

But …

Simon Kornblith wrote:

How do you format the contributors? You can’t just use
because editors/translators have to be formatted differently from
authors.

The question is how are they "formatted differently? I’d say the only
difference is the labels; not how the names are formatted.

So how about:

… and then:

<macro name="author">
   <text variable="author"/>
   <substitute>
     <choose>
       <if variable="editor">
         <text macro="editor-substitute"/>
       </if>
       <else-if variable="translator">
         <text macro="translator-substitute"/>
       </else-if>
     </choose>
   </substitute>
 </macro>

E.g. throw out cs:label, and achieve context-specific label placement
using a mix of cs:choose and cs:macro?

And how do you do to specify contributor labels (a problem I
brought up in a previous email)?

Directly:

<macro name="translator">
  <text variable="translator"/>
  <text term="translator"/>
</macro>

How do you format dates? Date accessed is often formatted differently
from date published, so again, won’t work.

It’d probably have to work the same as names; a mix of options and macros:

Separating agent/event elements from text elements does complicate the schema, but I
really can’t see how to avoid it.

It would definitely require using more option parameters.

Also, why …</

?

To avoid requiring cs:label.

The basic logic of what I’m wondering here is whether the combination of
cs:macro and cs:choose doesn’t offer a whole lot of power that makes it
possible to simplify the schema (and resulting code) quite a bit.

Bruce

9

The question is how are they "formatted differently? I’d say the
only
difference is the labels; not how the names are formatted.

APA (and probably others) disagrees. An edited book with authors:

Plath, S. (2000). The unabridged journals (K.V. Kukil, Ed.). New
York: Anchor.

name-as-sort-order and delimiter-precedes-last both change for editor/
translator. Why are we removing configurability?

So how about:

… and then:

<macro name="author">
   <text variable="author"/>
   <substitute>
     <choose>
       <if variable="editor">
         <text macro="editor-substitute"/>
       </if>
       <else-if variable="translator">
         <text macro="translator-substitute"/>
       </else-if>
     </choose>
   </substitute>
 </macro>

E.g. throw out cs:label, and achieve context-specific label placement
using a mix of cs:choose and cs:macro?

And how do you do to specify contributor labels (a problem I
brought up in a previous email)?

Directly:

<macro name="translator">
  <text variable="translator"/>
  <text term="translator"/>
</macro>

Does term=“translator” automatically become plural if there are
multiple translators, then?

How do you format dates? Date accessed is often formatted differently
from date published, so again, won’t work.

It’d probably have to work the same as names; a mix of options and
macros:

What if the date published should only be a year, while the date
accessed needs to be Month Day, Year? Furthermore, what do you do
about styles that put the year near the beginning and the month/day
elsewhere in the citation?

Separating agent/event elements from text elements does complicate
the schema, but I
really can’t see how to avoid it.

It would definitely require using more option parameters.

But, unless you plan to allow different “contexts” with different
options inside (which doesn’t seem
clean to me), there’s no way to format styles properly.

Also, why …</

?

To avoid requiring cs:label.

The basic logic of what I’m wondering here is whether the
combination of
cs:macro and cs:choose doesn’t offer a whole lot of power that
makes it
possible to simplify the schema (and resulting code) quite a bit.

This does not simplify the styles! We previously got away with:

Now we need:

In order to simplify the schema, we’ve sacrificed the compactness of
our CSLs and, at least in the current incarnation of this idea, our
ability to format styles properly. I have a strong preference for the
previous revision.

Simon

10

Simon Kornblith wrote:

The question is how are they "formatted differently? I’d say the
only
difference is the labels; not how the names are formatted.

APA (and probably others) disagrees. An edited book with authors:

Plath, S. (2000). The unabridged journals (K.V. Kukil, Ed.). New
York: Anchor.

OK, point taken.

name-as-sort-order and delimiter-precedes-last both change for editor/
translator.

They actually don’t change depending on the role; they change depending
on the position.

Why are we removing configurability?

As I said, this is an experiment in simplification; might as well at
least reconsider everything while we’re at it, even if we throw an idea
out …

In order to simplify the schema, we’ve sacrificed the compactness of
our CSLs and, at least in the current incarnation of this idea, our
ability to format styles properly. I have a strong preference for the
previous revision.

OK, fair enough. But the problem we’re faced with is: what’s the logic
such that we can clearly document it for style authors and programmers?
At least this is what I’m worried about, with all the
choose/variable/macro/term/label/substitute stuff now going on.

It doesn’t help if we have nice compact styles if they’re confusing to
people to read and (in particular) write.

If you/we could document the previous revision of the branch schema in
such a way that my worries are alleviated, that would definitely help,
and we could go from there.

Might help too to see if we could handle Ramesh’s IEEE style!

Bruce

11

OK, fair enough. But the problem we’re faced with is: what’s the logic
such that we can clearly document it for style authors and
programmers?
At least this is what I’m worried about, with all the
choose/variable/macro/term/label/substitute stuff now going on.

It doesn’t help if we have nice compact styles if they’re confusing to
people to read and (in particular) write.

If you/we could document the previous revision of the branch schema in
such a way that my worries are alleviated, that would definitely help,
and we could go from there.

I wouldn’t mind writing up some more comprehensive HTML documentation
at some point. Documentation is certainly preferable to
simplification of the schema to the point where it can no longer
represent what it needs to.

Might help too to see if we could handle Ramesh’s IEEE style!

I’m not entirely sure what to do to handle indentation. Maybe allow
something like (not quite
sure what to call the value). However, I think users are fairly
lenient about indentation (as opposed to the formatting of the
references themselves).

The online/in print issue is moot, at least from Zotero’s point of
view. In Zotero, unless an article can be retrieved from a given
location, the URL field isn’t populated, so
should suffice.

The FTP/HTTP issue is difficult to address. Perhaps ?

Simon

12

Simon Kornblith wrote:

I wouldn’t mind writing up some more comprehensive HTML documentation
at some point. Documentation is certainly preferable to
simplification of the schema to the point where it can no longer
represent what it needs to.

The reason I raise the issue of documentation is not just because we
need it (and we do), but because I want to make sure it CAN be
documented. E.g. that it makes sense, is consistent logically, etc.

Given that you’ve written a parser that seems to work, I presume it is,
but I was just getting worried thinking through some of the details.
Commenting the schema as we modify it can at least test this (well,
along with working code of course).

Might help too to see if we could handle Ramesh’s IEEE style!

I’m not entirely sure what to do to handle indentation. Maybe allow
something like (not quite
sure what to call the value). However, I think users are fairly
lenient about indentation (as opposed to the formatting of the
references themselves).

It might be:

 <option name="label-position" value="margin"/>

The online/in print issue is moot, at least from Zotero’s point of
view. In Zotero, unless an article can be retrieved from a given
location, the URL field isn’t populated, so
should suffice.

The FTP/HTTP issue is difficult to address. Perhaps ?

That would set the condition, but it wouldn’t solve the problem of
formatting it: breaking apart an FTP URI into the protocol, server, path
and file (which is insane really!).

That might constitute an edge case that we have to consider beyond scope?

Bruce

13

I’d be incline to agree. It seems like the style dates back to
command-line FTP, before there were ftp:// URLs. A quick check seems
to indicate that EndNote doesn’t put a URL into IEEE citations at
all, even if the reference type is “Electronic Article,” so no matter
what we do it should be better than this.

Simon

14

Simon Kornblith wrote:

I’d be incline to agree. It seems like the style dates back to
command-line FTP, before there were ftp:// URLs.

Yes, that makes sense. It also explains why some styles have such
bizarre treatment of electronic resources in general.

I really hate it when we have to make everything more complicated on our
end just to accommodate legacy conventions that make nobody’s life
(author, reader, programmer, copy editor) easier!

Bruce