ZotFile User-Defined Wildcards - Figuring it all out.

GrantRobertson

This thread is for people who want to figure out how to use the User-Defined Wildcards in ZotFile and how to use them to rename files in Zotero.

The only description I can find for how these work is at http://zotfile.com/#user-defined-wildcards, but I find that description to be very lacking. It assumes all kinds of additional knowledge and is vague in many ways. It also provides instructions that are out of date and leaves many things completely out. When I have asked questions, people have simply referred me to the same web site or told me to read the code. I do not consider these to be helpful answers.

So, I am starting this thread for people who want to actually figure out how User-Defined Wildcards work. It is for all those people who couldn't figure out what the ZotFile.com web site was talking about but just gave up. And all those people who cannot just "read the code." If developers or those associated with Zotero or ZotFile want to actually contribute, they are welcome. However...

Posts that merely refer people to ZotFile.com or say that you have to use RegEx (regular expressions) or tell people to "read the code" are not welcome. We know that we have to use regular expressions for some parts of User-Defined Wildcards. But regular expressions are not the be-all end-all of understanding ZotFile's User-Defined Wildcards. To be clear: I am NOT saying that people should not refer to passages on ZotFile.com and try to explain them or understand them. But if all you are going to do is say, "Read ZotFile.com." then how is that helpful?

Also, to be clear: I am not "Demanding" that people help me or anyone else. What I am saying is: If you are going to be un-helpful, then why bother to even post?"

Now that I have gotten all that off my chest: Let's get on to figuring this thing out...

GrantRobertson

"Exclusive Wildcards" and their implications:

The first thing that I have figured out is that renaming files is a two phase/level process. You have the "wildcards" (ether the standard ones or the user-defined ones) and then you have how they are used in the renaming fields in ZotFile preferences. In other words, some of the work is done deep within ZotFile as it figures out what value to insert into the wildcard. But, then, ZotFile uses the combination of all those wildcards and other text to determine the final name to give the file.

For instance, the %w wildcard automatically determines whether the journal name exists and if not, inserts the publisher name instead. That work is done completely behind the scenes, using JavaScript code buried deep within ZotFile. You could create a user-defined wildcard (lets call it %X) to take the first three characters of the journal name and then the first three characters of the publisher name. But, then, you would use the renaming format field to tell ZotFile where in your final file name you want those six characters to appear. For instance: "FirstPart-%X-LastPart" would give you something like "FirstPart-JJJPPP-LastPart" (assuming the journal was named JJJournal and the publisher was named PPPublisher).

OK, this is all already explained on the ZotFile.com web site. But here is an important part, and why I am going to all this trouble to explain this: The vertical bar creates a conditional statement within the renaming field. This is very important. As stated on ZotFile.com "Exclusive wild-cards such as %s|%j will generate the entry for %s if that exists and the entry for %j otherwise." ZotFile.com calls these "Exclusive wild-cards" but does not explain the implications very well. What this means is that there is no need to try to create conditionals within your user-defined wildcards.

What it really means is that there was no need for the %w wildcard. The same functionality would be achieved just by using {%j|%p} in your renaming format field. What this means for you is to keep your user-defined wildcards simple. Don't try to build in conditional functionality that could be handled within the renaming format field. If you make your user-defined wildcards as simple as possible, then you (and others using your user-defined wildcard) will have the most flexibility in how they use them in the renaming format field.

OK, what this means is that my example for %X, above, was a bad example. You should not combine the information from the two fields into one user-defined wildcard. You should split that out. Define one wildcard for the first three characters of the journal name (%1) and a SEPARATE wildcard for the first three characters of the publisher name (%2). This will allow you to also do things like "FirstPart-%1-MiddlePart-%2-LastPart" if you want to.

Well, I am not going to be able to sus out and explain everything about the user-defined wildcards in one post or one day. But this is a start. I though it was important to start with one of the most fundamental design considerations for our user-defined wildcards before going any further.

GrantRobertson

Using "Optional Wildcards"

On ZotFile.com the author says, "Optional wild-cards mean that {-%y} only includes the seperator - in the filename if %y is defined." That is all he says about this important feature. This is another aspect of conditional logic that is handled within the renaming format field and therefore does not need to be handled within your user-defined wildcards.

From what I can gather, ANY text included within the curly braces is NOT included in your final file name if ANY of the wildcards within those curly braces returns an empty string. I believe he means for the first example to illustrate that:

{%a}{-%y}{-%j (%s)} - Abbott-1990-American Journal of Sociology (AJS)
(if either “%j” or “%s” is empty, “Abbott-1990”)

This appears to mean that if either “%j” or “%s” is empty then the entire "expression" {-%j (%s)} is left out.

Again: Yes, this is stated on the ZotFile.com page but it is not explained well at all. And the description about it is separated from the example that illustrates it by so much additional text that both do not normally appear on the screen at the same time. This makes it hard for people to put the two together.

What this means, again, is to keep your user-defined wildcards simple. Let the "Optional Wildcards" feature do the work for you. Don't try to create a user-defined wildcard that includes all that conditional logic buried deep within it. Again, this gives you the maximum flexibility in how you and others can use your user-defined wildcard.

GrantRobertson

Here is the text of another question that I posted over in another thread. That thread is for ALL ZotFile questions and I feel it is getting a little long in the tooth. This thread is ONLY for questions and explanations about the user-defined wildcards in ZotFile. Here is the text of that question:

Another fundamental question about ZotFile that is not explained on the website:

{I have edited this message to use the code tags below.}

What are all the parts of this bit of code?:

"2": {
"default": "publicationTitle",
"book": "publisher",
"bookSection": "publisher"
},


I understand that it is JSON (or a modified version thereof).

Can I assume the "2" is the variable that I will then enter in the renaming field in the ZotFile preferences?

I also assume that "default" means that this line represents the default value to use to replace the %2 when renaming the field.

Is the "publicationTitle" a field name in Zotero?

Is "book" an item type in Zotero? Does that line mean "If the itemType is a book then replace the variable with the data in the "publisher" field"?

So, does the next line mean the same thing for when the itemType is a "bookSection"?

What do you do when the itemType is a "book" but there is no value in the "publisher" field?

What is all that extra stuff in the definition for %4:

"4": {
"default": {
"field": "title",
"regex": "([\\w ,-]{1,10})[:\\.?!]?",
"group": 1,
"transform": "upperCase"
},
"journalArticle": "publicationTitle"
}


The part within the {} for "default." What does that do? What are all those parts and why are they there? I've done some programming before. But the description about this is the most terse text I have ever seen. Can anyone explain to me what the heck is going on here?

Again, if all you are going to say is that I need to learn JSON or regular expressions, then don't bother to post. I know I am sounding pretty adversarial here. That is because it seems there are some here who want to pretend to be being helpful while providing no help at all. This thread is for people who want to be helpful. I have been using Zotero for years now. I do not want to have to switch to a commercial product. I cannot afford to switch to a commercial product. I don't think it is too much to ask for the people who don't want to actually be helpful to just not post. Again, I am not demanding that anyone help. But, for all that is good and holy about open-source software, stop trying to shut down someone who is TRYING to be helpful.

DWL-SDCA

Although this comment isn't exactly what you insist that you need I am posting a recommendation that will actually help you with your immediate problem here _and_ will greatly assist you with other computer-related issues.

Please take a step back. You are making this far more difficult than it needs to be. At first these things can seem opaque but you don't need to know anything more than the most elementary level.

1) Take a few minutes to learn the basics and you will have gone a long way toward accomplishing what you need to understand more advanced features. For example, If you want to appear in this forum text that is formatted in an exact way you should enclose it within opening and closing "code" tags like this:


<code>
This text is
formatted
with indents and it can contain important characters that cannot otherwise be displayed.
< / c o d e > without spaces

-- there is a way to have that last tag display correctly without the added-spaces hack but I cannot immediately remember. (To get the code tags to correctly appear here I doubled them. View the page source for this page to see what I mean.)

2) All you need to know about regular expressions can be learned in less than the time it took you to write your posts on this topic. Please spend 10-15 minutes to do this. Make a "cheat sheet". Your English language writing skills demonstrate that you easily have the intellectual capacity to learn enough about regular expressions to apply that knowledge to Zotfile. --Aside: regular expressions can be _very_ powerful and _very, very_ complex but you only need the very basics.

3) JSON: You do not need to learn JSON or JavaScript. You do need to memorize (or make a cheat sheet of) the labels for author, title, publication-name, year, etc.

4) A user of ZotFile CAN apply very complex knowledge to generate very complex file names. However, from your posts, I don't think you want complexity.

bwiernik

In one of your other threads, I linked to a page with the full list of Zotero item types and fields. Please look at that.