quick Start Guide for CSL

Hi,

For those who are interested, I have started to make a tutorial for making citation styles, as I felt that I missed that when I had to make one of my own. I am going to make it more complete in the coming weeks, but I think the start may already be welcome. Feel free to give comments or recommendations!

see http://www.condast.com/zotero/index.html

Kees
  • One correction I'd like to see: you put formatting instructions in the citation and bibliography elements. But I'd really like to see this done in macros, and for people to understand the importance of this feature.
  • Yes I know, but I first wanted to make a minimal layout that validates correctly. The macros are terrible to go through the first time round, and so I wanted to skip them at the intro. I'm working on the macro page right now ;)

    Kees
  • edited May 23, 2009
    Just for some background, I'm wanting to rationalize the existing styles a bit around common macro names, and to extract them, for use in something like this.

    Also, at the xbib project, there's some infrastructure for the tutorial, and there's the start of one in the SVN. The idea with this was I'd use pandoc to export the markdown to syntax-highlighted HTML.

    If you see some promise on working on that, let me know. I'd be happy to consider moving the documentation over to something like github.
  • That would be great!
    I'll first let the documentation mature a little ...I'm also still learning... then when it zotero CSL developers think it serves a purpose, I'll relocate the docs, maybe with a definitive link form zotero or so.
    But first see how far I get...I'm doing this on the side because I happened to need a very specific style.
  • Right.

    Just to be clear: while Zotero uses CSL and has helped with its development, it is not a Zotero project. The whole point of it is that it can be used in different applications.
  • Mea Culpa ;)
  • as someone who - after having self-taught and trial-and-errored - have tried to help out people here with their styles I just want to say that I think this is a _great_ idea.
    I had a first look and things look great, but I'll check back later after a more in depth look.
  • Here-here. As you can tell, there is a serious desire among people involved with CSL to provide clear documentation for the language, and this is really good to see. Good going.

    Here's a thought that might help you get a little extra community leverage for your effort. We're working on a set of standard test suites for CSL implementations (example here). The idea is to test all processors in a uniform framework (no matter what language they're written in), so that if you shift from one CSL-enabled writing environment to another, you get the same results in your citations, given the same style file and the same input.

    The test files are written in a machine-friendly form, but they contain small chunks of CSL style code that would serve well as examples in a document such as your guide. Many of the present tests involve difficult or arcane operations, but we also need tests (like the one linked above) that provide straightforward illustrations of the operation of individual CSL elements and attributes. If such example tests were prepared and provided with a description, they could be dual-purposed. The test would be a helpful guide to implementers and provide QA for processors, and the CSL examples and descriptions could be extracted for inclusion in a section of your document, for reference by a wider audience. Since any changes to CSL will be tested, that portion of your document could be updated automatically. You could concentrate your efforts on explaining general concepts and providing guidance on the editing process and procedures for submission.

    To get such a workflow going would need a little effort all 'round, but it would be well worth it, and I for one would be happy to help.
  • That's an interesting idea, Frank. Taking that a little father, even, it might be a way to build up a library of standard macros as well.
  • edited May 24, 2009
    I'm game!

    Currently I'm doing this a bit on the side ...got a Ph D to finish... but I always have seen that being a newbie really helps in making good 'how-to's. So far, by looking at the different styles that have been developed, the biggest omission seems to be

    1: attributes and values: what do they do and which values are allowed
    2: coding style

    The structure is clear enough and fairly self-descriptive. So a list of good (and properly made) code chunks would really help, especially if they have short comments on what certain elements do. If they stay in bitchunk, then I can just link through to them.

    If some developers have been working on more specific issues that they feel might benefit others, then I have no problems including instructions in html format to the guide. The more input the merrier (and the faster the guide can mature!).
    If someone is interested just send your html to info-at-condast.com
  • It would save you a lot of work in the long run to work out a way to pipeline commentary and code examples direct from the tests into your doc.

    Once set up, it should require just one push command from this end, or one pull command from yours to bring all the examples up to date. Linking to the examples individually is not something I would wish on you. To give an idea, the test suite for the processor currently has 238 tests in all. The standard tests portion of the suite is the least mature part of the whole, with only 63 tests. Over the next year or two it is likely to swell to several hundred fixtures, each with its own name and URL. RSI is a definite possibility.

    There's also the readability issue. Even newcomers (like myself -- six months ago, I didn't even know that CSL or Zotero existed) can become quickly accustomed to scratching around for answers in application source code, but it's important to remember how intimidating machine code is when it first pops up on the monitor. The great thing about a guide is that it's a document written for people, interspersed with machine-code examples, rather than the other way around. Building a single document with a uniform "look and feel" would present a much friendlier face to users in the early days of their exposure to Zotero, when they are most likely to get flummoxed.

    If we slow down at this point to figure out how to make things present well while being easy to maintain, it will be more fun -- and if maintenance is pleasant, you won't have to worry about carrying the can always and indefinitely, because others will be more willing to pitch in when you're busy with other things.

    So ... what are you using to draft the guide at the moment?

    (One small point, lest I forget to mention it later: the charset in your pages should probably be set to UTF-8 rather than iso8859-1, since Zotero and CSL speak Unicode).
  • edited May 24, 2009
    Frank: tests definitely need to be UTF-8. Among other things, sorting unicode correctly is both important, often wrong (a lot of languages just don't do well with unicode), but testable.

    Just to be clear, my comment about the macros was meant to suggest the possibility of killing three birds with one-ish stones: documentation, test suite, MakeCSL style creation wizard.
  • edited May 24, 2009
    Is MakeCSL supposed to be limited to selecting a list of premade macros, without any adaptation of the selected macros? Also, it might make a good case study to start with the citation section, as each style will only contain a small set of macros: citation-contributors, citation-date and citation-locator (for author-date styles) or citation-number (for numbered styles).
  • edited May 24, 2009
    In MakeBST, there's a "master" file that includes these instructions, which the script then uses to assemble the output style. To do the same thing conceptually with CSL could mean a "master.csl" file that only includes macros, which might have names like "apa:titles" or "chicago:authors". A script would just take, say, JSON as input, and pull in the appropriate macros.

    Of course, the macros could also be stored as individual files; makes little difference technically.

    And yes, your idea makes sense.
  • edited May 24, 2009
    Gentlemen,

    I am happy with the online enthusiasm! I will look into the various suggestions coming week (busy week ahead, see how far I come), but I'm definitely in for a slow but good approach than a quick 'n dirty one! I think every bit of html that is made available will already be of help, so grow slowly is good for me. I work in Eclipse (I'm a JAVA/Eclipse junkie) for the html/xml stuff, and I've been using Zotero for 4 months now. Usually the IEEE was perfect for me, but at some point you get into the custom styles...
    I'll make the changes a.s.a.p.

    thanks again!
  • edited May 24, 2009
    I've been thinking about your posts, and have looked a bit deeper into the the test sets, and so on. I am still trying make sense of all this, so I may be a bit off mark here, but this is the idea I am getting:

    Currently my documentation is evolving into a style that (for every html page) describes a bit of functionality, that can be validated and ends with the output of the zotero test pane. I currently include the test.csl for each of these steps.

    If I understand your ideas correctly, then the examples should basically become, or be based on test sets, that are then validated in the CSL. So the advantage would be that the csl files I'm currently developing by hand are pulled out of the test repository, with all the improvements this brings.

    In this scheme, my main requirement would be that I want to start with a minimum csl that validates correctly, and that every test set focuses on one bit of functionality (or a related set of functionalities) at a time. It should be possible to see the full listing in the html doc (probably with a collapse function)
    So if I can make a call to a certain test set, then I can basically weave a story around the available tests, from simple to more advanced topics. The how-to can then evolve with the test sets.
    On a side note, I think we should be very aware that a large group of people who will work on styles are not going to be programmers, but rather from a wide audience who need to 'tweak' existing styles for their purpose. This group is usually not served with 'technical' follow-the-XML type of instructions..that is usually the reason why techies don't make good manual writers for this audience; technical logic is different than user logic.

    Now comes the second part. Ideally, a citation style developer would want to download the test set, modify it, validate it and use it. If I project a possible use case based on test sets, then a developer will take little bits of functionality from every test set and compile her/his own file based on this.
    I have the feeling that you're telling me that this will can also be automated to some extent using javascript/JSON but here things become somewhat foggy for me.
    Are you for instance thinking of the following use case?

    1: The user looks for a certain functionality in the how-to guide
    2: in the corresponding web page, s/he can click a test set.
    3: S/he wants to change a few things and validate this with one button click
    4: When s/he has the requested functionality, the corresponding file can be saved for final use.

    Is this a use case that is feasible/wanted?
  • Hi All,

    I have found keesp tutorial very interesting as a starting point, however, I had some trouble to go further do to a `mismatch`in tags right after second sample of code and could not figure out how to fix it.

    I just would like to know if anyone else tried it out and face the same problem?

    actually, ive been struggle for a while trying to get help to adapt an existing style, I have tried different styles with no success. If there is also another tutorial based on 'overwriting' techniques, I would really appreciate it!
Sign In or Register to comment.