﻿======================================================================
ZiS-Nominare - Help
Replace text in files / rename files and folders
www.zis.it
----------------------------------------------------------------------------------------------------------------

1. WHAT THE PROGRAM DOES
----------------------------------------------------------------------------------------------------------------
ZiS-Nominare searches for a text and replaces it with another one. It works in three ways, one for each row with a "Preview" button in the Nominare tab:

A) "rename files / folders": renames the files and folders whose NAME contains the search text.
B) "replace text inside picked files": replaces the text INSIDE the files picked one by one.
C) "replace text inside files in picked folder": replaces the text INSIDE all the files of a folder.

Every operation takes two steps:
- PREVIEW: a simulation that shows what would change, without touching anything.
- APPLY PREVIEW: actually writes the changes shown to disk.

Typical use: renaming a project (e.g. "OldProject" -> "NewProject") both in the content of the files and in the names of files and folders.


2. THE WINDOW
----------------------------------------------------------------------------------------------------------------
At the first start, and every time the disclaimer changes, the program shows the Disclaimer and Licence Terms in a separate window before opening. To use the program, tick both boxes and press "Accept"; pressing "Decline", or closing the window, closes the program. The acceptance is recorded in ZiS-Nominare.ini.

The window has three tabs: Nominare (the working tab, described below), Info (this guide) and Disclaimer. The Exit button, at the top right, is always visible: it closes the program and saves the settings (the same happens when closing the window with the X).

Nominare tab:

- find: text to search for. Required, single line.
- replace with: text to put in its place. If left empty, the search text is simply deleted.

- case sensitive: when checked, upper and lower case are different ("Home" and "home" do not match); when unchecked, case is ignored (see section 6).
- recurse sub-dir: applies ONLY to operation C. When checked, files in subfolders are processed too; when unchecked, only the files in the chosen folder. Note: renaming (A) ALWAYS processes all subfolders, regardless of this option.
- include binary: when unchecked (recommended), files recognised as binary (programs, images, archives, Office documents, etc.) are skipped; when checked, they are processed too, with a real risk of damaging them.

- folder [...]: chooses the folder to work on (operations A and C).
- files [...]: chooses one or more files (operation B). In the selection dialog use Ctrl+Click to pick several files, or Shift+Click for a range. The full list of picked files appears in the box below.

- Preview: there is one for each operation (A, B, C); it simulates the operation and writes the result in the "preview / log:" box.
- Apply preview: executes the last Preview. It is enabled only after a Preview that found something to change.
- Messages: the text to the right of the buttons tells you what to do and the outcome of the last action.
- auto open log: if checked, after every Preview and every Apply the log file is opened with the default text editor.

Info tab:

- the box shows this guide;
- Open: opens this guide with the default text editor;
- www.zis.it: opens the website.

Disclaimer tab:

- the box shows the disclaimer;
- Open: opens the disclaimer with the default text editor.


3. HOW TO USE IT, STEP BY STEP
----------------------------------------------------------------------------------------------------------------
1. Make a BACKUP COPY of the files and folders to be changed: the changes cannot be undone by the program.
2. In the Nominare tab, type the text to search for in "find:" and the new text in "replace with:".
3. Set the options: case sensitive, recurse sub-dir, include binary.
4. Choose the target: for operations A and C use the [...] button next to "folder:"; for operation B use the [...] button next to "files:".
5. Press the "Preview" button on the row of the desired operation.
6. Read the result in the "preview / log:" box carefully.
7. If the result is what you want, press "Apply preview" and confirm with "Yes" (the default button of the confirmation request is "No").
8. Check the outcome at the end of the log: "done: X ok, Y failed". Any "FAILED" or "SKIPPED" lines show the items that were not changed.

To rename a whole project (content + names) run, in this order:
1) operation C (text inside the files of the folder): Preview + Apply;
2) operation A (names of files and folders): Preview + Apply.
If the renaming is done first and the name of the chosen folder changes too, the path shown in "folder:" no longer exists and must be selected again with [...].


4. HOW IT WORKS: RENAMING (operation A)
----------------------------------------------------------------------------------------------------------------
- It examines all the files and folders inside the chosen folder, at any depth, plus the chosen folder itself.
- The text is replaced only in the NAME of the item, in all its occurrences. The extension is part of the name: searching for "txt" would also change the ".txt" extension.
- Items are renamed from the deepest to the outermost (first the content, then the folder that contains it), so paths stay valid during the whole operation.
- If a file or folder with the new name already exists, the item is not touched and the log shows "SKIPPED (target exists)": nothing is overwritten.
- If the new name would be empty, the item is ignored.
- The Preview shows for each item its type ([file] or [dir]), the current name and the new name.


5. HOW IT WORKS: TEXT INSIDE FILES (operations B and C)
----------------------------------------------------------------------------------------------------------------
- Each file is read as it is, byte by byte, and its encoding is detected (UTF-16 is detected even without a BOM):
  UTF-8 (with or without BOM) and ANSI -> "utf8/ansi" in the log
  UTF-16 Little Endian -> "utf16le" in the log
  UTF-16 Big Endian -> "utf16be" in the log
- The "find:" and "replace with:" texts are converted to the same encoding as the file and the replacement is done at byte level: the rest of the file (BOM, line endings, other characters) stays identical.
- A file is considered binary if its first 1024 bytes contain null bytes that do not have the typical structure of UTF-16 text.
- The Preview lists, for each file that would change, the number of replacements, the encoding and the path. At the end there is a summary: files scanned, files to change, total replacements, files per encoding, binary files skipped and unreadable files.
- The new content of the files is computed during the Preview and kept in memory; "Apply preview" writes it to disk.


6. LIMITS AND WARNINGS
----------------------------------------------------------------------------------------------------------------
- NO UNDO: changes written to disk cannot be undone by the program. Always make a backup copy first.
- "Apply preview" writes exactly what was computed at the time of the Preview. If after the Preview you change "find:", "replace with:" or the options, or if the files are modified by other programs, run the Preview again before applying. Otherwise the previous version is applied and, for text inside files, any changes made in the meantime would be lost. Choosing a new folder or new files automatically cancels the current Preview.
- The text is matched literally: no wildcards (* ?), no regular expressions, no searches across several lines.
- Upper/lower case in the CONTENT of files: with "case sensitive" unchecked, case is ignored only for letters without accents (A-Z). Accented letters must match exactly ("È" and "è" are still different).
- ANSI files (non-UTF-8 text, typical of older Windows files): accented or special characters typed in "find:" and "replace with:" are converted to UTF-8, so they are not found and, if inserted, show up as wrong characters. With ANSI files use only unaccented letters, digits and common punctuation.
- Word, Excel and PDF documents, ZIP archives and the like: their text is usually compressed, so it is not found. Processing them with "include binary" can damage them.
- Renaming: "find:" and "replace with:" cannot contain the characters that Windows does not allow in names:  \ / : * ? " < > |  If they do, the rename Preview is blocked and a message shows the invalid characters. These characters can be used normally when replacing text inside files (operations B and C).
- Files open in other programs, or folders in use (for example open in a command prompt), can prevent writing or renaming. In that case "FAILED" lines appear in the log: close those programs and repeat Preview and Apply.
- With many files or large files the Preview can take time, and the window does not respond while processing: wait until it finishes. Searching without "case sensitive" is slower.
- The program writes its own files in the folder where it is located: put it in a folder with write permission (for example not in "C:\Program Files").


7. PROGRAM FILES (in the same folder as the executable)
----------------------------------------------------------------------------------------------------------------
- ZiS-Nominare.ini: settings (find, replace, folder and the four options), saved on exit and reloaded at startup, and the record of the acceptance of the disclaimer (version, date and time). The list of picked files is not saved. If this file is deleted, the acceptance window is shown again at the next start.
- ZiS-Nominare_log.txt: log of the last Preview and of the Apply, if any. It is cleared at every new Preview.
- ZiS-Nominare_help.txt: this guide, also shown in the Info tab.
- ZiS-Nominare_disclaimer.txt: the disclaimer shown in the acceptance window and in the Disclaimer tab.

======================================================================
