RAJE: RAsh Javascript Editor
Gran parte di questa tesi è centrata sullo sviluppo di un editor HTML-based chiamato RAJE (RAsh Javascript Editor), che non è altri che un editor WYSIWYG (di questo tipo di editor si è discusso ampiamente nella ). Il formato su cui è basato è sì, HTML ma per la precisione utilizza un sotto insieme di elementi HTML, conosciuti con il nome di RASH ( ).
In questo capitolo spiegherò cos'è RAJE e le funzionalità concesse all'utente, successivamente descriverò il grado di compatibilità (ad ora versione 0.1.17) che ha con il formato RASH, esaltando i suoi punti di forza che sono inoltre il motivo per cui è stato creato.
Funzionalità
Tra le principali funzionalità che RAJE mette a disposizione ne troviamo alcune ovvie e universali, necessarie in un editor come la toolbar e il menù del software; Altre, invece, sono specifiche per il formato su cui è basata (per esempio il passaggio tra modalità preview e modalità editor). Parlerò anche riguardo all'editabilità dell'header che merita di avere una sezione tutta dedicata, poiché la gestione è diversa da quella del corpo dell'articolo. Per ultimo parlerò delle shortcuts segrete che ho implementato per velocizzare la scrittura.
Splash window
Un buon numero di editor, non unicamente text editor (come per esempio Android Studio e la sua welcome window mostrata in ), integrano come schermata iniziale una finestra comunemente conosciuta con il nome di splash window o welcome window. Durante lo sviluppo dell'editor ho notato quanto sia effettivamente necessaria una splash window, come schermata inizale per software che richiedono di modificare diversi progetti. RAJE, infatti, permette di modificare e creare articoli, un articolo effettivamente è una cartella con un file HTML e gli assets richiesti normalmente da ogni documento RASH. Naturalmente è ammissible pensare che ogni utente possa voler creare più di un articolo, infatti l'ideale su cui ho pensato di costruire RAJE permette di gestirne molteplici, semplicemente conoscendo il percorso assoluto della sua cartella.
La splash window di RAJE in è stata sviluppata seguendo uno schema molto simile alla
. Naturalmente sono presenti una lista di articoli precedentementi aperti: i famosi "articoli recenti", disposti in ordine dal più recente al meno recente. Per ogni elemento della lista sono state salvate informazioni importanti necessarie per visualizzare correttamente l'articolo. E' inoltre possibile eliminarlo dalla lista, magari se stiamo parlando di articoli obsoleti o rimossi dalla macchina. I progetti recenti non sono aggiornabili, se ho aperto l'articolo X e successivamente cambio la sua posizione in un'altra cartella, non sarò più in grado di utilizzare il suo "articolo recente" per aprirlo, e sarà obbligatorio cercare manualmente la sua cartella.
Nella splash sono presente 3 pulsanti (Figure 2). Il primo serve per creare un nuovo articolo scegliendo la cartella di destinazione e il nome con cui verrà conosciuto (non è possibile cambiarlo successivamente). L'apertura di un articolo creato precedentemente (o inviato da un altro utente) è correlata alla pressione del secondo bottone "Open RASH article". In questo caso è necessario avere fisicamente la cartella sulla propria macchina.
Infine il terzo bottone è qualcosa di molto più particolare, partendo da un URL di github di questo tipo https://github.com/{author}/{repository} contenente un articolo RASH, è possibile scaricarlo sulla propria macchina ed editarlo direttamente con RAJE. Descrivere questa modalità sarà l'obiettivo della section 3.3.2.
Toolbar ed elementi
Come anticipato RAJE è un editor HTML-based di tipo WYSIWYG, perciò esattamente come altri editor di questo tipo è dotato di una toolbar che racchiude una buona parte di azioni permesse sull'articolo, se non tutte almeno quelle più importanti. Per quanto riguarda questo importante componente, nella fase iniziale dello sviluppo, ho optato per uno stile minimale, riprendendo le guidelines grafiche di Bootstrap. Successivamente sarà mio compito rendere la toolbar molto più simile agli editor più famosi e commerciali.
In questa sezione il mio scopo è di dare una descrizione della toolbar con annessi screenshots.
Questa toolbar è composta da un insieme di bottoni raggruppati e divisi per categoria, seguendo le specifiche RASH è possibile notare la differenza tra le diverse categorie di elemento o azione che verrebbero applicate al documento, una volta che l'utente preme il corrispondente bottone. E' inoltre possibile evocare un tooltip che mostra il nome comune per riconoscere il bottone come visto in .
figure.In rifermento alla e partendo da sinistra verso destra troviamo i primi due bottoni: rispettivamente undo e redo. Il comportamento nascosto dietro questi speciali pulsanti è strettamente necessario per quanto riguarda la stesura di un documento. Non avendo essi a disposizione sarebbe molto più complesso e macchinoso redigere l'articolo, inoltre il tempo di correzzione di eventuali errori lieviterebbe. Quindi l'introduzione di queste preziose funzionalità è stata una scelta obbligata.
Il terzo e il quarto pulsante sono un altro grande classico dgli editor, cioè bold e italic. Possono rendere un testo selezionato in grassetto o in corsivo.
Dal quarto pulsante in poi troviamo invece dei comportamenti speciali che riguardano esclusivamente RASH, sempre nella categoria "inline" (comportamenti che vengono applicati solo a del testo), che sono: code, link, cross ref, quote, subscript e superscript . Tra i vari, degno di nota è quello relativo alle cross reference (raffigurato con l'icona dell'ancora) che mostra una finestra modale con cui poter scegliere esattamente a quale elemento referenziarsi, ed è inoltre possibile creare una nuova reference o footnote.
Il funzionamento particolare di alcuni di questi pulsanti permette il loro utilizzo solo se è presente una selezione estesa del testo, cioè almeno un carattere selezionato trascinando il cursore del mouse e tenendo premuto il tasto sinistro. Per esempio selezionando del testo.
figure.Il secondo gruppo comprende i "blocks" che nella documentazione ufficiale di RASH sono codeblock, blockquote, ordered list e unordered list.
L'elemento codeblock è molto importante per quanto riguarda semplici snippet di codice, è possibile dunque scrivere diverse righe di codice (anche in formato HTML) senza che esse vengano interpretate e mostrate come se fosse una pagina web, in altre parole tutto ciò che si trova compreso tra l'apertura e la chiusura del tag code è codice solo graficamente, ma è testo a tutti gli effetti.
Per quanto riguarda le citazioni, ci viene in aiuto il pulsante relativo all'elemento blockquote. E' possibile aggiungere una citazione che, diversamente al normale quote (che crea una citazione inline), si estende completamente per una riga. Citazioni di questo tipo sono molto importanti, anche per dare maggiore enfasi rispetto alle semplici citazioni inserite nel testo.
E' accettabile e quasi scontato decidere di voler inserire delle liste all'interno dell'articolo che si sta scrivendo, a questo proposito all'utente vengono in aiuto i pulsati delle liste. Quelle più utilizzate e popolari sono naturalmente quelle ordinate e non ordinate e possono essere utilizzati in contesti diversi, è necessario dare la possibilità ad ogni utente di poter inserire la lista che più è in linea con le sue volontà.
Tra i bottoni del blocco denominato "figure" troviamo table, figure e formula. Sempre seguendo le indicazioni scritte nella documentazione ufficiale di RASH si nota l'importanza dell'utilizzo di questi tre blocchi (considerati tra i principali per la scrittura di un articolo di ricerca).
Le tabelle vengono inserite insieme ad un piccolo bottone di configurazione, posizionato alla loro sinistra. E' possibile modificare la tabella grazie a questo pulsante e, tra le opzioni permesse troviamo la possibilità di ridimensionarla e di cambiare l'organizzazione della testata. Un'altra funzionalità molto importante, permessa da RASH ma non ancora implementata con RAJE (dei motivi ne parlerò maggiormente nella section 3.2.), è l'espansione delle celle o dell'intera colonna. Sarà una delle prime funzionalità che verranno implementate nelle release successive dell'editor.
L'inserimento, tramite il corrispondente bottone, delle immagini è affidato al secondo bottone del blocco: figure. Alla pressione sarà immediatamente visibile una finestra modale ( ) che permette di scegliere tra due modalità distinte di inserimento: da selezione di un file di immagine o dall'inserimento di un URL. Entrambi importano fisicamente l'immagine all'interno della cartella del progetto.
Uno dei bottoni più importanti è sicuramente quello per aggiungere una formula nella posizione selezionata. Questa azione avviene con l'invocazione di un semplice editor asciiMath, che a tutti gli effetti crea un ambiente in cui impostare e selezionare la formula che si vuole inserire. Ne parlerò in modo più approfondito nella Section 3.3.1. .
Ho programmato il dropdown "section" in modo che sia possibile aggiungere delle nuove sezioni come quelle speciali di abstract e acknowledgement oppure delle comuni sezioni. Le uniche sezioni speciali che possono essere aggiunte in questo modo sono quelle sopra citate. Se sono già state inserite all'interno del documento, la schermata si posizionerà esattamente all'inizio della sezione visualizzandone il contenuto. Altrimenti verrà eseguito l'inserimento vero e proprio nell'ordine concepito da RASH.
Ogni qual volta la posizione del caret cambia viene aggiornato il contenuto della lista nel dropdown in base alle possibili sezioni aggiungibili. Se per caso l'utente si trova all'interno di una sezione di primo livello, sarà possibile aggiungere sia un'altra sezione di primo livello, oppure una sottosezione come mostrato nel codice.
<section><h1>Sezione di primo livello</h1>[caret]
</section> E' molto importante ricordare che questo non è l'unico modo a disposizione dell'utente per aggiungere delle sezioni, ma è l'unica strada per aggiungere quelle di astract e acknowledgement (maggiori informazioni sulle shortcuts nella section 3.1.4)
Menu software
RAJE è un software quindi, come tale, è servito con un menù la cui implementazione è stata scelta a mia più totale discrezione. E' molto importante aggiungere che in base al sistema operativo dell'utente la visualizzazione può cambiare in modo considerevole, particolarmente passando da sistemi Unix al sistema operativo Windows. Per quanto riguarda questa sezione non mi metterò a spiegare passo passo ogni singolo pulsante che è possibile trovare all'interno dei dropdown dei menu, perchè tutt'ora il progetto, ed in particolare questo modulo, sta subendo un numero importante di modifiche. Il mio obiettivo è spiegare, correlando degli esempi, come più ho pensato di dividere e raggruppare i molteplici attori del menù.
Sinceramente non sono partito da una progettazione senza fondamenti, ma bensì ho ripreso alcune linee guida e consigli trovati tramite internet. In particolar modo ho preso molto spunto dalla composizione dei menù di alcuni software di editing, tra i cui Visual Studio Code, Atom text editor (che ho utilizzato durante lo sviluppo di questo progetto) e Open Office come mostrato in .
L'organizzazione che ho seguito è molto in linea con questo schema. Tralasciando il bottone con il nome del software, che è una delle caratteristiche visibile solo nei sistemi Unix, File e Modifica sono stati introdotti anche in RAJE.
File è necessario per lavorare con molteplici documenti, dona la possibilità di aprire una nuova finestra riguardo ad un altro articolo. Modifica invece racchiude un gran numero di azioni proprie di un editor: undo, redo, cut, paste e copy. Inoltre ritroviamo il pulsante del salvataggio del file e quelli delle modifiche dell'header.
Header
L'intestazione di un file RASH è composta di più elementi necessari a contestualizzare l'articolo per intero. Titolo e lista di autori sono naturalmente molto importanti per quanto riguarda documenti di stampo scientifico, ma in questo caso anche keywords e ACM subject categories.
Grazie a RASH è permesso avere articoli scritti da molteplici autori, per questo motivo ho programmato RAJE in modo da permettere l'inserimento, modifica e rimozione di autori. Tra le altre cose è ragionevole anche voler modificare l'ordine degli autori, azionando l'azione corrispondente dal menù software è possibile spostarli semplicemente grazie ad una tecnologia di Drag & Drop. Anche per quanto riguarda l'eliminazione di autori è necessario azionare il relativo comportamento dal menù.
Così come gli altri elementi che conpongono l'intestazione del documento, sono facilmente editabili grazie ad un doppio click del mouse sul relativo elemento. Ho scelto di restringere i permessi di modifica di questa parte cruciale perchè è strutturata in un modo abbastanza complesso rispetto al resto del documento, quindi anche solo una piccola modifica strutturale avrebbe precluso la possibilità di salvare (e successivamente renderizzare) il documento RASH correttamente. Inoltre il doppio click è un'azione molto banale ed è anche l'azione principale per esprimere la volontà di interagire con un elemento grafico oppure la modifica di un testo (vedi rinomina di file su Windows).
Categories e keyword di possono rendere modificabili sempre dopo l'evento di doppio click, l'unica differenza è che il comportamento è identico agli elementi di code inline: il tasto spazio inserisce uno space all'interno dell'elemento, mentre il tasto enter inserisce uno spazio dopo l'elemento (serve per indicare la fine della scrittura).
Il titolo solitamente è accompagnato da un sottotitolo. Se durante la scrittura del titolo si vuole inserire il sottotitolo, è semplicemente necessario premere il tasto enter.
Quindi per quanto riguarda l'header di un documento scientifico in formato RASH è possibile modificarlo con la più assoluta compatibilità. L'unico punto esclamativo da aggiungere è la diversa modalità di modifica rispetto al corpo dell'articolo, che gode di un grado di restrizione minore.
Shortcuts
In questa sotto sezione mi trovo a descrivere ed a creare la lista delle scorciatoie da tastiera che ho pensato di implementare. Le modalità di implementazione verranno spiegate in modo approfondito nella section 4.3.2. .
Tutte le successive scorciatoie con il carattere mod equivale a scrivere ctrl per windows e cmd per osx.
-
mod+sè il salvataggio in locale del file. Tutte le modifiche che vengono apportate al documento sono visualizzabili nel documento HTML sorgente. -
mod+shift+s è la push alla repository Github. Mostra una finestra modale per inserire il commento con cui verrà etichettata la modifica.
-
mod+c,mod+v emod+xrispettivamente copia, incolla e taglia. -
mod+zemod+shift+z sono le scorciatoie per le azioni di undo e redo. -
# enter permette di creare una nuova sezione. in base al numero di caratteri#si può scegliere la profondità della sezione -
* enter aggiunge una lista non ordinata.
-
1. enteraggiunge una lista ordinata. -
| enterinserisce l'elemento blockquote. -
` enterinserisce l'elemento codeblock.
Punti di forza
RAJE è stato creato per ovviare al problema di avere un editor WYSIWYG di articoli scientifici di ricerca strutturati in formato RASH, oltre che avere un luogo centralizzato accessibile a tutti dove salvare i documenti. Durante la presentazione di questa sezione sarà mi compito descrivere i punti di forza del progetto da me sviluppato.
Durante il periodo di sviluppo, insieme al mio Co-relatore di tesi abbiamo definito un ulteriore necessità, correlata all'accessibilità dei documenti (problema ampiamente dettagliato all'interno della Section 2), cioè un editor di formule matematiche con caratteri asciiMath che genera formule grazie al processore di MathJax.
Il secondo punto di forza che andrò a presentare è l'integrazione con Github, in particolare parlerò di come ho pensato di gestire l'interconnessione tra più autori dei documenti.
Mathjax and Mathml
A partire dalla release 0.6 di RASH, grazie al lavoro svolto dal mio collega Vincenzo Rubano (@falcon03), è possibile renderizzare formule con input asciiMath in un elemento renderizzato grazie alle librerie di MathJax.
Una sfida significativa di questo lavoro è stata introdurre un editor pensato per essere di facile utilizzo, con tutti gli strumenti a disposizione, così anche chi non è a conoscenza delle sequenze di tasti può comunque pensare di costruire una formula matematica. L'editor ( ) è anch'esso una finestra modale. Presenta una textbox per i caratteri ascii di input, e una schermata predisposta alla sua visualizzazione in tempo reale. Infatti un'altra sfida che mi sono preposto è stata la velocità di aggiornamento della formula, che avviene ad ogni carattere o set di caratteri inseriti.
Per chi non è a conoscenza della sintassi necessaria per inserire particolari simboli o funzioni, è sempre possibile avvalersi dei bottoni che ho pensato di aggiungere immediatamente sotto della textbox di input. La disposizione deglli elementi è stata pensata incrociando i dati presenti dalla sintassi di asciiMath e l'impostazione dell'editor di OpenOffice.
Matrimonio con Github
Come già accennato più volte in precedenza, RAJE è strettamente collegato ad un sistema simil-cloud in modo tale da semplificare la comunicazione e la condivisione degli articoli tra i vari Stakeholders dell'articolo (che, oltre agli autori, possono essere anche i reviewer incaricati di revisionare un articolo inviato per una conferenza).
Github è il più popolare network per progetti prevalentemente di stampo Open Source, conosciuto ed utilizzato da milioni di sviluppatori in tutto il mondo. Il cuore pulsante di Github è Git, il sistema di controllo di versione distribuito creato da Linus Torvald durante lo sviluppo del sistema operativo ad oggi conosciuto con il nome di Linux. Nei tempi moderni è diventato un must per gli "Open Source Developer" avere un profilo su Github. Non solo per per motivi di curriculum, ma anche per ricevere apprezzamenti o miglioramenti dei propri lavori. Ad ogni utente è permesso quindi di lavorare insieme a persone di tutto il mondo per costruire progetti sempre più completi e complessi con, come unico vincolo, conoscenza della lingua inglese. Tutti i testi sono interamente in lingua inglese.
Ma come mai un sistema potente come questo non è popolare anche per la condivisione per materiale testuale? Per rispondere a questa domanda è necessario sapere che Git è stato creato con l'obiettivo di condividere codice, e questo semplifica moltissimo le cose. Il codice deve essere interpretato da una macchina, quindi è necessario definire in modo corretto dove inizia e dove finisce ogni istruzione, questo perchè ogni macchina legge, comprende ed elabora una riga alla volta.
Se RASH fosse del semplicissimo testo, forse altre modalità di controllo di versione sarebbero state molto più adatte. Ma un documento RASH non è semplice testo, questi documenti sono in formato HTML; Grazie a questa piccola differenza possiamo dire che Github e RASH si sposano perfettamente l'uno alla causa dell'altro.
Dopo questa premessa posso iniziare a descrivere l'integrazione vera e propria tra l'editor e il network.
In questa sezione, dopo aver dato delle informazioni basiche su cosa sia Github, posso estendere il discorso iniziato nella section 3.1.1. descrivendo il comportamento dell'ultimo bottone della toolbar. Cliccandolo è possibile creare una nuova cartella nel percorso scelto, che sarà immediatamente riempita con il codice e gli assets dell'articolo corrispondente all'URL inserito dall'utente. E' a tutti gli effetti la stessa cosa di aprire un documento precedentemente creato, con la differenza che questa volta stiamo parlando della repository https://github.com/{author}/{repository}.
Per quello che riguarda la scrittura di un articolo, arriva il momento in cui un utente ha intenzione di salvare il contenuto online. Per fare ciò è necessario autenticarsi con il proprio profilo di Github. Questo tipo di richieste sono impossibili senza un'autenticazione che certifica l'identità dell'utente.
Tralasciando la modalità di autenticazione, o meglio lo sviluppo del modulo predisposto per l'autenticazione, l'utente ha la possibilità di salvare il documento online, sui server di Github. L'azione può essre eseguita con la scorciatoia mod+shift+s oppure tramite l'apposito pulsante nel menù del software. Verrà visualizzata una semplice modale che permette all'utente di etichettare l'insieme di modifiche sotto un unico commento. Ad upload avvenuto sarà visualizzato un messaggio di successo ,in modo non invasivo, sullo schermo. La cosiddetta push è stata eseuguita con successo!
La gestione di documenti condivisi richiede che tutti gli autori della repository siano costantemente aggiornati sull'ultima versione dell'articolo, per non cadere in conflitti di merging. Nella corrente versione di RASH questa funzionalità non è ancora stata introdotta, ma è un punto cruciale della gestione di sistemi distribuiti, sarà implementata a breve.
Quelle sopra elencate sono le motivazioni del perfetto connubio tra Github e RAJE, che per l'appunto è uno dei motivi per cui è nato quest'ultimo.