Dan,On Mon, Nov 2, 2009 at 12:11 AM, Dan Stillman <@Dan_Stillman> wrote:
I (and I think Rick) have suggested this in the past, but rather than
having users search for macros manually, it might be possible to simply
have the user format a standard reference as it would appear in their
desired style …
Exactly how would you expect this to work from the user perspective?
What would they see, and how would they interact with it?
Bruce
The only input that users would have would be a reference type menu and
a WYSIWYG text editor (e.g., TinyMCE) with basic formatting options.
After selecting a type, they’d be presented with a table of metadata for
a sample reference of that type. (There might need to be multiple
entries for a given type to account for some conditionals.) They would
type out�or drag-and-drop from the metadata table�a citation and a
bibliography entry for that sample reference as appropriate for their
desired style, and then they’d apply any relevant formatting. They’d
repeat this for any types that differed (though the menu could also
offer the generic fallback types as options). When done, they’d click
Next, some magic would happen, and the tool would return A) a link to an
existing style that matched exactly, B) a link to one or more existing
styles that came close, or, perhaps, C) a custom-generated style that
was an amalgam of macros fitted to match (or closely match) the input.
While the tool would rely primarily on prewritten macros, it might be
able to make certain straightforward alterations to the macros itself.
Others would just require small tweaks to the style that it returned.
So, basically, this would function as both a search tool and a style editor.
Sorry, I still didn’t manage to have a look at Fred’s prototype - Carles
sent me the XPI, but the install fails on Firefox 3.5.4. I’ll have to look
on Carles’ machine.
But if I understand Dan correctly, we’re basically proposing the same thing,
no? In my mock-up, you would also select a type first, and the “unused
fields” section is the “table of metadata” for a sample reference of that
type (which is also shown in the preview field below). In my wireframe, they
couldn’t type out the citation, but drag-and-drop it as Dan proposes, and
then apply the relevant formatting. Then they’d repeat this for any types
that differed, but could use types defined earlier as “templates” to avoid
repition. Then the same magic bit that Dan described - done.
Best,
Victor
I’d still rather have the wizard pre-assemble the default, generic,
layout, with users only worrying about types if that doesn’t work.
The key in any case for it to be easy for users to visualize the
impacts of particular configurations. Maybe by default the preview
pane has 5-10 of the most common types for a particular field (biology
would be different than history, for example), and then that would be
filtered down to the specific type needed if people were modifying
that.
Bruce
I don’t think we’re really proposing the same thing. The UIs have some
similarities, but that’d be true with most WYSIWYG approaches.
The “magic bit” is not incidental�the main point of my proposal is the
mechanism it uses to find/assemble the style based on existing macros.
The resulting styles would be almost entirely macro-based, and the tool
would also point you to existing high-quality, canonical styles when
they existed. The user interface would also be as simple as it could
be�you would just enter the desired output string as you would, say, in
a forum request for the style. (To be clear, my proposal has no
tokens�if it supported dragging from the metadata table, doing so would
just be equivalent to typing the same string into the input field.)
As far as I can tell, your proposal doesn’t cover implementation at all,
though it implies that a style is being built up incrementally based on
formatting of the various tokens. This leaves open the question of what
the resulting styles would look like, whether they’d be based on macros,
how easy they would be to maintain, etc., which seem like the main
points of contention, all of which I’m suggesting we might be able to avoid.
I don’t think we’re really proposing the same thing. The UIs have some
similarities, but that’d be true with most WYSIWYG approaches.
Well, if our UI ideas have similarities, that’s a good start, isn’t it? I
think there’s a thousand different ways you could do the UI - if you look at
the WYSIWYG approach of EndNote or Citavi, they’re both very different both
from each other as well as your/my proposal.
(To be clear, my proposal has no tokens—if it supported dragging from the
metadata table, doing so would just be equivalent to typing the same string
into the input field.)
But how would you then allow for formatting each string? In my proposal, the
“tokens” are just a visual metaphor to make it clear that you can add or
re-arrange the strings using drag and drop.
As far as I can tell, your proposal doesn’t cover implementation at all,
though it implies that a style is being built up incrementally based on
formatting of the various tokens.
Yes, as I’ve said earlier, my only concern is about getting to a consensus
about UI, not implementation - which I wouldn’t understand anyway. That’s
probably why I don’t see how arranging strings via drag and drop (or typing)
would imply a different approach than the same string with a border drawn
around them (=“token”)?
(To be clear, my proposal has no tokens�if it supported dragging from the metadata table, doing so would just be equivalent to typing the same string into the input field.)But how would you then allow for formatting each string?
In my proposal, the tool doesn’t format each string. See below.
As far as I can tell, your proposal doesn't cover implementation at all, though it implies that a style is being built up incrementally based on formatting of the various tokens.Yes, as I’ve said earlier, my only concern is about getting to a
consensus about UI, not implementation - which I wouldn’t understand
anyway. That’s probably why I don’t see how arranging strings via drag
and drop (or typing) would imply a different approach than the same
string with a border drawn around them (=“token”)?
In your approach, the tool has to know how to format those individual
tokens, which requires fairly extensive knowledge of CSL to be coded in:
for each available formatting option that’s provided to the user, the
tool has to know how to translate it into actual CSL XML.
In my approach, the tool doesn’t (have to) know anything about CSL. All
the user is producing is a few HTML strings. The tool would then search
through a large and growing library of HTML strings pregenerated with
citeproc�both complete output from existing styles as well as the output
of individual macros, all for the same sample references supplied to the
user�and find a match. While this wouldn’t be trivial, it strikes me as
a considerably more fun�and, I suspect, considerably easier�programming
project than trying to build a tool that actually generates CSL XML
(which would also have to be updated whenever CSL was changed). And the
output would be entirely macro-based, which would be in line with
Bruce’s vision as well as Frank’s suggestion the other day that we rely
on a library of prewritten macros.
The tool I’m proposing still might know how to make a few
straightforward modifications to macros (say, if the only difference
between an existing style and the user’s preferred style was that this
one macro was italicized, and there didn’t happen to be an italicized
version of the macro in the library), but that’d be icing on the cake.
I don’t think we’re really proposing the same thing. The UIs have some
similarities, but that’d be true with most WYSIWYG approaches.Well, if our UI ideas have similarities, that’s a good start, isn’t it? I
think there’s a thousand different ways you could do the UI - if you look at
the WYSIWYG approach of EndNote or Citavi, they’re both very different both
from each other as well as your/my proposal.(To be clear, my proposal has no tokens—if it supported dragging from the
metadata table, doing so would just be equivalent to typing the same string
into the input field.)But how would you then allow for formatting each string? …
You might not want to provide on-screen controls to cover every
attribute, at least in the short term. It seems like that might make
it much harder to control style behavior that way than just directly
editing the CSL code. [Dan just made a similar point in response
while I was writing this]
But formatting wouldn’t need to be controlled by explicit CSL
attribute toggles. It might be more intuitive to allow some types of
formatting to be controlled by manipulating sample input and output
(by adding or deleting prepackaged names to the input side, for
example, or by manipulating “tokenized” name sub-elements on the
output). This would save you from the task of inventing screen icons
for such items as et-al-subsequent-use-first,
after-collapse-delimiter, and disambiguate-add-givenname.
Another thing to think about would be the possibility of dragging
formatting between macros. If the user finds a couple of macros, each
of which provides part of the desired effect, she might drag in one
set of parameters from one macro (variable field + text mangling, say)
and the visual formatting from the other (italics, say). Most of the
user’s actual work at the interface would involve searching and
scanning for cites and cite fragments that “look right”, and
facilities would be provided to get them from the appearance of things
to program code with a minimum of steps. (You could think of it as
kind of an Adobe Illustrator ™ approach to citation style design,
as contrasted with the LaTeX picture environment.)
Frank
… In my proposal, the
“tokens” are just a visual metaphor to make it clear that you can add or
re-arrange the strings using drag and drop.As far as I can tell, your proposal doesn’t cover implementation at all,
though it implies that a style is being built up incrementally based on
formatting of the various tokens.Yes, as I’ve said earlier, my only concern is about getting to a consensus
about UI, not implementation - which I wouldn’t understand anyway. That’s
probably why I don’t see how arranging strings via drag and drop (or typing)
would imply a different approach than the same string with a border drawn
around them (=“token”)?
The strings Dan refers to are not variable names (or proxies for
variable names), but
…
In my approach, the tool doesn’t (have to) know anything about CSL. All
the user is producing is a few HTML strings. The tool would then search
through a large and growing library of HTML strings pregenerated with
citeproc—both complete output from existing styles as well as the output
of individual macros, all for the same sample references supplied to the
user—and find a match. While this wouldn’t be trivial, it strikes me as
a considerably more fun—and, I suspect, considerably easier—programming
project than trying to build a tool that actually generates CSL XML
(which would also have to be updated whenever CSL was changed). And the
output would be entirely macro-based, which would be in line with
Bruce’s vision as well as Frank’s suggestion the other day that we rely
on a library of prewritten macros.
So in terms of what’s going on internally, your approach would be the
same as what I have suggested: you take a list of macro calls and
transform that into the CSL XML*. It’s just that you suggest a
different approach to getting that list of macro calls. E.g. the only
real difference is the UI.
Right?
Bruce
Hi all,
*(Dan:) *In my approach, the tool doesn’t (have to) know anything about CSL.
All
the user is producing is a few HTML strings. The tool would then search
through a large and growing library of HTML strings pregenerated with
citeproc—both complete output from existing styles as well as the output
of individual macros, all for the same sample references supplied to the
user—and find a match.
Wouldn’t the same be possible in my UI approach? The UI and “token”
formatting only produce HTML strings, which are then matched against an
existing library of HTML strings - just as you propose. If what a users has
created is identical to an existing style, the user could be offered to have
his style turned into a “dependent style” as described in my spec.
*(Bruce:) *So in terms of what’s going on internally, your approach would be
the
same as what I have suggested: you take a list of macro calls and
transform that into the CSL XML*. It’s just that you suggest a
different approach to getting that list of macro calls. E.g. the only
real difference is the UI.Right?
As explained above, I believe my proposal would also be compatible with this
approach. Am I wrong?
I’ve now managed to have a look at Fred’s prototype and played around with
it. I do feel there are many similarities in the underlying philosophy/UX
scenario - e.g. using pre-populated dropdowns with concrete examples of
formatting permutations. The main difference seems to be the user flow:
For me personally, the result of Fred’s approach was that I had difficulty
figuring out what to do at each step, and which field I was currently
editing (I asked myself “does what I’m doing now in the In-Text tab affect
all document types, or just the one I have currently active in the Field
Order tab?”). I feel that Fred’s UI emphasizes the controls over the
WYSIWYG/Preview part:
Going through the screenshots of Fred’s prototype I’ll try to point out
similarities and differences to my UI spec (
http://bitbucket.org/bdarcus/makecsl/wiki/UIProposal).
Screenshot 1 - Tab “Style Info”: This would roughly relate to the section
“Creating/Naming Styles” in my spec. I’ve left out some of the style creator
information, whereas Fred’s prototype is lacking the option to set
“dependent styles”.
[image:
?ui=2&view=att&th=124bf0a744b46390&attid=0.1&disp=attd&realattid=ii_124bf0a744b46390&zw]
Screenshot 2-4 - Tabs “In-text citations”, “Footnotes/Endnotes”,
“Bibliography”: Either one of the first two tabs is only visible depending
on the choice of “in-text vs. note” radio button in the “Style Info” tab. It
took me a while to figure this out. In both tabs, there are a number of
string formatting options - very similar to the string (=“token”) formatting
options in my spec. For example, Fred’s Author Name Options and Author
Delimiter options are virtually identical to my proposal - except for the
crucial difference that in my UI they would only be shown when an Author
string is currently being edited.
My UI, however, is missing the option to choose between in-text versus
footnote/endnote citations. I believe this would better be solved by a
simple tickbox like “Insert in-text citations as footnotes” rather than
having two completely separate tabs. My UI is also missing a couple of
formating options which I simply forgot, but which Fred included, e.g. roles
for “Subsequent citations”.
The most important difference, however, is where the definition of the field
order is done. My UI includes the definition of the field order and text
formatting right in the “In-text Citation” tab, where it doubles as a
WYSIWYG/Preview field, instead of separating it out to another tab as Fred
does. I believe that my approach is easier to understand, because in the
mind of a user, the field order (and included fields) are dependent on
whether he is trying to insert an in-text citation vs. a bibliography.
[image:
?ui=2&view=att&th=124bf7a043d13309&attid=0.1&disp=attd&realattid=ii_124bf7a043d13309&zw]
[image:
?ui=2&view=att&th=124bf7b994d4b057&attid=0.1&disp=attd&realattid=ii_124bf7b994d4b057&zw]
[image:
?ui=2&view=att&th=124bffbb5668121a&attid=0.1&disp=attd&realattid=ii_124bffbb5668121a&zw]
Screenshot 5 - “Field order”: As mentioned above, I would merge these UI
elements to the In-text/Footnotes/Bibliography tab, because the Field Order
is dependent on the type of citation. Fred’s approach is using rows with
dropdowns, whereas my approach strings up the fields in the order in which
they appear. As I explained in my spec, I think the advantage of having an
“unused fields” section over dropdowns is that the user can always see which
other fields are available for use.
In Fred’s UI, you select the Document Type (“Item Type”) almost as the last
step, whereas in my UI, you select it first. It was mentioned in the
discussion that is is usually the starting point for users: “I want to cite
a Music Recording - how do I do it?”. Moreover, my UI proposes to use
existing field orders from other Document Types as templates to avoid having
to assemble the same field order repeatedly. As for formatting the fields,
Fred’s and my approach are pretty much the same.
[image:
?ui=2&view=att&th=124bffc8437c4470&attid=0.1&disp=attd&realattid=ii_124bffc8437c4470&zw]
Best,
Victor
Well, it’s pretty different internally too—taking “internally” to mean
"getting from what the user inputs to a CSL file", which seems like a
pretty big part. So I wouldn’t say that the only real difference is the
UI. But, sure, the idea that a new style would be a set of macro calls
with a little glue is the same. I’m not sure if you were suggesting that
that JSON representation would actually be stored anywhere, but I wasn’t
thinking that you’d have any sort of external serialization like
that—the tool would just compare lots of permutations of HTML strings
and then concatenate the associated XML macros and configuration options
when it found a close match.
Yes, it would be possible to pair your UI with the internal process I
proposed. But I made my suggestion because it could potentially free us
from some standard assumptions, such as the assumption that the tool
itself has to know how the fields are arranged. The tokens are a
necessity if the tool is generating the CSL from internal knowledge of
the language�which is why I suggested that they imply that approach�and
they’re not a necessity if all the tool cares about is the HTML output.
My proposal was intended to give us the second option. If we feel my
idea is technically feasible, we should discuss whether a token-based
approach is easier for users or simply adding unnecessary abstraction
(and code complexity) over direct rich-text editing.
Not sure, but it would probably be necessary to allow it to be edited over time?
Bruce
I’ve started reorganizing the citeproc-js tests area to accomodate
per-style testing, as a first step toward work on a revised Bluebook
style. To simplify the maintenance work, and to facilitate the
sharing of macro-driven “legal functonality” with other styles, I’m
planning to break out the constituent parts of the CSL (options,
macros, sort blocks, overloaded locale elements) into separate files,
and compose the runtime CSL from a small config file. (The directoy
layout is listed at the bottom of this message.)
It would take some effort by someone, but existing styles could be
broken out into the same framework, placing chunks of normalized and
serialized CSL code in separate files under the relevant subfolders,
and casting a config file to reassemble the style’s elements. Once
this was done, duplicates among the macros/sorts/locale elements could
be identified and purged, and the relevant config files adjusted to
point to the correct, unique library chunk.
If such an audit were carried out by someone, we would have a good
full set of library elements ready for use in a WYSIWYG tool, which
might help move things forward on this front.
The tenative folder hierarchy looks like this:
./locales
./locales/dates
./locales/opts
./locales/terms
./macros
./sorts
./styles
./styles/bluebook
./styles/bluebook/fixtures
Hope this helps,
Frank
I’ve started reorganizing the citeproc-js tests area to accomodate
per-style testing, as a first step toward work on a revised Bluebook
style. To simplify the maintenance work, and to facilitate the
sharing of macro-driven “legal functonality” with other styles, I’m
planning to break out the constituent parts of the CSL (options,
macros, sort blocks, overloaded locale elements) into separate files,
and compose the runtime CSL from a small config file. (The directoy
layout is listed at the bottom of this message.)It would take some effort by someone, but existing styles could be
broken out into the same framework, placing chunks of normalized and
serialized CSL code in separate files under the relevant subfolders,
and casting a config file to reassemble the style’s elements. Once
this was done, duplicates among the macros/sorts/locale elements could
be identified and purged, and the relevant config files adjusted to
point to the correct, unique library chunk.If such an audit were carried out by someone, we would have a good
full set of library elements ready for use in a WYSIWYG tool, which
might help move things forward on this front.The tenative folder hierarchy looks like this:
./locales
./locales/dates
./locales/opts
./locales/terms
./macros
./sorts
./styles
./styles/bluebook
./styles/bluebook/fixtures
I’ve been playing a bit a tool for analyzing the existing styles in
the respository:
http://bitbucket.org/fbennett/csl-lib/src/
Still early days, but the tool is able to extract canonical versions
of macros, sort blocks, and layouts.
This work might be useful for curating the styles as a library. A
quick look through the macros suggests that there are some which
produce the same output with trivial variations in coding. See, for
example:
http://bitbucket.org/fbennett/csl-lib/src/tip/macros/pages-5.cnf
and
http://bitbucket.org/fbennett/csl-lib/src/tip/macros/pages-6.cnf
It also turns up macros that might benefit from general adoption of a
best-of-breed version across several styles. “access”, for example,
exists in 60 variations, some of which are bound to be more robust
than others.
If the macro set and the layouts were marshalled a bit and classified
with the addition of a bit of metadata (see the ./macros directory for
what a metadata wrapper might look like), it might be possible to
build rough copies of new styles entirely from templates, with the
user first selecting a layout on the basis of generic previews,
followed by drag-and-drop replacement of compatible macro blocks into
its slots, and tweaking of options to get close to the desired effect.
Styles that require larger changes to available code could be turned
over to a designer for hand-coding.
Some more grist for the mill, anyway.
Frank
I’ve started reorganizing the citeproc-js tests area to accomodate
per-style testing, as a first step toward work on a revised Bluebook
style. To simplify the maintenance work, and to facilitate the
sharing of macro-driven “legal functonality” with other styles, I’m
planning to break out the constituent parts of the CSL (options,
macros, sort blocks, overloaded locale elements) into separate files,
and compose the runtime CSL from a small config file. (The directoy
layout is listed at the bottom of this message.)It would take some effort by someone, but existing styles could be
broken out into the same framework, placing chunks of normalized and
serialized CSL code in separate files under the relevant subfolders,
and casting a config file to reassemble the style’s elements. Once
this was done, duplicates among the macros/sorts/locale elements could
be identified and purged, and the relevant config files adjusted to
point to the correct, unique library chunk.If such an audit were carried out by someone, we would have a good
full set of library elements ready for use in a WYSIWYG tool, which
might help move things forward on this front.The tenative folder hierarchy looks like this:
./locales
./locales/dates
./locales/opts
./locales/terms
./macros
./sorts
./styles
./styles/bluebook
./styles/bluebook/fixturesI’ve been playing a bit a tool for analyzing the existing styles in
the respository:http://bitbucket.org/fbennett/csl-lib/src/
Still early days, but the tool is able to extract canonical versions
of macros, sort blocks, and layouts.This work might be useful for curating the styles as a library. A
quick look through the macros suggests that there are some which
produce the same output with trivial variations in coding. See, for
example:http://bitbucket.org/fbennett/csl-lib/src/tip/macros/pages-5.cnf
and
http://bitbucket.org/fbennett/csl-lib/src/tip/macros/pages-6.cnf
It also turns up macros that might benefit from general adoption of a
best-of-breed version across several styles. “access”, for example,
exists in 60 variations, some of which are bound to be more robust
than others.If the macro set and the layouts were marshalled a bit and classified
with the addition of a bit of metadata (see the ./macros directory for
what a metadata wrapper might look like), it might be possible to
build rough copies of new styles entirely from templates, with the
user first selecting a layout on the basis of generic previews,
followed by drag-and-drop replacement of compatible macro blocks into
its slots, and tweaking of options to get close to the desired effect.
Styles that require larger changes to available code could be turned
over to a designer for hand-coding.Some more grist for the mill, anyway.
The csl-lib bundle is about as far along as it can be taken for the
present; option extraction, and locales should wait for CSL 1.0.
Looking at what’s there so far, two things would be useful to have, if
there is interest in pushing this any further:
** Library editor **
To slim down the library would require an efficient means of renaming
macros, both in the macro and in the calls made by styles,
repository-wide. This would allow you to refactor things so that
macros with the same base name (the part before the numeric suffix)
are safe to use as drop-in replacements for one another. It would
also allow you to merge macros that are functionally equivalent. Such
a beast could probably be done in Emacs by someone with elisp skills
(which definitely ain’t me, unfortunately).
** Test generator **
Both for generating style tests and for style bug reports, it would be
nice to have a “Report style bug” facility in the word processor
plugin, which (a) identifies the target style, (b) provides a canned
set of CSL processor calls in JSON that will reproduce the context of
the target cite, and (c) provides the user-corrected form of the
citation (from the citation editor).
I realize that either of these would be a tall order, unlikely to
emerge from volunteer efforts. But you never know, I suppose.
…
I’ve been playing a bit a tool for analyzing the existing styles in
the respository:http://bitbucket.org/fbennett/csl-lib/src/
Still early days, but the tool is able to extract canonical versions
of macros, sort blocks, and layouts.This work might be useful for curating the styles as a library.
I don’t exactly understand what this code does, but it sounds good!
Bruce
…
I’ve been playing a bit a tool for analyzing the existing styles in
the respository:http://bitbucket.org/fbennett/csl-lib/src/
Still early days, but the tool is able to extract canonical versions
of macros, sort blocks, and layouts.This work might be useful for curating the styles as a library.
I don’t exactly understand what this code does, but it sounds good!
It extracts macros and sort blocks from all styles, scans for
duplicates, and maps all macro calls to one unique name for the
relevant unique macro. Just a kind of automated housecleaner. Not
sure how useful it will be, but it’s the start of … something!