Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update zeitschrift-fur-medienwissenschaft.csl #3371

Merged
merged 8 commits into from Mar 12, 2019

Conversation

Projects
None yet
4 participants
@tillheilmann
Copy link
Contributor

tillheilmann commented Mar 6, 2018

Complete rewrite of style using reference CSL template (http://www.tillheilmann.info/code/referenz-geisteswissenschaften-heilmann.csl). It now adheres more closely to journal's style guide, supports (almost) all CSL types and fields and has better documentation.

Update zeitschrift-fur-medienwissenschaft.csl
Complete rewrite of style using reference CSL template (http://www.tillheilmann.info/code/referenz-geisteswissenschaften-heilmann.csl). It now adheres more closely to journal's style guide, supports (almost) all CSL types and fields and has better documentation.
@csl-bot

This comment has been minimized.

Copy link

csl-bot commented Mar 6, 2018

Awesome! You just created a pull request to the Citation Styles Language styles repository. One of our human volunteers will try to get in touch soon (usually within a week). In the meantime, I will run some automated checks. You should be notified of the results in a few minutes.

If you haven't done so yet, please make sure your style validates and follows all our other Style Requirements.

To update this pull request, visit the "Files changed" tab above, and click on the pencil icon (see below) in the top-right corner of your style to start editing.

If you have any questions, please leave a comment and we'll get back to you. While we usually respond in English, feel free to write in whatever language you're most comfortable.

@csl-bot

This comment has been minimized.

Copy link

csl-bot commented Mar 6, 2018

😟 There are some issues with your submission. Please check the test report for details.

Fixed update to zeitschrift-fur-medienwissenschaft
Fixed errors in header and removed unused macro.
@csl-bot

This comment has been minimized.

Copy link

csl-bot commented Mar 6, 2018

😃 Your submission passed all our automated tests.

@adam3smith

This comment has been minimized.

Copy link
Member

adam3smith commented Apr 14, 2018

So I've looked at this a bit now and while it's definitely very impressive,
I have some reservations about the approach in general, in order of importance.

  1. The style is unmaintainable. CSL is a collaborative project and relies on the ability of multiple people to address issues in a style. Even for the Chicago manual styles, this has gotten difficult. This one is more than twice the size of the CMoS styles and coded in such a way that changes to a single item type or a single element have to be made in countless places. Other than you, who will be able to keep this maintained?
  2. Relatedly, and probably because this is based on a template(?) the coding seems inefficient to me:
    <else-if type="broadcast" variable="container-title" match="all">
  	<text variable="container-title" font-style="italic" text-case="title"/>
      </else-if>
      <else-if type="broadcast" variable="container-title-short" match="all">
  	<text variable="container-title-short" font-style="italic" text-case="title"/>
      </else-if>
      <else-if type="broadcast" variable="title" match="all">
  	<text variable="title" font-style="italic" text-case="title"/>
      </else-if>
      <else-if type="broadcast" variable="title-short" match="all">
        <text variable="title-short" font-style="italic" text-case="title"/>
</else-if>

For one, CSL was built on the idea that some constellations or variables do not exist. It does not make any sense to me, for example, for an item to have a short title or container title and not have a title/container title. I suspect the style could (and imo should) be massively simplified.
Moreover, I find it hard to believe (but also hard to tell, see 1.) that this really has to be done for different item types individually to the degree that is the case in the style. Again, CSL is based on the idea that most citation styles allow you to abstract to a fair degree and handle constellations identically across item types. There are obviously going to be some examples (legal cites, letters), but to this degree?

Apart from maintenance and principled concerns about code efficiency, there are also very real performance concerns. We have no idea how something this large & complex will perform across processors and in large documents.

  1. The sheer size of the style -- more than 5 times the CSL average and more than twice as large as the current larges style -- also strikes me as a problem if it becomes standard practice. I'm less sure about the nature of this problem, but both the total size of the CSL repository and the dynamic online loading of CSL styles as used by many applications strike me as potential problems.

These are just initial thoughts. I'd like to hear from @rmzelle and I'm certainly open to be convinced, but currently I'm skeptical.

@tillheilmann

This comment has been minimized.

Copy link
Contributor Author

tillheilmann commented Apr 16, 2018

Dear Sebastian,

I understand your concerns. The style is big and the code goes to (sometimes seemingly absurd) lengths to get everything right and to accommodate for every conceivable combination of types and fields/variables. As you guessed, this is due mostly to the fact that I derived it from my "complete" template style referenz-geisteswissenschaften-heilmann whose sole purpose is exactly that: to support every type and every field of the CSL 1.0.1 specification. If you want this done "right", especially for references of the German humanities sort, then there are a lot of possibilities to consider. (I could send you my "proof" sheets showing different cases of broadcasts, all "real life" examples). As you said yourself, big styles like CMoS are complicated almost by necessity. Still, I absolutely get your point and I think I can "shave off" a lot of code for this particular journal style (I could throw out many types). Performance issues are very important. I somewhat disagree with your first point, though: I find it quite easy to adapt the "complete" reference style to different needs and I think the modular structure helps a lot. Anyways: I will look at the code in the coming days (start of the semester here) and see want I can cut out and simplify. You can then consider it again.

Thank you for your diligence!
Till

@tillheilmann

This comment has been minimized.

Copy link
Contributor Author

tillheilmann commented Apr 25, 2018

Before I submit a new version of the style... I have revised the code, removed support for types unlikely to be used in the journal ("bill", "legal_case" and "legislation"), removed support for 'weird' constellations (such as entries with short-title but no title etc.) and simplified some macros. The code is now (not counting the lengthy comment at the beginning) 2000 lines long. The general structure of the code remains unchanged. Will you review a style of this size? I could probably cut some more but then would have to compromise support for complicated cases like CSL type "song" (used by Zotero for both audio recordings and podcasts), "motion_picture" (used by Zotero for both video recording and film) or "map" and "personal_communication" (many different scenarios).

@rmzelle

This comment has been minimized.

Copy link
Member

rmzelle commented Apr 26, 2018

I'd like to hear from @rmzelle

3000+ lines does seem a little excessive. (I only briefly looked at the style, and didn't take the time to figure out how well it's structured; hard to judge from a quick glance, which I guess is partially @adam3smith's point)

I derived it from my "complete" template style referenz-geisteswissenschaften-heilmann whose sole purpose is exactly that: to support every type and every field of the CSL 1.0.1 specification.

Especially for journal styles, that seems like overkill. And modeling styles after CSL, instead of directly after the demands of the journal, also seems like it unnecessarily complicates matters. (in the natural sciences, a CSL style that correctly formats journal articles, books, and chapters often covers 90%+ of all references, and there are real costs in complexity in trying to cover every corner case)

@adam3smith

This comment has been minimized.

Copy link
Member

adam3smith commented Apr 26, 2018

Especially for journal styles, that seems like overkill. And modeling styles after CSL, instead of directly after the demands of the journal, also seems like it unnecessarily complicates matters.

Yes, that's a good point that I'd want to discuss before deciding on whether I´d want to review 2000 lines of code. The Chicago Manual guide that we take somewhere around1,500 lines to implement has something like 100 pages dedicated to references, covering more then 200 different scenarios. For something like that I think a complex style would be OK, even if it´s a lot less widely used as the Manual. But zfm's styleguide basically covers 6 or 7 different item types on 4 pages (which makes sense for a journal; I'm not saying it should be more complicated), so I'm wondering about Verhältnismäßigkeit.

Update zeitschrift-fur-medienwissenschaft.csl
Shortened code drastically. Explicit support only for types mentioned in journal's style guide.
@tillheilmann

This comment has been minimized.

Copy link
Contributor Author

tillheilmann commented May 8, 2018

Okay, so I reduced the code to about 800 lines. It now only (explicitly) supports the types/cases mentioned in the journal's style guide. Everything else can fail catastrophically.

EDIT: Grammar.

@csl-bot

This comment has been minimized.

Copy link

csl-bot commented May 8, 2018

😃 Your submission passed all our automated tests.

Update zeitschrift-fur-medienwissenschaft.csl
Fixed conditional in macro <volume-and-issue>
@csl-bot

This comment has been minimized.

Copy link

csl-bot commented May 8, 2018

😃 Your submission passed all our automated tests.

@csl-bot

This comment has been minimized.

Copy link

csl-bot commented Jun 13, 2018

😃 Your submission passed all our automated tests.

adam3smith added some commits Jul 8, 2018

Simplifications
1. Reduce complexity using groups, behavior of form="short" & better conditionals (output unchanged)
2. Change instructions at beginning to preferred syntax
3. Fix uncertain original data (was testing for issue)
@csl-bot

This comment has been minimized.

Copy link

csl-bot commented Jul 8, 2018

😟 There are some issues with your submission. Please check the test report for details.

@csl-bot

This comment has been minimized.

Copy link

csl-bot commented Jul 8, 2018

😟 There are some issues with your submission. Please check the test report for details.

@csl-bot

This comment has been minimized.

Copy link

csl-bot commented Jul 8, 2018

😃 Your submission passed all our automated tests.

@csl-bot

This comment has been minimized.

Copy link

csl-bot commented Oct 28, 2018

😃 Your submission passed all our automated tests.

@adam3smith

This comment has been minimized.

Copy link
Member

adam3smith commented Oct 31, 2018

sorry for letting this sit -- will review asap

@adam3smith adam3smith self-assigned this Oct 31, 2018

@stale

This comment has been minimized.

Copy link

stale bot commented Dec 26, 2018

This issue hasn't seen any activity in the past 30 days. It will be automatically closed if no further activity occurs in the next two weeks.

@stale stale bot added the waiting label Dec 26, 2018

@stale stale bot closed this Jan 9, 2019

@adam3smith adam3smith reopened this Jan 10, 2019

@stale stale bot removed the waiting label Jan 10, 2019

@adam3smith

This comment has been minimized.

Copy link
Member

adam3smith commented Jan 10, 2019

sorry, this is may bad and should have been reviewed a while ago. reopening

@csl-bot

This comment has been minimized.

Copy link

csl-bot commented Jan 10, 2019

😃 Your submission passed all our automated tests.

@tillheilmann

This comment has been minimized.

Copy link
Contributor Author

tillheilmann commented Feb 5, 2019

Okay, do I have to do anything?

@stale

This comment has been minimized.

Copy link

stale bot commented Mar 7, 2019

This issue hasn't seen any activity in the past 30 days. It will be automatically closed if no further activity occurs in the next two weeks.

@stale stale bot added the waiting label Mar 7, 2019

@adam3smith

This comment has been minimized.

Copy link
Member

adam3smith commented Mar 12, 2019

My apologies for letting this sit so long. I'm fine with the style as is -- I'm still not convinced checking for short-titles in the absence of regular titles makes a lot of sense, but this adds about 20 lines here that aren't worth spending much time arguing, so let's keep them in.

I think the style's et al. approach is odd (u.a. means "und andere" after all, and if an item has two authors and you're just leaving one out that's ... ungrammatical, but I agree that's the best reading of the ZfM guidelines.

Thanks for doing this and apologies, again, for the completely unreasonable time this has been waiting for review.

@stale stale bot removed the waiting label Mar 12, 2019

@adam3smith adam3smith merged commit b4671f4 into citation-style-language:master Mar 12, 2019

1 check passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details

@tillheilmann tillheilmann deleted the tillheilmann:patch-8 branch Mar 12, 2019

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.