Utente:Alex brollo/BAT man

Da Wikisource.
Jump to navigation Jump to search

Stiamo parlando di Batman?

Adam West as Batman.jpg


No! Si tratta solo della pagina man del tool BAT (Big Anonymous Tool) :-)

Come nasce[modifica]

Essendo passato a fatica dalla fase "non ci capisco niente" all'entusiasmo "comincio a capire qualcosa" in js, jQuery et al, ho fattivamente contribuito a rendere it.source una specie di giungla indistricabile di tool incrociati e il suo namespace global una specie di bazaaar levantino popolato di strani personaggi. @Ricordisamoa mi aveva messo in guardia... e in effetti il disastro annunciato si è verificato. Sono bastate alcune modifiche centrali del meccanismo del caricamento dei gadget per far collassare il sistema.

Stavo per dimissionarmi da apprendista stregone, quando provvidenzialmente @C.R. ha lanciato un invito a lavorare su m,ul.source per dare una spintarella al progetto nap.source, invito che ho accolto approfittando dell'opportunità di ricominciare daccapo riscrivendo tutto in uno script che avrebbe dovuto essere personale, usando i mattoni delle rovine per costruire un'altra cosa del tutto diversa: il BAT, appunto. Lo sventato tentativo ha avuto successo, qualche altro coraggioso utente ha usato il BAT, e quindi ho scritto la pagina mul:User:Alex brollo/BAT man.

Recentemente (primavera 2016) sono rientrato su it.source, portandomi dietro il tool che è multiprogetto; nelle ultime settimane l'ho stressato, migliorato, e quindi mi sono deciso a pubblicizzarlo un po' e ho cominciato ad aggiornare la pagina. Alex brollo (disc.) 23:40, 5 mag 2016 (CEST)

Avviso preliminare[modifica]

Nascendo come tool personale, il BAT è stato testato e modellato sull'ambiente e sulle abitudini di edit di un solo utente:

  • sistema operativo: Windows
  • browser: Chrome
  • usi e costumi di edit: largo uso di Trova & sostituisci con memoRegex

Sarà fatto uno sforzo di generalizzazione, ma non potrà essere completo.

L'idea generale[modifica]

Il cuore di BAT è lo script mul:User:Alex brollo/common.js che può essere attivato da chiunque su qualunque progetto con una singola riga di codice nella propria pagina Utente:NomeUtente/common.js ; con questa riga di codice:

  • mw.loader.load('//wikisource.org/w/index.php?title=User:Alex brollo/common.js&action=raw&ctype=text/javascript');

Produce una serie di bottoni del tutto analoghi, nell'aspetto, a quelli che da tempo su it.source vengono chiamati "la bottoniera"; il tool infatti nasce come evoluzione della bottoniera, adattata ad un ambiente con pochissimi tool e lavorando come "utente semplice".

Il tool può essere opzionalmente personalizzato dall'utente utilizzando una sottopagina (testuale) locale opzionale della propria pagina utente , che deve chiamarsi PersonalButtons, questa è la mia:

Essendo una sottopagina testuale della pagina utente, può essere modificata da qualsiasi utente - cosa indispensabile per darsi una mano fra utenti non Amministratori/sysop.

Cenni sulla struttura dello script (nota tecnica)[modifica]

Lo script mul:User:Alex brollo/common.js è costituito da un'unica grossa (Big) funzione anonima (Anonymous Tool), senza dipendenze esterne, con la struttura di una iffy. Espone (tranne errori & omissioni) nel namespace globale (opzionalmente; per permettermi il controllo di cosa avviene al suo interno) un unico oggetto, chiamato alex. :-). Interagisce con localStorage dove ficca ciò che è bene venga ricordato passando da pagina a pagina.

Attenzione
non possono essere esclusi conflitti con altri gadget o script personali, soprattutto su it.source dove il software è un po' movimentato. Per evitare cefalee al momento della prova, è molto opportuno disattivare tutti i gadget di Preferenze->Accessori, provare a fondo il tool, e poi riattivare cautamente i gadget tenendo gli occhi aperti per eventuali anomalie.
Non sarebbe male, verificata la compatibilità, aggiungere una piccola annotazione/un piccolo simbolo nella descrizione dei gadget per certificare la compatibilità. Va certamente disattivato Bottoniera e Raccolta dei giocattoli, e in genere tutti i gadget che richiedono l'attivazione del gadget-libreria common.js.

La struttura di PersonalButtons[modifica]

La pagina PersonalButtons è costituita semplicemente da una serie di righe di testo, ognuna delle quali crea un bottone sul fondo dello schermo; la sequenza di righe è inserita in un tag pre.

diacritici, es, Mostra/nascondi diacritici *Alt+0*,diacriticiToggle
postOCR, es, esegue postOCR *Alt+7*,postOCR
... 

Vi sono due tipi di righe, a quattro e a sei elementi separati da virgole:

diacritici, es, Mostra/nascondi diacritici *Alt+0*,diacriticiToggle
...
Sc, es,Applica il template SmallCaps (maiuscoletto), incapsula,{{Sc|,}}
... 

Il primo tipo è dedicato al richiamo di funzioni generiche senza parametri (che devono esistere all'interno di BAT come proprietà dell'oggetto alex o come proprietà dell'oggetto window); il secondo tipo è destinato alla sola, utile funzione incapsula (aggiunta di un prefisso e di un postfisso al testo selezionato); per questo secondo tipo speciale, prefisso e postfisso sono costituiti dal 5° e dal 6° elemento.

Il contenuto dei quattro elementi iniziali è il seguente:

  • testo nel bottone,action (non utilizzato), tooltip + shortcut opzionale, funzione chiamata

Unica regola sintattica aggiuntiva: nessuno dei quattro/sei elementi deve contenere il carattere virgola! La virgola infatti è usata come separatore.

I parametri delle righe PersonalButtons[modifica]

Il parametro 1 testo nel bottone
totalmente libero, determina il testo che compare all'interno del bottone; uno o più caratteri, qualsiasi carattere Unicode (anche speciale come

va bene). Suggerimento: usare il minor numero di caratteri possibile.

Il parametro 2 action
composto dall'unione delle iniziali delle azioni sulla pagina in cui il bottone dovrebbe comparire (e=edit (modifica), s=submit (anteprima), v=view (visualizazzione). Al momento inattivo, i bottoni compaiono comunque. Suggerimento: impostare a es quando si tratta di bottoni utili in fase di edit.
Il parametro 3 tooltip + shortcut opzionale
ha due funzioni; la prima di visualizzare una breve frase di aiuto (totalmente libera) che compare al passaggio del mouse sul bottone; la seconda di registrare e attivare uno shortcut (combinazione di tasti) a piacere, che attiveranno il bottone come se fosse stato "cliccato"; la combinazione va incorporata fra due asterischi. Suggerimento: prima di registrare una combinazione di tasti, verificare che la combinazione sia "libera" provandola in fase di edit nel browser; vanno scartate le combinazioni che fanno già qualcosa perchè proprie del browser o del software mediawiki.
Il parametro 4 funzione chiamata
nome della funzione da chiamare; la funzione deve essere una proprietà dell'oggetto windows (ossia una funzione globale) oppure una proprietà dell'oggetto alex.
I parametri 5 e 6
usati solo dalla funzione incapsula, sono le due stringhe prefisso-postfisso che vengono aggiunte al testo selezionato. Se non c'è alcun testo selezionato, le due stringhe, unite fra di loro, vengono inserite nella posizione del cursore. Il meccanismo funziona su qualsiasi textarea o campo testo di un form, (es. in header e footer di una pagina Page), e non solo nel box di edit principale.

Ok. Ma 'ste funzioni, che fanno...?[modifica]

Principio generale[modifica]

Tutte le funzioni di BAT hanno il solo scopo di rendere l'edit delle pagine Pagina più veloce e meno faticoso.

Le funzioni sono sostanzialmente di tre tipi:

  1. gruppo 1: semplici inserimenti di prefissi-suffissi al testo selezionato, attraverso la funzione incapsula, come i, c, larger ecc.;
  2. gruppo 2: funzioni che svolgono operazioni più complesse sul testo, come postOCR,parag,linee ecc;
  3. gruppo 3: funzioni che attivano tool o procedure complesse, ognuno dei quali richiede documentazione specifica, come diacritici, F&R e il gruppo di bottoni r..

Funzioni del gruppo 2[modifica]

  • autoRi Versione potenziata dell'autoRi (inserimento automatico di RigaIntestazione), inserisce un template RigaIntestazione nell'header

ricavandolo da quello messo due pagine prima. Questa versione non soffre del difetto di considerare numero pagina il primo numero che trova; se in RigaIntestazione trova più di un numero, cerca di ragionare e di individuare quello giusto. Se non ci riesce, rinuncia :-) e inserisce il RigaIntestazione che ha trovato, tal quale.

Copia anche eventuale codice aggiuntivo dell'header, senza modificarlo.
Non riconosce i numeri romani (aimè). In caso di numerazione pagina romana, occorre modificare il numero a mano.
  • pt
Esattamente uguale al tool autoPt di it.source.
  • postOCR
Esegue poche semplici correzioni del testo, indipendenti dall'opera e dalla lingua. Converte gli apostrofi dattilografici ' in apostrofi tipografici ’, evitando però di modificare gli apostrofi che costituiscono marckup wiki o che sono contenuti dentro link, template, tag math.
Non modifica le spaziature adiacenti a punteggiatura, perchè le convenzioni variano da lingua a lingua (es. fr.source richiede uno spazio prima dei segni di punteggiatura costituiti da due simboli, come : e ;).
Riunisce le parole spezzate in due righe riconoscendole dai due caratteri trattino a fine riga - e ¬.
  • parag
Separa il testo in paragrafi aggiungendo una riga bianca sotto le righe che terminano con alcuni caratteri di punteggiatura (.!? ed alcuni altri). NON agisce nelle aree delimitate da tag poem; va quindi richiamato dopo aver delimitato le parti in versi inserendo nel testo i tag poem.
  • linee
Riunisce le righe di ogni paragrafo eliminando i caratteri a capo alla fine della riga. Rispetta la suddivisione in paragrafi, che deve essere sistemata, a mano o con parag, prima di lanciarlo. Non agisce all'interno del testo delimitato da poem, nè all'interno del codice di tabelle.
  • Mm
Agisce sul testo selezionato rendendo alternativamente i caratteri tutti maiuscoli o tutti minuscoli. In caso di miscela di caratteri maiuscoli e minuscoli, la prima trasformazione è in maiuscoli.
  • Rv
Elimina le righe vuote in un testo; agisce anche all'interno di poem. Ha lo scopo di "compattare" le linee di testo nelle circostanze in cui l'OCR crea righe vuote errate; particolarmente utile nei testi in versi.
Indenta la riga contenente il cursore, o tutte le righe comprese, anche parzialmente, da una selezione, inserendo in testa cinque spazi per ogni click. Utile nei testi in versi.
Deindenta (funzione inversa della precedente)
  • sect
Con un click, inserisce il codice <section begin=s1>...<section end=s1> attorno al testo precedente il cursore, e <section begin=s2>...<section end=s2> / attorno al testo seguente il cursore;non è necessaria alcuna selezione.
  • tabM
Eseguendo un copia-incolla da excel alla pagina, ogni riga viene copiata come una riga, con le celle separate da caratteri di tabulazione:
cella 1 riga 1	cella 2 riga 1
cella 1 riga 2	cella 2 riga 2

Selezionando le righe e pigiando tabM il testo copiaincollato viene tradotto in codice tabella wiki:

{|
|-
|cella 1 riga 1||cella 2 riga 1
|-
|cella 1 riga 2||cella 2 riga 2
|}

Il che in alcuni casi può salvare la vita :-)

  • app
Un buon OCR di una tabella viene reso come una sequenza di colonne. Nella semplice tabella esempio sopra, l'OCR risulterebbe:
cella 1 riga 1
cella 1 riga 2
cella 2 riga 1
cella 2 riga 2

Selezionando il testo della seconda colonna (elementi 3 e 4), cliccando app, portando il cursore a sinistra nella cella 1, cliccando di nuovo app le celle vengono ordinatamente appese (da cui app) a ciascuna riga:

cella 1 riga 1||cella 2 riga 1
cella 1 riga 2||cella 2 riga 2

Riselezionando e pigiando tabM si ottiene il codice wiki tabella:

{|
|-
|cella 1 riga 1||cella 2 riga 1
|-
|cella 1 riga 2||cella 2 riga 2
|}

Anche questo, in tabelle con centinaia di elementi, salva la vita. :-) :-)

  • appr
in alcuni casi l'OCR di una tabella fa una cosa diversa: presenta le celle in sequenze per riga e non per colonna. Nella solita tabella di esempio darebbe questo testo:
cella 1 riga 1
cella 2 riga 1
cella 3 riga 1
cella 1 riga 2
cella 2 riga 2
cella 3 riga 1

Selezionando le celle consecutive che costituiscono una riga della tabella (nell'esempio le prime tre) e premendo appr si ottiene:

cella 1 riga 1||cella 2 riga 1||cella 3 riga 1
cella 1 riga 2
cella 2 riga 2
cella 3 riga 2

Ovviamente occorre ripetere per le celle di ciascuna linea.

Funzioni del gruppo 3[modifica]

Lasciate ogni speranza voi ch'entrate (qui le cose si fanno complicate.... ma neanche tanto forse)

  • eiv Dalla modalità view, si apre un box di editing che permette la modifica della pagina senza entrare in modalità modifica - ossia, senza ricaricare la pagina. Sono attivi tutti i bottoni personali, e alcuni pulsanti aggiuntivi (per il SAL). E' anche possibile aprire un box di anteprima del risultato.
  • diacritici
    Screenshot non aggiornatissimo ma sostanzialmente dà l'idea
L'idea di base del tool è di modificare o aggiungere un diacritico (accenti vari, dieresi ecc) a qualsiasi carattere, precisamente a quello che precede il cursore (senza selezionarlo nemmeno). L'alternativa è, come ben sapete, quella di selezionare il carattere, viaggiare nella pagina, cercare quel carattere con quel determinato accento.... talora non trovarlo, andare nelle tabelle Unicode, cercare e cercare.... e alla fine magari non esiste.
Il tool invece divide il carattere base dall'eventuale diacritico, e agisce sul diacritico/sui diacritici, ricomponendo poi il carattere composito. Se il carattere composito non esiste come carattere Unicode, lo visualizza lo stesso, come combinazione di due caratteri distinti (uno normale, uno combining).
Esempio. Un carattere alieno, q combinato con ~, non lo trovate in unicode, ma... diacritici lo costruisce con un singolo click: . Allo stesso modo, con un click, si crea una cosa mai vista: o si può cambiare al volo tipo di accento da à a á.
Cliccate su diacritici, vi compare un boxetto draggabile; all'apertura è attiva la modalità REP (rimpiazzo), cliccando il REP diventa ADD (modalità aggiunta); mettete il cursore immediatamente dopo la lettera su cui volete operare, e fate dei test cliccando i vari diacritici su vari caratteri. Con la modalità REP potete cambiare al volo un diacritico (es. da à a â) ma anche aggiungerne uno se la lettera ne è priva (es. da e a è) maiuscole o minuscole (da S a Š); il primo diacritico è "vuoto" e quindi con REP il diacritico viene semplicemente rimpiazzato con niente (Ẍ a X); in modalità ADD invece il diacritico viene aggiunto alla lettera conservando eventuali diacritici già presenti (da Š a Š̤, tanto per fare un esempio esotico).
Con questo tool si entra nel magico mondo dei caratteri unicode combinanti, in vari casi (quando la "fusione" lettera+diacritico non esiste in Unicode) aspettatevi qualche stranezza (i caratteri sembrano uno e invece sono due o tre....)
PS: mi rifiuto fermamente di documentare cosa fa un click su CLOSE :-)
  • note+ e * note↑↓
Il tag ref prevede che il testo della nota sia inserito nella posizione della nota, all'interno del testo. Quando le note sono molte, o sono lunghe, la rilettura è difficilissima, perchè sulla pagina originale le note stanno a fondo pagina, e nel testo wiki sono sparpagliate e mescolate con il testo base.
Il bottone note↑↓ esegue la "magia" di riportare le note al loro posto se sono all'interno del testo, lasciando al loro posto dei "segnaposto" che per ora sono il codice nota; un secondo click le riporta al loro posto. Moolto comodo!
Non solo. Il bottone note+, se cliccato senza testo selezionato, inserisce nella posizione un marcatore nota; se invece c'è testo selezionato, aggiunge <ref>...</ref> attorno al testo selezionato. A che serve tutto ciò? Serve a inserire comodamente le note da un testo OCR; si inserisce un segnaposto per ogni nota nel testo, poi con calma si aggiunge i ref al testo di tutte le note a fondo pagina, poi si clicca note↑↓ e le note vanno al loro posto. Attenzione: se il numero di segnaposti è diverso dal numero delle note, lo script si ribella; è uno script precisino. ;-)
  • F&R
Il tool F&R
Un tool Find & replace (trova e sostituisci), scritto da Candalua e successivamente adattato come "motore" del tool memoRegex. Può essere usato sia per sostituzioni semplici di testo, che per sostituzioni regex.
Per quanto riguarda il check Ricorda, vedi sezione successiva.
Attenzione!
Il tool sostituisce tutte le occorrenze della stringa "Cerca" con la stringa "Sostituisci", sia in header, che nel corpo pagina, che nel footer, e non esiste un undo. Utente avvisato, mezzo salvato.
L'uso "non regex" è semplicissimo e intuitivo e non serve doc.
Per quanto riguarda le regex, attivate con "Espressione regolare", è un tema ostico, posso solo suggerire - anche a chi conosce questo vero e proprio linguaggio - il magnifico sito Online regex tester and debugging. Le particolarità del nostro "Trova e sostituisci" per le regex:
nel campo Cerca, mettere l'espressione regex senza i caratteri / iniziale e finale;
tener presente che è sempre attivo il modificatore g (sostituzione globale);
i due modificatori m (multilinea) e i (ignora maiuscole/minuscole) vanno impostati con i due check quando necessari;
il carattere a capo, se serve, va inserito come \n sia in cerca che in sostituisci.
ricordatevi che non c'è un undo!
  • r!!, r↓ e r=
Il tool F&R ha un'opzione "Ricorda questa sostituzione". Ok: ricordala, ma dove? come? Quando? E come "dimenticarla", se va dimenticata?
Le sostituzioni vengono ricordate in una speciale e recente "memoria del browser", che viene ficcata in qualche anfratto del disco rigido in cui il browser corre. Verranno ripescate usando lo stesso browser sullo stesso pc - altrimenti resteranno irragiungibili. Non solo: saranno ripescate solo al momento dell'apertura dello stesso sito da cui sono state memorizzate. Questa area di memorizzazione si chiama localStorage.
Ovviamente questo sistema di memorizzazione non basta. Occorre poter "travasare" i dati memorizzati in qualche zona in cui siano recuperabili anche da altri browser, e da altri pc; visto che siamo su wiki, è necessario che possano essere ripescati anche da altri utenti. I tre bottoni r servono proprio a memorizzare in maniera stabile i dati delle sostituzioni, in modo da poterli ripescare, da poterli condividere e anche da poterli modificare o cancellare "svuotando" la memoria. La pagina destinata alla memorizzazione è la Index talk riferita alla pagina pagina che si sta modificando; si scopre presto che ogni opera ha bisogno delle sue particolari regex. I bottoni sono attivi in qualsiasi pagina Pagina; non è necessario aprire la pagina Index talk.
r!! : esegue tutte le sostituzioni caricate in memoria sulla pagina aperta in modifica
r↓ : Salva le regex memorizzate nella pagina Index talk corrente.
r= : carica le regex memorizzate dalla pagina Index talk corrente.
L'argomento è piuttosto ostico, e la soluzione è tagliata con l'accetta; difficile fare tutto da soli, ma se un utente ha preparato una buona serie di sostituzioni, e l'ha memorizzata come si deve in Index talk, tutto si riduce a cliccare r= per "caricare" e a cliccare r!! (oppure Alt+9) per "lanciare".

Il prossimo passo[modifica]

Di tutti i tool, il più complesso è certamente memoRegex per le sue difficoltà "stratificate in più livelli". Il tool dovrebbe essere migliorato, soprattutto nella parte memorizzazione-recupero-modifica delle regex memorizzate. Già così com'è, però, con un po' di trucchi, fa cose notevoli; ma richiede una pagina apposita di suggerimenti, che sarà questa: User:Alex brollo/BAT man/memoRegex e che conterrà anche alcune "ricette pronte" da caricare (vi ricordo che caricando dei gruppi di regex con il pulsante r↑ queste si sommano in memoria).