Two usability patches for ZS 1.5
Frank Bennett
covers a specific functionality, and I would like to request their
consideration for inclusion.
00-push-item-on-multiple-sources-switch.patch
This was prompted by a user suggestion that seemed sensible to me;
in the WP client, initialize the multiples box with the currently
selected item when Multiple Selections is pressed. This is the
intuitive action, and the patch is not complex (he said).
01-allow-duplicate-entries-in-multiple.patch
This one is actually quite important for law. Legal writing
requires precise pinpointing of each assertion made in the text, and
of fresh assertions made in footnotes. It is common for the same
source to be cited more than once in a single footnote, with different
pinpoint page numbers. This patch enables that behaviour. Each
instance of a source holds separate pinpoints. Items can be safely
deleted from the multiples box without losing or confusing the
pinpoint assignments.
Many thanks.
Frank Bennett
Bruce D'Arcus
On Wed, Jan 14, 2009 at 10:44 AM, Frank Bennett <bierc...@gmail.com> wrote:
> ... It is common for the same
> source to be cited more than once in a single footnote, with different
> pinpoint page numbers. This patch enables that behaviour. Each
> instance of a source holds separate pinpoints. Items can be safely
> deleted from the multiples box without losing or confusing the
> pinpoint assignments.
But how is this done? I typically use author-date styles, for example.
Are we talking about ...
Blah, blah, blah (Doe, 1999: 22, 55)
...? Or ...
Blah (Doe, 1999: 22), blah, blah (Doe, 1999: 55)
...?
WRT to footnote style, the idea has always been to distinguish too
different kinds of citations: citations within notes, and footnoted
citations. The first is typically going to include other commentary,
and indeed one would footnote this content in any kind of style.
Bruce
Frank Bennett
> > ... It is common for the same
> > source to be cited more than once in a single footnote, with different
> > pinpoint page numbers. This patch enables that behaviour. Each
> > instance of a source holds separate pinpoints. Items can be safely
> > deleted from the multiples box without losing or confusing the
> > pinpoint assignments.
>
> But how is this done? I typically use author-date styles, for example.
> Are we talking about ...
>
> Blah, blah, blah (Doe, 1999: 22, 55)
>
> ...? Or ...
>
> Blah (Doe, 1999: 22), blah, blah (Doe, 1999: 55)
>
> ...?
first example, with a style that puts the reference in a footnote
instead of the text. The structure is the same, only the form
changes. If the Blah, blah, blah is bound to the footnote (as a
Zotero prefix) then it goes to the footnote too. At least that's how
I understand things.
> WRT to footnote style, the idea has always been to distinguish too
> different kinds of citations: citations within notes, and footnoted
> citations. The first is typically going to include other commentary,
> and indeed one would footnote this content in any kind of style.
precisely to preserve unity between "citation" (i.e. in the sense used
in the Zotero source, as a grouped cluster of cites in a single
container or note) and "note" or "footnote". It certainly would make
for cleaner architecture to follow that route, because Zotero's CSL
processor doesn't need to know anything about the surrounding
environment to determine whether a subsequent citation is in the same
note, or a subsequent one. (Bluebook requires different formatting
for a supra reference inside the same note, so it's important.)
I just did a trial on a sample document under 1.0 and Open Office,
placing several separate references to the same and different sources
there. Interestingly, with each refresh of the citations, I get a
different combination (a different *sequence*) of id and supra. On
one iteration, *both* instances of a citation come out as ibid. Some
weird interaction between the client and Zotero when the physical
reference is contained in the footnote, I guess. Which kind of
demonstrates the point.
To recap, I have been assuming that a footnote containing a mixture of
references and commentary should be built using the multiple
references function in the client, inserting commentary text through
the prefix and suffix fields. If that's wrong, it looks like there
are some bugs to be worked on. In any case, though, I don't like the
feel of editing cites directly in the footnote; in Open Office, at
least, it's not obvious how to get the cursor outside of the scope of
the field (and not obvious to the new user that their text will be
lost if they type it inside the field). But that's more an
implementation issue.
Bruce D'Arcus
> I thought that the prefix and suffix fields were in the Z clients
> precisely to preserve unity between "citation" (i.e. in the sense used
> in the Zotero source, as a grouped cluster of cites in a single
> container or note) and "note" or "footnote". It certainly would make
> for cleaner architecture to follow that route, because Zotero's CSL
> processor doesn't need to know anything about the surrounding
> environment to determine whether a subsequent citation is in the same
> note, or a subsequent one. (Bluebook requires different formatting
> for a supra reference inside the same note, so it's important.)
>
> I just did a trial on a sample document under 1.0 and Open Office,
> placing several separate references to the same and different sources
> there. Interestingly, with each refresh of the citations, I get a
> different combination (a different *sequence*) of id and supra. On
> one iteration, *both* instances of a citation come out as ibid. Some
> weird interaction between the client and Zotero when the physical
> reference is contained in the footnote, I guess. Which kind of
> demonstrates the point.
>
> To recap, I have been assuming that a footnote containing a mixture of
> references and commentary should be built using the multiple
> references function in the client, inserting commentary text through
> the prefix and suffix fields.
That's not exactly how I view it.
My assumption has always been that one design goal of CSL is to enable
more-or-less seamless switching between note-based styles and in-text
styles. I think doing that requires recognizing a different between
micro-commentary related directly to a citation (see Doe, 1999,
especially Chapter 3) and more extensive commentary that gets cited.
Just thought it might be good to keep this in mind.
> If that's wrong, it looks like there are some bugs to be worked on.
Not surprising.
> In any case, though, I don't like the
> feel of editing cites directly in the footnote; in Open Office, at
> least, it's not obvious how to get the cursor outside of the scope of
> the field (and not obvious to the new user that their text will be
> lost if they type it inside the field). But that's more an
> implementation issue.
Yes, and would be nice if it could be fixed.
Bruce
Frank Bennett
think the simplest way to get there is to treat what we might call a
unit of reference (everything that should go into a footnote when a
footnote style is selected) as a single entity. CSL already has this
concept built into it implicitly, in the rules for setting "ibid" and
"subsequent" (if the immediately preceding reference is to the same
source, but it is in the preceding note, and the preceding note
contains multiple references, the latter must be raised). CSL needs
to know about note containers; and if micro-commentary is kept in the
prefix and suffix fields, this already works correctly. I really
don't see the need for added complexity. Deriving note position from
the word processor environment for non-Zotero-generated footnotes
sounds like a real maintenance headache for the plugin developers.
This problem of reading note position from the word processor
environment has come up before, in the context of back-reference note
specifiers needed for robust Bluebook implementation:
http://sourceforge.net/mailarchive/forum.php?thread_name=47E8657E.1020202%40gmail.com&forum_name=xbiblio-devel
You can kill two birds with one stone on this by reworking the user
interface to the prefix and suffix fields, so that they are editable
in place, and treating *all* footnotes as Zotero references. The
Zotero/CLS "citation" sequence would then correspond with note
sequence where it matters (i.e. in all-footnote styles like Bluebook),
and the issue linked above goes away.
In this design, references would appear in the word processor view
with icons showing the start and finish of prefix and suffix zones.
In the "Add citation" menu supplied by Zotero, these fields would no
longer appear, but the user would be given a "Force to footnote"
option, which would place the unit of reference into a footnote in all
styles.
> > If that's wrong, it looks like there are some bugs to be worked on.
>
> Not surprising.
Frank Bennett
[snip]
> Not surprising.
[snip]
There are two approaches on the table:
(1) No changes are necessary; multiple citations can be added inside a
footnote, with connecting text outside of Zotero reference marks (see
uploaded pretty-printed file notes-two-single.xml)
(2) Footnotes with multiple references should always be constructed as
a single citation (unit of reference), with connecting text provided
through the prefix and suffix fields (see uploaded pretty-printed file
notes-multiple.xml).
Here are some facts:
-- Legal writing requires multiple references to the same source
within a single footnote.
-- Zotero currently blocks multiple references within a single unit of
reference, so the only way to get two references to the same source
into a footnote is to use approach (1).
-- Position evaluation with approach (1) is currently broken, so it is
unusable.
-- If approach (1) is adopted, there will be two possible methods of
creating a footnote containing multiple references: by creating a
multiple reference in Zotero, and letting the style generate the
footnote; or creating a footnote, and inserting Zotero references into
it. The two have the same appearance on the page, but require
different operations to edit them. One has a significant limitation (a
duplicate reference cannot be added to the generated footnote), and
walking a footnote of one type to the other requires the user to
perform complicated cut-and-paste work.
Approach (1) strikes me as complicated to maintain (and it is already
broken), awkward to use, and difficult to explain. Approach (2)
strikes me as simple to maintain (the positioning issues are all
solved by a patch upload to zotero-dev as 02-positioning.patch), easy
to use, and easy to explain.
Because some of the support burden for this is going to fall on my
desk, I would prefer a commitment to approach (2) because of its
simplicity (I will spend less time explaining to students why you can
do this, but you can't do that, you should have done this other thing
instead).
I want to keep things simple, but if there is a solution, I'm good.
So which is it going to be? This issue isn't going to go away for us;
there should either be a ticket for fixing the existing breakage in
position evaluation, or an agreement that opening duplicate references
in a single "citation" (covered by my 01 and 02 patches) is desirable.
Frank Bennett
today, but was able to spend some time ploughing through the 1.0
sources. What I discovered was that the Open Office client in 1.0, at
least, was completely broken with respect to footnotes. The memory
map in the client did not track the order of citations in the
document, with the result that back-references worked only if the
references were added top to bottom and no insertions were made
afterward.
In the 1.5 client this has been fixed, but I also discovered (as Dan
had mentioned to me several days ago -- although I failed to grasp the
significance of what he said at the time) that only one unit of
reference can be inserted into a footnote. In other words, Zotero has
already adopted approach (2), as described in my last message. In
Open Office, at least, the use of approach (1), which is what I am
guessing Bruce had in mind (inserting several separate Zotero
references into a commentary footnote separately created by the user),
has been blocked in software.
Hope that's all clear now.
Frank Bennett
Bruce D'Arcus
> In the 1.5 client this has been fixed, but I also discovered (as Dan
> had mentioned to me several days ago -- although I failed to grasp the
> significance of what he said at the time) that only one unit of
> reference can be inserted into a footnote.
Um, if this is the case (and testing right now for the first time
using 1.5 and the beta OOo 3.0 plug-in seems to suggest it may be),
then I consider this a bug. I really hope this is just an oversight,
rather than a deliberate choice.
As I mentioned previously, I always had in mind that a core
requirement of styling around CSL (though this is really independent
of CSL) is that one must be able to switch between note and in-text
styles without modifying the source. That was previously possible, but
would not be under this situation. Moreover, and even worse, it would
needlessly constrain how people cite.
Practical example: I am in a field (human geography) that generally
uses author-date citations. On the more humanities send of the
discipline, there are journals (and some book authors) that use note
styles.
So theoretically, I may actually need to be able to switch between
note and author-date styles. But really practically, I almost always
use author-date styles, and there are times when I need to put two
citation fields in my footnotes!
> In other words, Zotero has
> already adopted approach (2), as described in my last message. In
> Open Office, at least, the use of approach (1), which is what I am
> guessing Bruce had in mind (inserting several separate Zotero
> references into a commentary footnote separately created by the user),
> has been blocked in software.
Which is a really, really, bad idea! I'll be submitting a bug report on this.:-)
Bruce
Bruce D'Arcus
> Which is a really, really, bad idea! I'll be submitting a bug report on this.:-)
https://www.zotero.org/trac/ticket/1298
I also found a problem with data loss, so a definitive bug.
Bruce
Frank Bennett
happen in order to realize your design goal. Zotero can manage both
types of references your describe -- and it should do, in order to
keep the design simple and clean. All that is needed is an option to
force a reference unit into a footnote, no matter what the style.
From there, you can use the prefix and suffix areas to fashion the
full text of the note.
Currently, the prefix and suffix fields are awkward little plain text
things, and that is constraining. But they could equally well be Open
Office XML spans, open to direct editing by the word process (but
within the scope of Zotero's reference markers, so that they could be
managed easily by the plugin client.
As I tried to explain in the earlier messages, permitting users to
create multiple single references inside footnotes introduces
unnecessary complexity. The CSL processor would need to be able to
determine that it was running inside a footnote, by querying the word
processor environment itself -- and that would be required for lots of
stuff, from note numbers to surrounding punctuation marks. All that
custom coding for individual platforms would soak up developer time
and slow down progress. With the current choice, things can proceed
more quickly, and the system will be more stable in the hands of users
as it matures.
I'll second you on the need for easy editing of multiple footnotes,
preferably in-place. But I don't think there's anything to be alarmed
about. On the contrary.
Frank Bennett
little off the path here. I'd be interested in learning Simon's view,
but as I say, if it's working, I'm good.)
Frank Bennett
for my request for permitting repeat references to the same source in
a single unit of reference. Here's a Bluebook example:
(1) Robert M. Cover, Justice Accused 19 (1975).
(2) Id. Cover goes on to discuss this concept in more detail. Id.
at 22-30.
(Example from Rule 15.8.1)
Bluebook has two modes, one for references in footnotes (in law review
articles), one for references in text (in memoranda). The references
above should be run into the main text in the memorandum style, and
appear in footnotes in the law review style. If two references to the
Robert Cover source are permitted in a single unit of reference, this
works. Current behaviour forces rewriting of the document.
In _my_ writing, this is an important issue. I don't see how it
conflicts with other styles. I would be grateful if it could be
considered.
Bruce D'Arcus
...
> I think you're missing the point. This is exactly what needs to
> happen in order to realize your design goal. Zotero can manage both
> types of references your describe -- and it should do, in order to
> keep the design simple and clean. All that is needed is an option to
> force a reference unit into a footnote, no matter what the style.
> From there, you can use the prefix and suffix areas to fashion the
> full text of the note.
I may still be "missing the point," since this bit at the end isn't
making any sense to me :-).
> Currently, the prefix and suffix fields are awkward little plain text
> things, and that is constraining. But they could equally well be Open
> Office XML spans, open to direct editing by the word process (but
> within the scope of Zotero's reference markers, so that they could be
> managed easily by the plugin client.
They could, but it does add complexity all around: to the document
encoding, and to the Zotero and/or WP UI.
> As I tried to explain in the earlier messages, permitting users to
> create multiple single references inside footnotes introduces
> unnecessary complexity.
And not permitting it appears to me ATM as an arbitrary restriction ;-)
> The CSL processor would need to be able to
> determine that it was running inside a footnote, by querying the word
> processor environment itself -- and that would be required for lots of
> stuff, from note numbers to surrounding punctuation marks. All that
> custom coding for individual platforms would soak up developer time
> and slow down progress. With the current choice, things can proceed
> more quickly, and the system will be more stable in the hands of users
> as it matures.
It just may be that I'm not able to find the time to figure this all
out, but I'm still not following this.
> I'll second you on the need for easy editing of multiple footnotes,
> preferably in-place. But I don't think there's anything to be alarmed
> about. On the contrary
I'm "alarmed" if we (you, me, Simon, etc.) aren't on the same page
about what we're trying to achieve, and what the requirements ought to
be.
We went through similar confusion in the first version of the plug-in,
and it seems one upshot was that it got rewritten (though I don't know
how much Simon actually changed the basic structure of the approach,
other than that he ported it to Python).
Bruce
Bruce D'Arcus
...
> Returning to the original topic of this thread, there _is_ a reason
> for my request for permitting repeat references to the same source in
> a single unit of reference. Here's a Bluebook example:
>
> (1) Robert M. Cover, Justice Accused 19 (1975).
>
> (2) Id. Cover goes on to discuss this concept in more detail. Id.
> at 22-30.
>
> (Example from Rule 15.8.1)
>
> Bluebook has two modes, one for references in footnotes (in law review
> articles), one for references in text (in memoranda). The references
> above should be run into the main text in the memorandum style, and
> appear in footnotes in the law review style. If two references to the
> Robert Cover source are permitted in a single unit of reference, this
> works. Current behaviour forces rewriting of the document.
>
> In _my_ writing, this is an important issue. I don't see how it
> conflicts with other styles. I would be grateful if it could be
> considered.
So for clarity, you are referring to your "(2)" example above as the
"two references ... in a single unit of reference"; right?
Which version of BB are you working with? I have the 18th edition, but
don't see 15.8.1.
Bruce
Frank Bennett
> On Sat, Jan 17, 2009 at 10:23 AM, Frank Bennett <biercena...@gmail.com> wrote:
...
> > full text of the note.
>
> I may still be "missing the point," since this bit at the end isn't
> making any sense to me :-).
> > Currently, the prefix and suffix fields are awkward little plain text
> > things, and that is constraining. But they could equally well be Open
> > Office XML spans, open to direct editing by the word process (but
> > within the scope of Zotero's reference markers, so that they could be
> > managed easily by the plugin client.
>
> They could, but it does add complexity all around: to the document
> encoding, and to the Zotero and/or WP UI.
simpler to have a single object "reference blob", of which
"footnoteness" is an attribute than it is to have "reference blobs"
and "footnote blobs", each of which can contain or be contained by the
other. You're thinking that the footnote has to be created by the
"footnote" item in the WP menu bar. It could equally well be created
by pressing a "force footnote" button in Zotero. In a footnote style,
creating all footnotes in this way would get you to automatic
insertion of note numbers in one go -- Zotero doesn't need any
additional information from the document, because it has all of the
notes in its own registers. And that's simple.
> > As I tried to explain in the earlier messages, permitting users to
> > create multiple single references inside footnotes introduces
> > unnecessary complexity.
>
> And not permitting it appears to me ATM as an arbitrary restriction ;-)
> > The CSL processor would need to be able to
> > determine that it was running inside a footnote, by querying the word
> > processor environment itself -- and that would be required for lots of
> > stuff, from note numbers to surrounding punctuation marks. All that
> > custom coding for individual platforms would soak up developer time
> > and slow down progress. With the current choice, things can proceed
> > more quickly, and the system will be more stable in the hands of users
> > as it matures.
>
> It just may be that I'm not able to find the time to figure this all
> out, but I'm still not following this.
> > I'll second you on the need for easy editing of multiple footnotes,
> > preferably in-place. But I don't think there's anything to be alarmed
> > about. On the contrary
>
> I'm "alarmed" if we (you, me, Simon, etc.) aren't on the same page
> about what we're trying to achieve, and what the requirements ought to
> be.
>
> We went through similar confusion in the first version of the plug-in,
> and it seems one upshot was that it got rewritten (though I don't know
> how much Simon actually changed the basic structure of the approach,
> other than that he ported it to Python).
it's just more stable). All things with time.
Thanks for listening, I know you're busy. I'm about to settle the
last couple of details for the internal version that we'll deploy to
students in April (and that I'll use for my next article). I'll grow
quieter soon.
Frank