Manuale Inglese about polygen-docs HOT 9 CLOSED

from polygen-docs.

@alivsespano,

ho iniziato a tradurre le parti mancanti in inglese, e quindi anche i termini che non apparivano prima nel documento.

Binding (forti, deboli, e sospensioni)

Se puoi dare un'occhiata alle sez. 2.0.10–2.0.11 per accertarti che la scelta dei termini è corretta:

https://htmlpreview.github.io/?https://github.com/tajmone/polygen-docs/blob/draftwork/docs-src/polygen-spec_EN.html#sec:binding

Ero indeciso su come tradurre il secondo di questi due paragrafi:

La produzione associata a Frutto viene sospesa e chiusa insieme all'ambiente corrente secondo le regole di scoping. Durante la generazione, alla prima occorrenza del simbolo Frutto in un ambiente discendente (od il medesimo, come nell'esempio) la produzione associata viene generata una sola volta nell'ambiente chiuso assieme ad essa ed il risultato, immodificabile, della generazione risposto nell'ambiente; ogni successiva occorrenza dello stesso non terminale produrrà sempre lo stesso risultato.

Si badi che la prima generazione avviene in un ambiente in cui il simbolo non terminale in questione è associato alla chiusura, non ancora ad una sospensione: in tal modo è possibile fare uso di ricorsione anche definendo binding forti.

Alla fine ho scelto questa traduzione:

Please note that during its first generation the non terminal is still associated to the closure of the environment where it's being generated, and not (yet) to its suspension: this allows the use of recursion in strong binding deinitions.

e scartato quest'altra:

Please note that the first generation of the non terminal occurs in an environment where the symbol is still associated to its closure, and not to its suspension: this allows the use of recursion in strong binding deinitions.

... ma alla fine non ero sicuro di quale delle due esprimesse meglio il concetto. (la difficoltà consiste nel giostrare nella stessa frase i riferimenti all'ambiente, alla sua chiusura ed alla sua sospensione, senza rendere la frase troppo criptica).

from polygen-docs.

from polygen-docs.

Ok. Riguarda solo i termini usati nell'inglese o anche nell'italiano?

"arricchire" l'ambiente

Non so mai bene come tradurre "arricchire l'ambiente". A volte ho usato "accrue the environment" (lett.: accrescere), altre "enrich the environemnt" (traducendo alla lettera). Nessuno dei due suona bene.

Eppure, sento che mi sfugge un qualche termine più appropriato al contesto; è come se l'avessi sulla punta della lingua ma continua a scivolarmi via.

Qualche idea?

from polygen-docs.

MI è tornato in mente: "populate the environment" — secondo me questo è il termine calzante per descrivere l'aggiunta di simboli all'ambiente. Ma se esistono già dei termini d'uso, ovviamente conviene rifarsi a quelli, però non ho trovato quali sono.

from polygen-docs.

from polygen-docs.

Bozza Inglese Terminata!

Ho appena terminato la revisione/traduzione del testo inglese — e quindi è ora passato alla Beta 1.

Voglio prendere una pausa e poi rileggerlo daccapo, per verificare errori di battitura e se alcune parti possono essere smussate.

Premesso che:

• Lo stile della mia traduzione dista quintillioni di anni luce da quello di Shakespear
• Il documento non vincerà un Pulitzer
• Il documento non assurgerà a stauts di "Stele di Rosetta" e madre di stile per tutti i manuali sul generis
• Ci saranno sicuremente errori di spelling ed anche alcuni abomini linguistici di varia natura

... ritengo comunque che si tratti di un lavoro decente. Alla domanda:

Una persona (magari non madre lingua inglese) che leggerà questo manuale, riuscirà a capire come funzionano le grammatiche Polygen?

la risposta è: Sì!

Credo anche che il testo sia abbastanza scorrevole, e di essere riuscito a smussare alcune parti arzigogolate, rendendole più fluide, e anche a stemperare un po' le parti fortemente tecniche.

Correzioni Binding?

Avevi accennato a delle correzioni che volevi fare riguardo alla terminologia dei binding.

Personalmente, trovo che le scelte attuali vadano bene:

• Closures: weak binding
• Suspensions: strong binding (o assignment)

Ovviamente: a meno che non siano tecnicamente sbagliate.

Comunque attendo tue istruzioni al riguardo.

E in ogni caso, prima di rendere definitivi i documenti attendo una tua conferma riguardo il testo inglese — a sto punto, farei che pubblicarli insieme, tanto l'inglese quanto l'italiano.

PS: — è stato un vero incubo! Odio tradurre...

from polygen-docs.

Concordo. Alla fine, l'importante è che il lettore comprenda il linguaggio (senza dover impazzire per raggiungere lo scopo).

Io mi prenderei qualche giorno di pausa, così tu hai il tempo di dare un'ultima rilettura ai documenti, e io di prendere le dovute distanze dal testo (ora come ora, sono troppo coinvolto nel testo per essere obiettivo) per poter fare una rilettura a tabula rasa.

Nel frattempo, colgo l'occasione per rimettere mano a un paio di progetti che ho lasciato in sospeso.

Dopodiché rileggo, ritocco eventuali refusi, e ripulisco i sorgenti markdown.

Documenti Finali: Nome e Versione

Se ricordo bene, i documenti finali avranno la versione 1.1.0.

Quanto ai nomi, riprendo quanto detto in #1, e propongo:

Creare una copia dei i documenti finali in:

archived/polygen-spec_en_1_1_0.html
archived/polygen-spec_it_1_1_0.html

... dove la cartella archived conterrà lo storico di ogni versione del documento, per ogni lingua.

E nella root, invece, una copia di entrmbi i documenti senza numero di versione:

polygen-spec.html
polygen-spec.html

... di modo che la root contenga sempre una copia dell'ultima release del documento, in ciascuna lingua.

Vedrò di crare uno script che possa eseguire queste operazioni in automatico, così in futuro basterà un click per aggiornare il tutto a dovere.

Sito GitHub Pages

Inoltre, come si era già accennato, potremmo attivare il sito di GitHub pages facendolo puntare alla cartella docs del repository, e lì includere una copia del documento in inglese, rinominata index.html, di modo che essa diventi un sito a pagina singola, visibile sul web.

(si dovrà solo aggiungere un file .nojekyll per disattivare Jekyll, il CMS di default di GitHub Pages, di modo che il sito sia in HTML statico.)

A tal fine vedrò anche di definire nello header YAML dei valori per i meta-tags HTML description e keywords, di modo che la pagina venga indicizzata a dovere.

from polygen-docs.

Ok, ho aggiornato il tutto e pubblicato (non mi sono ancora occupato del sito GitHub Pages, voglio rifletterci ancora sopra su come procedere).

Ho cancellato il branch "draftwork" — assicurati che anche la tua copia locale venga cancelleta, e che non lo ri-pushi sul repository per sbaglio.

from polygen-docs.