# 13 luty 2017
# Michał Marcińczuk <michal.marcinczuk@pwr.edu.pl>
# Wrocław University of Science and Technology

Niniejszy dokument zawiera instrukcję instalacji narzędzia oraz opis procedury 
generowania słownika zawierającego formy bazowe fraz i ich formy odmienione
na podstawie linków wewnętrznych z Wikipedii. Słownik generowany jest na podstawie
rozpakowanego zrzutu Wikipedii w formacie xml (plwiki-YYYYMMDD-pages-articles.xml).


==========
Instalacja
==========

1. Zależności

  a) narzędzie maca: http://nlp.pwr.wroc.pl/redmine/projects/libpltagger/wiki
  b) pakiet setuptools (Python)
  
2. Instalacja

  sudo python setup.py install  


===================
Etapy przetwarzania
===================
--------------------------------------
1. Ekstrakcja linków z dumpa Wikipedii
--------------------------------------
Na tym etapie zostaje sparsowany dump Wikipedii w celu wyciągnięcia treści 
linków wewnętrznych wikipedii. Efektem ubocznym jest zapisanie każdej strony 
z Wikipedii w osobnym pliku.

UWAGA: Ten etap jest bardzo czasochłonny i może potrwać kilka godzin.


Wywołanie:
-----------

  cat XML_WIKIPEDIA_DUMP | g419wikitools-extract -o PAGES_FOLDER -w LINKS_FILE

Gdzie:
  XML_WIKIPEDIA_DUMP — ścieżka do pliku zawierające dump Wikipedii,
  PAGES_FOLDER       — ścieżka do istniejącego katalogu, do którego 
                       zostanie zapisana treść stron wycągniętych z wikipedii,
  LINKS_FILE         — ścieżka do pliku, do którego zostaną zapisane treści 
                       linków wewnętrznych wikipedii

Przykład wywołania:
-------------------

  cat plwiki-20150116-pages-articles.xml | g419wikitools-extract -o /tmp/wikipedia -w /tmp/links.txt


Przykładowy wynik (zawartość pliku LINKS_FILE):
------------------------------------------------
język programowania
plik
system operacyjny|systemów operacyjnych
Unix|UNIX
tablica asocjacyjna|tablice asocjacyjne
Tekstowy typ danych|stringi
wyrażenie regularne|wyrażenia regularne
Alfred V. Aho|Alfreda V. Aho
Peter Weinberger|Petera Weinbergera
Brian Kernighan|Briana Kernighana
POSIX
System V|SVR4


--------------------------------------
2. Filtrowanie i czyszczenie linków 
--------------------------------------
Na tym etapie plik z treściami linków wygenerowany w poprzednim kroku 
zostaje poddany filtrowaniu. Zostają odrzucone linie, które:
— nie zawierają znaku "|", co oznacza, że treść odsyłacza ma dokładnie tą
  samą wartość co tytuł artykułu, do którego się odnosi.
— są odnośnikiem do plików multimedialnych, kategorii, np. zaczynających się od:
  Plik:,  Kategoria:, 


Wywołanie:
----------

  g419wikitools-links-filter -i LINKS_FILE -o FILTERED_FILE

Gdzie:
  LINKS_FILE    — lista treści linków, efekt działania poprzedniego kroku,
  FILTERED_FILE — lista przefiltrowanych linków z pliku wejściowego.

Przykład:
---------
  g419wikitools-links-filter -i /tmp/links.txt -o /tmp/links-filtered.txt


Przykładowy wynik (zawartość pliku FILTERED_FILE):
--------------------------------------------------
system operacyjny|systemów operacyjnych
Unix|UNIX
tablica asocjacyjna|tablice asocjacyjne
Tekstowy typ danych|stringi
wyrażenie regularne|wyrażenia regularne
Alfred V. Aho|Alfreda V. Aho
Peter Weinberger|Petera Weinbergera
Brian Kernighan|Briana Kernighana
System V|SVR4


--------------------------------------
3. Analiza linków
--------------------------------------
Na tym etapie lista przefiltrowanych linków poddawana jest analizie morfologiczno-
-ortograficznej, której zadaniem jest ustalenie, które treści linków stanowią
formy odmienione tych samych fraz, na przykład: 
— "system operacyjny|systemów operacyjnych" — para zawiera formy odmienione tej samej frazy,
— "Tekstowy typ danych|stringi" — para zawiera formy odmienione dwóch różnych fraz.

Lista wejściowa dzielona jest na następujące pliki:
A) wikilinks-difflen.txt — frazy mają różną liczbę tokenów,
B) wikilinks-samelen*    — frazy mają taką samą liczbę tokenów,
 1. wikilinks-samelen-textbase.txt         — każda para tokenów ma przynajmniej 
                                             jedną wspólną formę bazową,
 1.a) wikilinks-samelen-textbase-one.txt   — frazy zawierają po jednym tokenie,
 1.b) wikilinks-samelen-textbase-multi.txt — frazy zawierają więcej niż jeden token,
 2. wikilinks-samelen-rules.txt            — co najmniej jedna para tokenów nie została dopasowana
                                             przez formy bazowe, tylko przez zastosowanie reguł podmiany
                                             końcówek dla formy tekstowej.
 3. wikilinks-samelen-different.txt        — pozostałe frazy, które nie zostały dopasowane.


Sposób wywołania:
-----------------
  g419wikitools-links-analyze -i FILTERED_FILE -o LINKS_FOLDER

Gdzie:
  FILTERED_FILE — ścieżka do pliku z przefiltrowaną listą treści linków
                  (wynik działania poprzedniego etapu).
  LINKS_FOLDER  — ścieżka do katalogu, w który zostanie zapisany wynik analizy.

Przykład:
---------
  g419wikitools-links-analyze -i /tmp/links-filtered.txt -o /tmp/links


Format plików wyjściowych
-------------------------
Pliki wyjściowe zawierające pogrupowanie linki zawierają w pojedynczej linii
listę fraz będących formą odmienioną tej samej frazy. Formy oddzielone są 
znakiem tabulacji, a forma mianownikowa jest na początku linii, np.:

Franciszek Ksawery      Franciszek Ksawery      Franciszka Ksawerego    Franciszkiem Ksawerym
