Skip to content

Commit

Permalink
Readme update
Browse files Browse the repository at this point in the history
  • Loading branch information
Pierpaolo Sichera authored and Pierpaolo Sichera committed Dec 21, 2023
1 parent a979fe9 commit 7384c0d
Show file tree
Hide file tree
Showing 2 changed files with 128 additions and 1 deletion.
1 change: 1 addition & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
@@ -1,2 +1,3 @@

.DS_Store
README_images/Thumbs.db
128 changes: 127 additions & 1 deletion README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ NormaTEI è progettato principalmente per due utilizzi:
- controllo dell'uniformità di codifica: quando un'edizione XML/TEI è formata da più file, NormaTEI permette di controllarli in maniera organica, permettendo di individuare facilmente errori o scelte di codifica difformi;
- analisi della codifica: ricerche personalizzate e complesse sul corpus selezionato.
Il nome "Norma" richiama sia l'operazione per cui il software è stato sviluppato ("normalizzazione") che la più famosa opera di Vincenzo Bellini: NormaTEI è stato sviluppato infatti durante la realizzazione di Bellini Digital Correspondence, © Cnr Edizioni, 2023 ISBN: 978-88-8080-562-5 (edizione elettronica).
[Bellini Digital Correspondence, © Cnr Edizioni, 2023 ISBN: 978-88-8080-562-5 (edizione elettronica)](http://bellinicorrespondence.cnr.it "Bellini Digital Correspondence, © Cnr Edizioni, 2023 ISBN: 978-88-8080-562-5 (edizione elettronica)")
[Bellini Digital Correspondence, © Cnr Edizioni, 2023 ISBN: 978-88-8080-562-5 -edizione elettronica-](http://bellinicorrespondence.cnr.it)

## Ambiente
NormaTEI è stato sviluppato utilizzando 4D (https://www.4d.com/).
Expand Down Expand Up @@ -125,3 +125,129 @@ A questo punto è possibile effettuare una nuova ricerca sull'intero corpus oppu



# NormaTEI
NormaTEI is software for analyzing the content of one or more XML files.
NormaTEI is designed mainly for two uses:
- control of coding uniformity: when an XML/TEI edition is made up of multiple files, NormaTEI allows you to control them in an organic way, allowing you to easily identify errors or different coding choices;
- coding analysis: personalized and complex searches on the selected corpus.
The name "Norma" recalls both the operation for which the software was developed ("normalization") and the most famous work of Vincenzo Bellini: NormaTEI was in fact developed during the creation of Bellini Digital Correspondence, © Cnr Edizioni, 2023 ISBN : 978-88-8080-562-5 (electronic edition).
[Bellini Digital Correspondence, © Cnr Edizioni, 2023 ISBN: 978-88-8080-562-5 -electronic edition-](http://bellinicorrespondence.cnr.it)

## Environment
NormaTEI was developed using 4D (https://www.4d.com/).
Among the many features of this platform, native XML support with the Apache Foundation's Xerces library and access to the structure of an XML via the DOM (Document Object Model) standard have been exploited.
NormaTEI is compatible with Windows 10 – Windows 11 Windows Server 2012 R2 – Windows Server 2022 - macOS Big Sur (11) – macOS Ventura (13) (the latest releases for each version).

## Installation
To use NormaTEI:

### Windows
- download the Windows folder (downloading the entire repository or downloading the single folder via download services or software);
- extract the compressed files to obtain a zip file that you can extract to the folder you prefer and then run the NormaTEI.exe file.

### MacOSX
- go to "System Settings -> Privacy and Security" and check that the "Everywhere" option is enabled. If the "Everywhere" item is not present, you can enable it with this command given by Terminal:


```
sudo spctl --master-disable
```

- download the MacOSX folder (downloading the entire repository or downloading the single folder via download services or software);
- extract the compressed files to obtain a zip file that you can extract to the folder you prefer and then run the NormaTEI.app file;
- note (1): if you tried to open NormaTEI.app before going to "Privacy and security", the operating system may have returned an error, preventing the application from opening. In this case, delete the file and download and extract it again;
- note (2): to enable Gatekeeper again (if you have deactivated it) just give the same command by inserting the word enable:


```
sudo spctl --master-enable
```

## Instructions for use
NormaTEI offers two search modes:
- Standard: For simple searches, quickly find coding errors;
- Advanced: for in-depth analysis and evaluation of corpuses.

## Standard usage
At the first start a window for creating the data file may appear.
![Create a new data file](https://github.com/pierpaolosicera/NormaTEI/blob/main/README_images/01_NewDataFile.png)
Choose "Create" and save it wherever you want, NormaTEI will remember the path used.

### Corpus import
![Corpus import](https://github.com/pierpaolosicera/NormaTEI/blob/main/README_images/02_Open.gif)
In the launch window click on "Change..." to choose the folder containing the XML files, then press the "Import and analyze" button.
If you have already imported files, you can view the results without performing a new import with the "Open already uploaded files" button below.

### Research
![Simple search](https://github.com/pierpaolosicera/NormaTEI/blob/main/README_images/03_SimpleSearch.gif)
At the end of the chosen operation, NormaTEI will show the data, generating a list that lists:
- the file where that tag is present;
- the complete route;
- the tag;
- the value of that tag;
- the attributes of that tag;
- the values of the attributes;
- the unique path.
By "unique path" we mean attributing a unique identifier to each path, adding a numeric code of the type "[N]" to each path tag. For example "/TEI[1]/text[3]/body[2]/" indicates that body is the second child of the text tag which is the third child of the TEI tag which is the first child of the root.
The total number of results compared to the corpus examined is shown at the top left.
The results show:
- one line for each attribute of a tag: therefore if a tag has three attributes the list shows three lines, one for each attribute;
- a row with a value in the Tag column and no value in the Attribute column if the tag has no attributes.
It is possible to carry out searches by entering for each column a part of the text to be searched for in the yellow boxes at the top.
By clicking on the border between the column headers you can resize them.
If a tag has no attributes, a row with empty attribute data is shown. If a tag has an attribute it is shown with its value. If a tag has multiple attributes, one row is shown for each attribute.
The number of distinct values for each column is shown at the bottom.

### Counting
![Count per attribute](https://github.com/pierpaolosicera/NormaTEI/blob/main/README_images/04_Count.gif)
The "Count" button allows you to go to a summary window with respect to the data displayed.
The following are displayed:
- the metric on which the counting is performed (the columns of the search window);
- the total number of occurrences of that phenomenon;
- in how many files is that phenomenon present at least once;
- the files in which that phenomenon is present/absent (if the line has a green background those shown are the corpus files where that phenomenon is not present, if the line has a red background they are the corpus files where that phenomenon is found) ;

![Count by tag](https://github.com/pierpaolosicera/NormaTEI/blob/main/README_images/05_CountAll.gif)
Counting can be done by attribute or tag. Example: for the tag
```xml


<ab n="ab_02" next="#LL1.10_ab_01_1v" part="I" rend="first_line_indented" type="parag" xml:id="LL1.10_ab_01_1r">


```

counting on the "Tag" metric:
- if the counting is carried out by Attribute, the value of ab is 5 (how many attributes are present in this tag);
- if the counting is done by Tag, the value of ab is 1 (because ab is a single tag).

## Advanced usage
![Advanced search](https://github.com/pierpaolosichera/NormaTEI/blob/main/README_images/06_AdvancedSearch.gif)
By clicking on "Advanced" at the top right you can activate the advanced search window.
Above the search string you can choose the criterion to apply to the search string:
- Contains: the string is contained in the field (case insensitive);
- Starts with: the string is found in the initial part of the field;
- Ends with: the string is found in the final part of the field;
- Exact: the exact value of the string;
- Does not contain: the string nin is present in the field;
- Match RegEx: the search string is evaluated as a regular expression.
![Advanced search](https://github.com/pierpaolosichera/NormaTEI/blob/main/README_images/07_AdvancedSearchExample1)
Here too it is possible to activate the counting function to analyze the results.

### Search on subsets of the corpus
![Use results](https://github.com/pierpaolosicera/NormaTEI/blob/main/README_images/08_UseResults.gif)
By clicking on the "Use" button you can copy the search results in the lower part of the window for later use:
- What I use:
- The selection: uses the rows found
- Column values: takes all the rows of the corpus that have that value in that column. The most classic case is the one in which I have searched for where a certain characteristic is present in my corpus and I would like to carry out subsequent searches only on those files: in this case I will choose the values in the "File" column.

- What I do:
- Add: the results are added to the results in the lower part of the window;
- Remove: the results are removed from the results in the lower part of the window;
- Get common: results common to those already present in the lower part of the window are selected;
- New selection: the selected results are used, removing any already present in the lower part of the window.

![Reuse results](https://github.com/pierpaolosicera/NormaTEI/blob/main/README_images/09_SearchResults.gif)
At this point it is possible to carry out a new search on the entire corpus or by pressing "Search among results" a search can be carried out among the data selected in the lower part of the window.
You can also count the lines displayed at the Top or Bottom of the window.
![Count advanced results](https://github.com/pierpaolosichera/NormaTEI/blob/main/README_images/10_SearchResultsCount.gif)

0 comments on commit 7384c0d

Please sign in to comment.