Mirror top-level English docs to internal copies

i18n/en-US/readme/CHANGELOG.md

@@ -1,3 +1,9 @@
+* In version 3.2.0b:
+
+    + Update item select link to newer format used by recent version of Zotero
+    + Add functions to copy select links and web links to collections
+    + Add copy/paste item field functions
+
 * In version 3.1.0:
 
     + Update Chinese translation

i18n/en-US/readme/docs/COMMANDS.md

@@ -42,34 +42,33 @@ In the Zutilo preferences (accessed from the same menu as Zotero's preferences),
     Set all selected items to be related to each other.
 
 * __QuickCopy items:__
-	Copy selected items to the clipboard using the "Default output format" specified in the "Export" section of Zotero's preferences.
-	There are also two alternative QuickCopy items (labeled "alt 1" and "alt 2").
-	These items will copy to the clipboard using alternative export translators.
-	To select the translators used by these functions, the corresponding preferences `extensions.zutilo.quickcopy_alt1` and `extensions.zutilo.quickcopy_alt2` must be set in the config editor.
-	Each preference should be set to whatever appears in the config editor for the `export.quickCopy.setting` preference when the desired translator is set as the "Default output format" in Zotero's preferences.
-        The config editor can be opened from the Advanced pane of Zotero's preferences window (or by visiting `about:config` if using Zotero as a Firefox add-on).
+    Copy selected items to the clipboard using the "Default output format" specified in the "Export" section of Zotero's preferences.
+    There are also two alternative QuickCopy items (labeled "alt 1" and "alt 2").
+    These items will copy to the clipboard using alternative export translators.
+    To select the translators used by these functions, the corresponding preferences `extensions.zutilo.quickcopy_alt1` and `extensions.zutilo.quickcopy_alt2` must be set in the config editor.
+    Each preference should be set to whatever appears in the config editor for the `export.quickCopy.setting` preference when the desired translator is set as the "Default output format" in Zotero's preferences.
+        The config editor can be opened from the Advanced pane of Zotero's preferences window.
 
 * __Copy select item links:__
-	Copy links of the form "zotero://select/items/ITEM_ID" to the clipboard for each selected item.
-	Pasting such a link into the Firefox address bar will select the corresponding item in the Zotero Firefox plugin.
-	Following links from other applications and having the links select items in the Zotero Standalone client may also be achievable but might require additional set up.
+    Copy links of the form "zotero://select/library/items/ITEM_ID" to the clipboard for each selected item.
+    Following links from other applications can select items in the Zotero Standalone client but might require additional set up.
 
 * __Copy Zotero URIs:__
-	Copy (www.zotero.org) links to the clipboard for each selected item.
-	If you have a (www.zotero.org) profile, following such a link will open the page for the corresponding item in profile on (www.zotero.org).
-	If you do not have a (www.zotero.org) profile, a placeholder link is still generated but might not be useful.
+    Copy (www.zotero.org) links to the clipboard for each selected item.
+    If you have a (www.zotero.org) profile, following such a link will open the page for the corresponding item in profile on (www.zotero.org).
+    If you do not have a (www.zotero.org) profile, a placeholder link is still generated but might not be useful.
 
 * __Create book section:__
-	Create a book section item from the currently selected book item.
+    Create a book section item from the currently selected book item.
 
-	The new item is created by duplicating the book item and changing its type to book section.
-	Author entries for the book item are converted to "book author" entries for the new book section item.
-	The new book section item is added as a related item to the original book item.
-	Finally, the title textbox for the new item is focused so that a new title for the book section may be entered.
+    The new item is created by duplicating the book item and changing its type to book section.
+    Author entries for the book item are converted to "book author" entries for the new book section item.
+    The new book section item is added as a related item to the original book item.
+    Finally, the title textbox for the new item is focused so that a new title for the book section may be entered.
 
-	This function only works when a single book item is selected.
-	Note that some fields (number of pages and short title, as of late 2014) apply only to book items and not book section items.
-	There is no prompt to confirm this loss of fields from the created book section item.
+    This function only works when a single book item is selected.
+    Note that some fields (number of pages and short title, as of late 2014) apply only to book items and not book section items.
+    There is no prompt to confirm this loss of fields from the created book section item.
 
 * __Create book item:__
     Create a book item from teh currently selected book section item.
@@ -86,6 +85,32 @@ In the Zutilo preferences (accessed from the same menu as Zotero's preferences),
 * __Relocate child items:__
     Move all items stored in Zutilo's internal clipboard (put there by the "Copy child items" function) to the currently selected item.
 
+* __Copy item fields:__
+    Copies all source-item metadata fields to the clipboard.
+    The data copied is all data visible in the right panel only (not tags, not notes).
+
+* __Paste into empty item fields:__
+    (‘Paste-into-empty’) paste where source has value and target has none/empty.
+    Authors from the source are merged in even if the target already has authors.
+
+* __Paste non-empty item fields__
+    (‘Paste-non-empty’): paste where source has value.
+    Replaces authors if there is an author field in the pasted data.
+
+* __Paste all items fields__
+    (Paste-all): paste all fields from source, even if they are empty.
+
+### Collection menu functions
+
+* __Copy select collection link:__
+    Copy links of the form "zotero://select/library/collections/ITEM_ID" to the clipboard for the selected collection.
+    Following links from other applications can select the collection in the Zotero Standalone client but might require additional set up.
+
+* __Copy Zotero URI:__
+    Copy (www.zotero.org) link to the clipboard for the selected collection.
+    If you have a (www.zotero.org) profile, following such a link will open the page for the corresponding item in profile on (www.zotero.org).
+    If you do not have a (www.zotero.org) profile, a placeholder link is still generated but might not be useful.
+
 ### Navigating the UI and editing items via keyboard shortcuts
 
 Zutilo currently implements several keyboard shortcuts that are useful for editing Zotero items.
@@ -196,68 +221,6 @@ However, when the pane is shown, the thicker vertical divider ("splitter", "grip
 * __Open style editor:__
     Open the style editor window (normally accessible from the advanced section of Zotero's preferences).
 
-### Firefox browser shortcut functions
-
-The following shortcut functions are only available in the Zotero Firefox addon.
-
-* __Focus Zotero:__
-    Make Zotero visible if it is not.
-    Focus Zotero so that, e.g., `Tab` and the arrow keys work on the Zotero UI rather than the previously focused element of Firefox's UI.
-
-* __Hide Zotero:__
-    Hide Zotero if it was visible.
-
-* __Toggle Zotero:__
-    Show Zotero if it was not visible.
-    Otherwise hide Zotero.
-
-* __Save webpage as a Zotero item:__
-    Save the current page as a webpage item in Zotero.
-
-* __Save item:__
-    Add an item to the Zotero library based on the reference content of the current webpage (equivalent to clicking on the little page/book icon in the Firefox address bar).
-    In Zotero, the function that creates the item from the web page content is referred to as a `translator`.
-
-* __Save item without attachments:__
-    Create an item in a similar manner to "Save item" but __do not__ save attachment files for the item regardless of whether or not Zotero is set to save such attachments in its preferences.
-
-* __Save item with attachments:__
-    Create an item in a similar manner to "Save item" but __do__ save attachment files for the item regardless of whether or not Zotero is set to save such attachments in its preferences.
-
-* __Save item (reverse attachment pref):__
-    Create an item in a similar manner to "Save item" but only save attachments if Zotero is set not to save attachments in its preferences.
-
-* __Attach current page:__
-    Attach the current browser page to the selected Zotero item.
-    This function works best when the current web page is a PDF opened with Firefox's internal PDF viewer.
-
-### Firefox browser menu functions
-
-These functions add items to the Zotero "Save item" button's menu and to the Firefox right-click menu.
-Any of the menu items can be set to hidden in Zutilo's preferences.
-
-* __Attaching webpages and links to Zotero items:__
-    Zutilo adds context menu items to Firefox for attaching the current page or the current link target (if a link is selected in the current web page) to the item currently selected in Zotero.
-    Attaching the current web page is also available as a keyboard shortcut.
-
-    How the attachment is processed depends on the attachment method set in Zutilo's preferences.
-    If the method is 'Import', an imported attachment is created from the page/link.
-    If the method is 'Prompt for linked file', a file prompt appears to allow the user to specify a new file.
-    The page/link is saved to this file and then a linked file attachment (linked to the downloaded file) is created.
-    If the method is 'Prompt after first', an imported attachment is created if the selected item has no previous attachments (not counting webpage snapshot attachments).
-    Otherwise, the file prompt for creating a linked file attachment is shown.
-    If the shift key is pressed when the attachment function is activated, a prompt for a linked file is shown regardless of Zutilo's preference setting.
-    If the control key is pressed, the attachment is imported regardless of Zutilo's preference setting.
-
-* __Save item from a current webpage with or without attachments:__
-    Zutilo adds extra menu items to the context menu of Zotero's "Save item" button that save an item for the current page with or without extracting the page's associated PDF's and other files.
-    That is, if the "Automatically attach PDFs and other files" preference is selected in Zotero, Zutilo adds menu items for saving the item without attachments.
-    One menu item is created for each "Save to Zotero" method that applies to the current page.
-    If the preference is not selected, Zutilo adds menu items for saving an item with the attachments.
-
-    This function works by toggling the associated files preference in Zotero, creating the item, and then toggling the preference back to its original state.
-    Because Zotero translates pages asynchronously (and thus simultaneously), translations made with this function should be allowed to finish before starting normal page translations with Zotero (since otherwise the state of the "Associated files" preference will depend on the timing of the simultaneous translations).
-
 ### Better BibTeX functions
 
 The following functions are only available when [Better BibTeX](https://github.com/retorquere/zotero-better-bibtex) is installed (and only for Zotero version 5.0 or higher).
@@ -267,3 +230,5 @@ The following functions are only available when [Better BibTeX](https://github.c
 * __Unpin key:__ Unpin the key for the currently selected items.
 
 * __Force-refresh key:__ Force-refresh the key for the currently selected items.
+
+

i18n/en-US/readme/docs/USAGE.md

@@ -24,3 +24,101 @@ In Zutilo's preferences, these functions can be set to create either imported or
 Note that Zutilo's linked file attachment method triggers ZotFile, so, if ZotFile is set up to rename and move attachments, it will rename and move the ones saved this way no matter where you choose to save them with Zutilo's prompt.
 ZotFile has a "only ask if item has other attachments" option.
 This option works well with the Zutilo option to prompt for the location of attachments after the first.
+
+### Item field modification functions
+
+Zutilo provides several functions for copying and pasting item fields.
+The functions are meant to help completing metadata manually. Here are some use cases.
+
+#### Copy + Paste-into-empty: Completing records
+
+You have a series of PDFs, for which metadata is not recognised automatically, such as the chapters of a book.  
+You want to copy a set of metadata from the ‘source record’ to ‘target records’, without overwritten the information already available in the target records.
+
+1. You complete a ‘book section’ record for the first PDF (including editors, book title, publication year, etc).
+
+2. You then use Copy on this record, and Paste-into-empty onto all of the other records.
+  In this, you don’t need to worry about existing metadata (in the target records) as this is not overwritten.
+
+For example, if the target records already have titles and authors, those titles are kept while  editors, book title, publication year, etc is merged into the record.
+You can be sure that no information from the target records is lost.
+
+#### Copy + Paste-non-empty: Conforming records
+
+You have a series of PDFs for which metadata was recognised, such as papers contained in a journal volume.
+However, the name of the journal and the year of the volume are incorrect.
+
+1. Create a new journal paper record and enter the required information (name of the journal and year).
+
+2. Copy the record.
+
+3. Paste-non-empty the target records. This copies all non-empty fields from the source onto the target.
+
+As a result, the target records now all have the same Journal name and the same name (irrespective of the prior setting).
+
+#### Copying authors
+
+Copy+Paste-into-empty, Copy+Paste-non-empty and Copy+Paste-non-empty behave differently with regard to copying authors.
+
+* Copy+Paste-into-empty merges additional authors: Authors present in the source are added to the target.
+
+* Copy+Paste-non-empty replaces authors: Authors present in the source replace authors present in the target.
+In other words, the authors in the target are removed, and the authors from the source are added to the target.
+
+* Copy+Paste-all replaces authors; if the author field in the source is empty, then authors in the target are also cleared.
+
+The above option offer some likely scenarios, while keeping the number of paste-options to just three.
+Three examples which aren’t covered are
+
+1.  Completing records but not adding to authors.
+  To do this, duplicate the source record, remove the authors and then do a Paste-into-empty.
+
+2. Conforming records but not replacing authors.
+  To do this, duplicate the source record, remove the authors and then do a Paste-non-empty.
+
+3. Conforming records but merging authors.
+  To do this, duplicate the source record, remove the authors and then do a Paste-non-empty.
+Then copy the original source record, and do a Paste-into-empty.
+
+#### Copy + Paste-all: Copying item metadata between libraries
+
+If you are using copy + Paste-all, in sequence and onto the same item type, you are setting all source fields to the target (in a sense, duplicating the item).
+A use case for this is this is to easily sync items across two libraries.
+You have an item with correct metadata in one library, but with incorrect metadata in another library.
+Copy + Paste-all command copies all metadata from the item in one library onto the other.
+It updates fields on the target from the source.
+This also clears all fields in the target that are empty in the source.
+
+1. An item was copied from library A to B.
+  The metadata in A is subsequently corrected, and now needs to be copied onto the target item in library B.
+
+2. Copy the source item in library A
+
+3. Paste-all onto the target item in library B
+
+4. The metadata of the target item is now identical to the source item.
+
+Note that effectively Copy+Paste-all is similar to a duplicate.
+However, in some circumstances it’s easier to do.
+
+* For example, between libraries you’d first have to duplicate, then drag the item, then move attachments in the new library.
+  Creation time would also not be preserved.
+
+* Suppose you create one item, you duplicate it.
+  You move all the PDFs to the duplicates as needed.
+Now you notice a mistake (involving an empty field, e.g. moving Series to Series Title, while clearing Series).
+You just correct the original record, and use Paste-all.
+The Series filled is cleared, and Series TItle is filled.
+
+#### Copy + edit + Paste-all: Clearing certain item fields in a large number of records
+
+You are creating a public library B from a library A.
+In this process, you want to clear some fields from a set of items in library B.
+For example, you may wish to remove a set of archive locations, or extras, or similar.
+
+1. Create a blank item (of the same type), copy it.
+
+2. Edit the JSON on the clipboard to keep only fields to be cleared.
+
+3. Then use Paste-all to clear those fields in a number of source items.
+