search

Juris-M / zotero

Juris-M is a variant of the free and friendly Zotero research platform, with support for legal and multilingual materials.
https://juris-m.github.io
Other
77 stars 12 forks source link

juris-* macros in juris-m .csl files not taking effect in MS Word. #52

Closed JohnLukeBentley closed 4 years ago

JohnLukeBentley commented 6 years ago

Following the tutorial at the Juris-M editor https://juris-m.github.io/editor/ I'm expecting to be able to add code to the marcro's prefixed with juris-.

However, behold my gist JohnLukeBentley/jlb-test-jm-indigobook.csl

With respect to JM Indigo Book I've made the following modifications:

In MS Word I have a Statue (legislation type) and Case (legal_case type) output as follows:

Statue:

Strata Schemes Management Act, JLB 002 § 100 (Australia New South Wales 2015) JLB 003.

Case:

R v Ahmad Alameddine; R v Lee McArthur [2018] NSWDC 43, JLB 002 (Australia New South Wales District Court of New South Wales Feb. 9, 2018) JLB 003.

The output "JLB 001" is missing when I'd expect it to override the titles to produce something like:

Statue:

JLB 001, JLB 002 § 100 (Australia New South Wales 2015) JLB 003.

Case:

JLB 001, JLB 002 (Australia New South Wales District Court of New South Wales Feb. 9, 2018) JLB 003.

Perhaps the processor provides sensible defaults when it encounters a blank juris- prefixed macro, as in ...

<macro name="juris-title">
  <text value="" />
</macro>

... but there's a bug in the processor that means it fails to pick up on non blank juris- prefixed macros. That is, it wrongly ignores ...

<macro name="juris-title">
  <text value="JLB 001" />
</macro>

???

Edit: I'm on 5.0.44m22

fbennett commented 6 years ago

The Indigo book style is modular. The juris- prefixed macros in the style are placeholders that will be used only if the modular-style infrastructure is not available (as in Mendeley or Zotero).

To see output from your code, use the online editor. Open a jurisdiction for editing. Paste in your juris macro to replace the sample version. Add your change to juris-title. The style module should validate, and you can preview the behavior of the style.

If bundled with Juris-M, the module would be used when that jurisdiction is set in the Jurisdiction field of an item.

JohnLukeBentley commented 6 years ago

In addition to testing output with the JurisM MS word plugin I've lately taken your suggestion above and tested output with the editor. I get contradicting results. Before detailing that I might ask a high order question to clarify what I should expect ...

Module Composition: Scaffolding and Components

Each bracketed term [in citation sample output] comes from a separate CSL macro (a component) supplied by the legal style module. Components are joined together in the style that calls the module, with code that we will call the scaffolding.

In our module for Atlantis, the scaffolding is contained in the cs:citation element at the bottom of the file. We will not touch this block in this tutorial—it is, in fact, not part of the module code. In production, our module will be called by another, more general style (Chicago Full Note, APA, OSCOLA, etc.), and the calling style will supply its own scaffolding.

The module components consist of a set of juris-prefixed macros. Here is the full list of them, all of which must be defined:

From that I take it I'm to understand that in a *.csl file that targets juris-m, when used with Juris-M, rather than Zotero or Mendeley:

But I'm a bit confused by ...

The Indigo book style is modular. The juris- prefixed macros in the style are placeholders that will be used only if the modular-style infrastructure is not available (as in Mendeley or Zotero).

...

If bundled with Juris-M, the module would be used when that jurisdiction is set in the Jurisdiction field of an item.

... which would seem to mean:

If jm-indigobook.csl has been modded so that the "module" (juris- prefixed macros) have been defined:

To put this as a question:

If jm-indigobook.csl has been modded so that the "module" (juris- prefixed macros) have been defined and this is used with JurisM against an Entry with a jurisdiction set, which of the following should occur:

?

Note this question, a question of when the "scaffolding" (CSL conventional cs:citation code) is ignored, is orthogonal to the original post ... as that post (so it appears to me) demonstrates a case where the "module" (juris- prefixed macros) is ignored while the other relevant conditions are met:

... but if you answer the question I ask in this post (and correct any other misunderstanding I'm betraying) then I might be able make the original post clearer.

fbennett commented 6 years ago

Your confusion is understandable. The documentation was written soon after coming off the coding of modular style support, and it could do with a round of revision for readability.

From that I take it I'm to understand that in a *.csl file that targets juris-m, when used with Juris-M, rather than Zotero or Mendeley:

  • A "module" entails the set of juris- prefixed macros; and
  • The "scaffolding" contains cs:citation code which will (for entries with a jurisdiction set) call the "module" (some set of juris- prefixed macros).

Yes, that's the scenario.

If jm-indigobook.csl has been modded so that the "module" (juris- prefixed macros) have been defined:

  • In Zotero or Mendeley: the "module" (juris- prefixed macros) will be ignored and the "scaffolding" (CSL conventional cs:citation code) will be used; and
  • In JurisM and against an entry with a jurisdiction set: the "module" (juris- prefixed macros) will be used and the "scaffolding" (CSL conventional cs:citation code) will be [also used | or ignored (I'm not sure which)];

It's the latter. The macros defined in the style are replaced by the instance in the module. When I wrote "scaffolding" in the docs, I meant the macro that calls the modular elements the "jurism" macro in the JM styles, if I recall correctly), not the eponymous placeholders. The scaffolding controls how the elements will be joined together, how back-references will be composed, and might add some styling (like italics on juris-title, say). Working out which aspects of a cite are determined entirely by the jurisdiction, and which aspects can be controlled by the calling style, was the hardest part of the design. (And the hardest part of that was the handling of locators and locator labels. I think the solution in code is solid, but the documentation for that may be particularly opaque.)

If jm-indigobook.csl has been modded so that the "module" (juris- prefixed macros) have been defined and this is used with JurisM against an Entry with a jurisdiction set, which of the following should occur:

  • the "module" (juris- prefixed macros) will be used and the "scaffolding" (CSL conventional cs:citation code) will be also be used.
  • the "module" (juris- prefixed macros) will be used and the "scaffolding" (CSL conventional cs:citation code) will be ignored.

Again, the latter. Thejuris- macros in the parent style are used only if the processor has no jurisdiction support, or support has been disabled. Note, though, that only the juris- macros overwrite their counterparts.

Does that help to clarify? If something still seems not right, let me know: I'm confident that it's working correctly, but it's also important that it be understood (and comprehensible).

fbennett commented 6 years ago

Ah - there are two points that I should have raised more clearly earlier.

  1. The style editor shows how the elements operate, but within the scaffolding written into the module. That scaffolding is used only for testing purposes. The calling style will provide its own scaffolding, which may combine the elements in a slightly different way (with changes to punctuation, etc.).
  2. When a module is saved via the Submit button, it does not immediately become available in Juris-M. It is saved as a pull request to the Juris-M/style-modules project on GitHub. I never merge the zz samples, since they are not meant for production. For production modules, there is a workflow:
    • The change is merged to the style-modules master.
    • The master branch of style-modules is pulled into the myles plugin project master.
    • The master branch of the myles plugin is pulled into the zotero-standalone-build project.
    • Deployment scripts in zotero-standalone-build are used to compose the working client and binary updates for clients in the wild.
    • Clients in the wild call home and receive the updated myles plugin, as part of a general update.

At the end of all that, the module is available in clients via the Word and LibreOffice plugins. Testing locally in Word would require a local development copy of the client. That takes some work to set up, and it isn't really necessary, since the online style editor tells the truth about the behavior of the module code.

JohnLukeBentley commented 6 years ago

Online Editor Submitting

On submitting csl files (Styles) entered via the online editor. Thanks for that explanation. I had assumed [Submit] just saved a user's file between sessions - for testing/play purposes only. I wasn't aware that this was made available to a production Juris-M (via the plugin architecture you describe). I see, for example and as you describe, my practice sessions manifesting as pull requests at https://github.com/Juris-M/style-modules/pull/240 (You, fbennett, can reject those pull requests).

As a matter separate to this thread's purpose it might be worth providing a [Temp] V [Production Save] submit option.

Adjust code or documentation

Your confusion is understandable. The documentation was written soon after coming off the coding of modular style support, and it could do with a round of revision for readability.

On the other hand I do see you've put a great deal of good effort into the documentation. Having an interactive tutorial to demonstrate the jusris-m, csl based, file format is a great tool. But yes there's room for revision for readability. And, yes, if this thread doesn't identify a need to change code it my revealed confusion might assist in identifying points where the documentation can be revised. However ...

I'm confident that it's working correctly,...

Given that, my understanding needs further correction to account for the contradicting output I'm getting.

Contradicting output

Overview

So from your response above I have confirmed, that if I use

... then, with regard to the the JurisM MS Word Plugin ...

the "module" (juris- prefixed macros) will be used and the "scaffolding" (CSL conventional cs:citation code) will be ignored.

I'll call that "the expected output".

However, the online sampler (aka the "editor", at https://juris-m.github.io/editor/) output contradicts the expected output ...

"module" (juris- prefixed macros) is used and the "scaffolding" (CSL conventional cs:citation code) is used.

... and, as I attempted to demonstrate in the first post, Juris-M's Word plugin output contradicts both the expected output, and the online sampler output:

"module" (juris- prefixed macros) is ignored and the "scaffolding" (CSL conventional cs:citation code) is used.

These results can be reproduced as follows ...

Reproduce in online editor

Setup the entry in JurisM:

In https://juris-m.github.io/editor/ :

Note the only purpose for my <text value="JLB XXX" /> nodes in jlb-test-jm-indigobook.csl is just to mark which code a processor picks up during output. That is, those JLB nodes are just debugging nodes.

The remaining juris-* macros remain undefined.

These debugging nodes aren't intended to represent my beliefs about the location of where production modifications should occur. And, moreover, I'm aware that in production underneath <macro name="juris-title"> you'd be wanting <text variable="title"/> somewhere (with all the conditions and formatting that constitute the Jurism/csl author's desires).

So with those debugging markers in place the output seems to show: the "module" (juris- prefixed macros) is used and the "scaffolding" (CSL conventional cs:citation code) is used.

Reproduce using JurisM MS Word Plugin

So the two juris-m processors, the one driving the https://juris-m.github.io/editor/ and the one driving MS Word, produce different results given the same input file jlb-test-jm-indigobook.csl and the same entry data (assuming no mistake).

But the chief point is that the JurisM MS Word Plugin output seems to show: the "module" (juris- prefixed macros) is ignored and the "scaffolding" (CSL conventional cs:citation code) is used. This contradicts the expected output.

Summary of contradicting output

Output Location "module" (juris- prefixed macros) "scaffolding" (CSL conventional cs:citation code) Example
Expected Used Ignored JLB 001
Online Sampler Used Used JLB 001, JLB 002 JLB 003.
Word Plugin Ignored Used Strata Schemes Management Act, JLB 002 (Australia New South Wales 2015) JLB 003.

It seems to me you must either:

fbennett commented 4 years ago

The online editor has been discontinued, in favor of Citeproc Test Runner, which can perform batch testing of the legal style modules in the context of a calling style.