Proposal re locators and numbers

[Frank_Bennett]

The current syntax for a locator looks something like this:

This supports only a single label and a page number (I think as a dumb
string, at present). This proposal would provide for multiple
elements in a pinpoint locator. Enhanced syntax for rendering a
locator would be as follows:

The delimiter attribute on the numeral is used to join range elements.
If an implicit test for is-numeric raises false, the locator variable
is rendered as at present (as a single plain string preceded, in the
example above, by the primary locator label).

Comments?

[Bruce_D_Arcus1]

I won’t have time to think about this for a few days, but would ask
others to take a look and comment. I don’t recall there being any
particular problem with locators.

Bruce

[Frank_Bennett]

The current syntax for a locator looks something like this:

This supports only a single label and a page number (I think as a dumb
string, at present). This proposal would provide for multiple
elements in a pinpoint locator. Enhanced syntax for rendering a
locator would be as follows:

The delimiter attribute on the numeral is used to join range elements.
If an implicit test for is-numeric raises false, the locator variable
is rendered as at present (as a single plain string preceded, in the
example above, by the primary locator label).

Comments?

I won’t have time to think about this for a few days, but would ask
others to take a look and comment. I don’t recall there being any
particular problem with locators.

I’m confused, then. Everyone seems to want the locator passed to the
processor as a structured array with multiple elements:

Thread: [xbiblio-devel] Test suite input format | XBib

How is the processor supposed to handle the array?

Frank

[Bruce_D_Arcus1]

I’m confused too, since I don’t know ATM why that variable is in the
schema (!). The point-locator attribute is intended to handle this use
case.

Does anyone have any better insight, or do we need to remove the
"locator" variable?

Bruce

[Rintze_Zelle]

FWIW, quite a few styles currently rely on the locator-variable (like
Chicago).

Rintze

[Bruce_D_Arcus1]

But what does it DO? Are these bugs?

[Rintze_Zelle]

gives the locator value as supplied by Zotero,
while gives the matching label. Also, I didn’t
search all styles, but I can’t recall ever seeing the point-locator
attribute being used.

Rintze

[Frank_Bennett]

gives the locator value as supplied by Zotero,
while gives the matching label. Also, I didn’t
search all styles, but I can’t recall ever seeing the point-locator
attribute being used.

bennett@bennett-laptop$ grep ‘point-locator[^a-z]’ *.csl
bennett@bennett-laptop$

Your memory serves you right. It’s not in there.

But to pull things back to the original question, I wasn’t asking
about the variable name, but the syntax for rendering it in CSL. We
currently use this:

That works if locator is a simple string variable. But in the thread
I linked, everyone is asking that it be an array – multiple
labelterm/value pairs. Don’t know how to render a data bundle like
that from the syntax above.

[Frank_Bennett]

gives the locator value as supplied by Zotero,
while gives the matching label. Also, I didn’t
search all styles, but I can’t recall ever seeing the point-locator
attribute being used.

bennett@bennett-laptop$ grep ‘point-locator[^a-z]’ *.csl
bennett@bennett-laptop$

Your memory serves you right. It’s not in there.

But to pull things back to the original question, I wasn’t asking
about the variable name, but the syntax for rendering it in CSL. We
currently use this:

That works if locator is a simple string variable. But in the thread
I linked, everyone is asking that it be an array – multiple
labelterm/value pairs. Don’t know how to render a data bundle like
that from the syntax above.

To be doubly clear, the issue is not the label, but the fact that it’s an array.

[Bruce_D_Arcus1]

That’s only part of the issue. What I’m saying is this is the wrong
variable, and we probably need to remove it.

See this thread:

<http://sourceforge.net/mailarchive/message.php?msg_id=47C6AA89.2020105%40gmail.com

[Frank_Bennett]

gives the locator value as supplied by Zotero,
while gives the matching label. Also, I didn’t
search all styles, but I can’t recall ever seeing the point-locator
attribute being used.

bennett@bennett-laptop$ grep ‘point-locator[^a-z]’ *.csl
bennett@bennett-laptop$

Your memory serves you right. It’s not in there.

But to pull things back to the original question, I wasn’t asking
about the variable name, but the syntax for rendering it in CSL. We
currently use this:

That works if locator is a simple string variable. But in the thread
I linked, everyone is asking that it be an array – multiple
labelterm/value pairs. Don’t know how to render a data bundle like
that from the syntax above.

To be doubly clear, the issue is not the label, but the fact that it’s an array.

That’s only part of the issue. What I’m saying is this is the wrong
variable, and we probably need to remove it.

See this thread:

http://sourceforge.net/mailarchive/message.php?msg_id=47C6AA89.2020105%40gmail.com

Read through the thread. It looks like at that stage the meaning of
“locator” and “point-locator” was in flux. Currently, “locator” is
effectively the name for a special variable consisting of exactly with
two elements: a label part associated with a locale term; and a string
supplied by the user. The first is called using the label element,
the second using the text element, as Rintze said earlier. If that
will change, I’ll need to know the structure of the data and the CSL
markup, and have an example or two of input and matching output. I’ll
work with whatever you decide.

No opinion on whether it’s necessary to replace locator with
point-locator in all existing styles.

[Bruce_D_Arcus1]

…

See this thread:

http://sourceforge.net/mailarchive/message.php?msg_id=47C6AA89.2020105%40gmail.com

Read through the thread. It looks like at that stage the meaning of
“locator” and “point-locator” was in flux. Currently, “locator” is
effectively the name for a special variable consisting of exactly with
two elements: a label part associated with a locale term; and a string
supplied by the user. The first is called using the label element,
the second using the text element, as Rintze said earlier. If that
will change, I’ll need to know the structure of the data and the CSL
markup, and have an example or two of input and matching output. I’ll
work with whatever you decide.

This is an ugly detail of CSL, and it’s not so much that it’s an
oversight, but that it’s just kind of hard to balance the concerns.

To understand some of the historical context of this wrinkle, you can
look back at an earlier version of the schema:

http://xbiblio.svn.sourceforge.net/viewvc/xbiblio/csl/schema/trunk/csl.rnc?logsort=cvs&revision=344&view=markup

At line 787, you’ll see we used to have a cs:locator element, which
had a bit of magic associated with it that avoided people having to
write really complicated stuff just to get the locators to print
correctly.

So the current variable was a product of an effort to simplify CSL
where possible. It essentially changed the variable element to an
attribute value.

With that out of the way, we need to clear up two details:

1. The more recent thread was just confusion about what “locator”
   referred to: the details of the source per se, or of its citation. We
   have two options.

A. remove “point-locator” and update the documentation to make clear
that “locator” is only for use in the citation, and refers to the
point citation details (not the source).

B. remove “locator” and update the existing CSL styles to use that

It seems to me option A is preferable.

2. processing of 1:

I think we have a few options:

A. we define the order of printing, so that a style author could just do:

<cs:text variable=“locator” delimiter=", "/>

B. we force the style author to define the ordering by having to list
the variables

<cs:text variable=“chapter page” delimiter=", "/>

If we choose B, then we don’t need 1 above at all (and we need to
update all the styles).

There’s an issue with my examples, though: they don’t include the
labels. I guess in that case we’d need to use a group?

Bruce

[Frank_Bennett]

…

See this thread:

http://sourceforge.net/mailarchive/message.php?msg_id=47C6AA89.2020105%40gmail.com

Read through the thread. It looks like at that stage the meaning of
“locator” and “point-locator” was in flux. Currently, “locator” is
effectively the name for a special variable consisting of exactly with
two elements: a label part associated with a locale term; and a string
supplied by the user. The first is called using the label element,
the second using the text element, as Rintze said earlier. If that
will change, I’ll need to know the structure of the data and the CSL
markup, and have an example or two of input and matching output. I’ll
work with whatever you decide.

This is an ugly detail of CSL, and it’s not so much that it’s an
oversight, but that it’s just kind of hard to balance the concerns.

To understand some of the historical context of this wrinkle, you can
look back at an earlier version of the schema:

http://xbiblio.svn.sourceforge.net/viewvc/xbiblio/csl/schema/trunk/csl.rnc?logsort=cvs&revision=344&view=markup

At line 787, you’ll see we used to have a cs:locator element, which
had a bit of magic associated with it that avoided people having to
write really complicated stuff just to get the locators to print
correctly.

So the current variable was a product of an effort to simplify CSL
where possible. It essentially changed the variable element to an
attribute value.

With that out of the way, we need to clear up two details:

1. The more recent thread was just confusion about what “locator”
   referred to: the details of the source per se, or of its citation. We
   have two options.

A. remove “point-locator” and update the documentation to make clear
that “locator” is only for use in the citation, and refers to the
point citation details (not the source).

B. remove “locator” and update the existing CSL styles to use that

It seems to me option A is preferable.

2. processing of 1:

I think we have a few options:

A. we define the order of printing, so that a style author could just do:

<cs:text variable=“locator” delimiter=", "/>

B. we force the style author to define the ordering by having to list
the variables

The hierarchy positions of “chapter”, “section”, “part” and “book”
aren’t fixed, are they? I can remember people expressing very strong
options about whether the smallest unit of a Japanese statute should
be translated as “section” or “article”, and whether a mid-level
division should be a “part” or a “section”.

I assumed that the pinpoint information would be fixed in the
application, passed as an array, and rendered in the order received.
Sort of like names work now, and with similar UI support on
application side.

[Bruce_D_Arcus1]

OK, I’m making an executive decision:

…

With that out of the way, we need to clear up two details:

1. The more recent thread was just confusion about what “locator”
   referred to: the details of the source per se, or of its citation. We
   have two options.

A. remove “point-locator” and update the documentation to make clear
that “locator” is only for use in the citation, and refers to the
point citation details (not the source).

B. remove “locator” and update the existing CSL styles to use that

It seems to me option A is preferable.

We’re going with Option A.

2. processing of 1:

I think we have a few options:

A. we define the order of printing, so that a style author could just do:

<cs:text variable=“locator” delimiter=", "/>

B. we force the style author to define the ordering by having to list
the variables

<cs:text variable=“chapter page” delimiter=", "/>

If we choose B, then we don’t need 1 above at all (and we need to
update all the styles).

There’s an issue with my examples, though: they don’t include the
labels. I guess in that case we’d need to use a group?

We’re going with Option A.

In other words, there will be no changes in CSL for this, except that
we will remove the “point-locator” variable, and change the
documentation for “locator” to make it clear that, unlike all (?)
other simple variables, this one can return multiple values.

For 0.9, I’m leaving it to implementers to figure out, or suggest,
ordering of multiple locators. I do not believe we should expect the
client to send an ordered array, though.

The reality is that multiple locators will be important for some
people, but fairly rare.

Bruce

[Frank_Bennett]

A. we define the order of printing, so that a style author could just do:

<cs:text variable=“locator” delimiter=", "/>

B. we force the style author to define the ordering by having to list
the variables

<cs:text variable=“chapter page” delimiter=", "/>

If we choose B, then we don’t need 1 above at all (and we need to
update all the styles).

There’s an issue with my examples, though: they don’t include the
labels. I guess in that case we’d need to use a group?

We’re going with Option A.

So a group should implicitly iterate, if and only if it contains a
text element that has “locator” as its variable attribute. The value
to be iterated is the locator variable, and the iteration will
encompass all elements contained within the group.

The group provides the delimiter between elements contained in the
group (text and label), but the child text element bearing the locator
variable provides the delimiter that joins the iterated sets.

It’s probably worth taking a week or two to think this one over; I
don’t think I can code it to work reliably. Here’s a fairly common
snip from one style in the repository:

.... ........ ........ .... ....

Applying the rules above, this would iterate the entire citation when
a multiple locator is provided by the user, joined by an empty string:

Doe 2003, 10Doe 2003, 15Doe 2003, 20-25

It’s not obvious how to prevent that from happening.

[Bruce_D_Arcus1]

…

We’re going with Option A.

So a group should implicitly iterate, if and only if it contains a
text element that has “locator” as its variable attribute. The value
to be iterated is the locator variable, and the iteration will
encompass all elements contained within the group.

The group provides the delimiter between elements contained in the
group (text and label), but the child text element bearing the locator
variable provides the delimiter that joins the iterated sets.

It’s probably worth taking a week or two to think this one over; I
don’t think I can code it to work reliably. Here’s a fairly common
snip from one style in the repository:

.... ........ ........ .... ....

Applying the rules above, this would iterate the entire citation when
a multiple locator is provided by the user, joined by an empty string:

Doe 2003, 10Doe 2003, 15Doe 2003, 20-25

It’s not obvious how to prevent that from happening.

When I mentioned the group, I was referring to labels specifically; an
example like this:

I’m fine on waiting on implementing this. I agree it’s not ideal
(though don’t ATM see an option that is).

Bruce

[Frank_Bennett]

…

We’re going with Option A.

So a group should implicitly iterate, if and only if it contains a
text element that has “locator” as its variable attribute. The value
to be iterated is the locator variable, and the iteration will
encompass all elements contained within the group.

The group provides the delimiter between elements contained in the
group (text and label), but the child text element bearing the locator
variable provides the delimiter that joins the iterated sets.

It’s probably worth taking a week or two to think this one over; I
don’t think I can code it to work reliably. Here’s a fairly common
snip from one style in the repository:

.... ........ ........ .... ....

Applying the rules above, this would iterate the entire citation when
a multiple locator is provided by the user, joined by an empty string:

Doe 2003, 10Doe 2003, 15Doe 2003, 20-25

It’s not obvious how to prevent that from happening.

When I mentioned the group, I was referring to labels specifically; an
example like this:

I’m fine on waiting on implementing this. I agree it’s not ideal
(though don’t ATM see an option that is).

Here is the only request for this use case that I was able to find in
a search of the Z forums:

Book, Chapter, Page

It might be worth putting up a (true) request for comments sometime,
and bump it a few times to give it some exposure, before finalizing.

[Bruce_D_Arcus1]

I’d like to go back to the beginning, since I kind of lost this proposal …

The current syntax for a locator looks something like this:

This supports only a single label and a page number (I think as a dumb
string, at present). This proposal would provide for multiple
elements in a pinpoint locator. Enhanced syntax for rendering a
locator would be as follows:

The delimiter attribute on the numeral is used to join range elements.
If an implicit test for is-numeric raises false, the locator variable
is rendered as at present (as a single plain string preceded, in the
example above, by the primary locator label).

So what you’re suggesting here is to change the current cs:number definition …

cs-number =
element cs:number {
formatting,
attribute variable { “edition” | “volume” | “issue” | “number” |
“number-of-volumes” },
attribute form { “numeric” | “ordinal” | “roman” | “long-ordinal” }?
}

… to a) add a sub-node that specifies the data per se, and b)
include cs:label as an option, and c) add “locator” to the variable
list.

Is that right?

This might indeed be a better approach, but we’d need to distinguish
the locators specific to the source, from those that are point
locators. We’d also want to allow all locator variables on cs:number.

Bruce

[Frank_Bennett]

I’d like to go back to the beginning, since I kind of lost this proposal …

The current syntax for a locator looks something like this:

This supports only a single label and a page number (I think as a dumb
string, at present). This proposal would provide for multiple
elements in a pinpoint locator. Enhanced syntax for rendering a
locator would be as follows:

The delimiter attribute on the numeral is used to join range elements.
If an implicit test for is-numeric raises false, the locator variable
is rendered as at present (as a single plain string preceded, in the
example above, by the primary locator label).

So what you’re suggesting here is to change the current cs:number definition …

cs-number =
element cs:number {
formatting,
attribute variable { “edition” | “volume” | “issue” | “number” |
“number-of-volumes” },
attribute form { “numeric” | “ordinal” | “roman” | “long-ordinal” }?
}

… to a) add a sub-node that specifies the data per se, and b)
include cs:label as an option, and c) add “locator” to the variable
list.

Is that right?

This might indeed be a better approach, but we’d need to distinguish
the locators specific to the source, from those that are point
locators. We’d also want to allow all locator variables on cs:number.

That was the idea. There is a wrinkle I didn’t think of, though, unfortunately.

Special numeric forms (as roman, or roman uppercase) may be
source-specific, so they can’t be fixed in the style. If the data is
received as an integer, the form and decoration parameters (roman,
uppercase) would need to be supplied by the application along with the
label. That would need support in the UI, and it seems like it would
make adding citations to a document more complicated and
time-consuming for users.

Maybe it’s up to application side to decide whether they really need
this to support their user community.