Ultimi Ritocchi Prima della Pubblicazione about polygen-docs HOT 58 CLOSED

from polygen-docs.

from polygen-docs.

Errata 2.4.1

In 2.4.1 Di simboli non terminali c'è una frase in cui si dev'essere perso un pezzo:

Per risolvere questo problema, che rappresenta un’istanza del più vasto problema dell’irregolarità della distribuzione delle probabilità in presenza, in generale, di sottoproduzioni, il linguaggio di operare l’unfolding di un simbolo non terminale:

L'ho corretta aggiungendovi "consente":

Per risolvere questo problema, che rappresenta un’istanza del più vasto problema dell’irregolarità della distribuzione delle probabilità in presenza, in generale, di sottoproduzioni, il linguaggio consente di operare l’unfolding di un simbolo non terminale:

basandomi sull'originale inglese:

In order to solve this problem, itself an instance of the dishomogeneity of probability distribution problem in case of subproductions, the language offers an operator for unfolding non-terminal symbols:

from polygen-docs.

Pronto a pubblicare

Ok, il lavoro tecnico per il manuale italiano è terminato. Attendo solo una tua conferma riguardo le correzioni menzionate qui sopra e in #2, e se magari hai voglia di rileggero.

Sono soddisfatto del risultato, ed il nuovo formato semplificherà eventuali manutenzioni future del documento, nonché eventuali traduzioni in altre lingue, e in futuro faciliterà anche garantire che il manuale sia sempre in versione HTML standard dato che tramite pandoc sarà possibile "ricompilare" il sorgente secondo gli ultimi dettami dell'HTML.

Appena mi dai il benestare, muovo tutti i sorgenti in master, mi sbarazzo della branch di lavoro e pubblico il manuale italiano sul repo di PolyGen.

Poi potrò creare una nuova branch di lavoro per iniziare la ristampa del manuale inglese.

from polygen-docs.

Gli do un'occhiata adesso.

from polygen-docs.

La storia del "circuito" in effetti è borderline :P
Ho scritto sia il Polygen che la sua documentazione che non avevo neanche 25 anni, usavo ancora strane perifrasi, abbi pazienza :)

from polygen-docs.

No prob, credimi ti capisco, so come sia stressante il lavoro di stesura delle documentazioni. In quel passaggio credo che il problema sia solo dovuto all'esempio precedente; entrambi generano loop infiniti, ma l'introduzione del nuovo termine "circuiti" nel secondo esempio finisce per catturare l'attenzione e ci si arrovella per capire la differenza.

Alla fine, mi par di capire che (al di là del numero di simboli coinvolti nel loop senza uscita) il problema è sempre lo stesso, ossia che si tratta di definizioni ricorsive dalle quali non vi è uscita.

from polygen-docs.

Non ho mai approfondito la conoscenza di Pandoc, ho delle domande:

1. i sorgenti dei doc sono i markdown ed il resto è artifatto di building?
2. cosa devo installare per poter buildare? Pandoc su Cygwin pare non ci sia.
3. il sottosistema di commenti (esempio: !comment{ FIXME -- poco chiaro}) è puramente in-source o c'è qualche tool esterno (visuale o meno) che li genera/gestisce?

from polygen-docs.

E comunque hai fatto un lavorone da paura. Senza quel manuale PolyGen sarebbe stato un programma miracoloso ma inaccessibile. L'ho usato per anni, l'avevo collegato al mio vecchio client postale per generare per ogni email un header ed un footer casuali. Poi con il passaggio a Win7 ho dovuto cambiare client postale, e Polygen ha iniziato a far le bizze.

Polygen è davvero un programma eccezionale, e per quante ricerche abbia fatto non ne ho trovati altri che lo eguaglino. Ovviamente, c'è il famoso Natural Language Toolkit (Python), ma è un libreria scientifica accademica enorme e difficile da usare. Per un uso dilettevole, ho trovato solo qualche chat-bot, ma nulla di eccezionale.

Esiste un remake di Polygen in Haskell, ma non è chiaro a che punto sia:

https://github.com/svoisen/hs_polygen

Non ci sono release binarie, e non è menzionata una release stable. Da un lato è molto promettente dato che Haskell è un bellissimo linguaggio, però credo che OCaml sia più memory-efficient e performante rispetto ad Haskell.

from polygen-docs.

Ti ringrazio per i complimenti. Ora contatto Svoisen e gli dico che se vuole può joinare il repo ufficiale di Polygen e parliamo del futuro tutti assieme, se fa piacere anche a te ed a lui.
Mi fa piacere avere un aiuto da parte della community e di persone come te, ed è anche un pretesto per me per tornare su polygen, ridargli una spolverata e magari finire anche l'update 2.0 che da anni ho in cantiere ma che non ho mai finito.

Per quanto riguarda OCaml vs Haskell, ovviamente Haskell è il re dei linguaggi, ma OCaml all'epoca in cui ho scritto Polygen era un meno research-oriented e più un linguaggio funzionale per scrivere programmi veri. Oggi però le cose sono cambiate: Haskell gode di ottima salute mentre OCaml, pur rimanendo il miglior ML, comincia ad accusare l'età. Non è più al passo coi tempi per quanto riguarda gli strumenti accessori (IDE, tool di building vari, librerie ecc) ed dà un po' una sensazione di "vecchio" e poco mantenuto. In realtà Leroy (il principale autore) è sempre attivo e molto in gamba, ma non è stato fortunato col suo linguaggio. Haskell ha una community enorme: non solo praticamente predomina l'intera scena della ricerca scientifica sui linguaggi, ma anche a livello di user base è messo bene. OCaml invece è praticamente un ML dimenticato, come F# ed altri.

In ogni caso, ci ripenso spesso se riscrivere Polygen in qualche altro linguaggio: potrei fare un rapidissimo porting in F#, che ha il vantaggio di essere basato su visual studio che è un buon IDE (il migliore se paragonato alla sola scena dei linguaggi funzionali!); oppure un porting in Haskell. Ma che senso avrebbe? OCaml è comunque supportato ed è più facile da capire di Haskell, meno estremo, meno difficile per chi non se ne intende di programmazione funzionale.
Ci penso spesso, ti dicevo, e mi piacerebbe aprire una discussione con te e quant'altri della community vogliano darmi una mano e/o una opinione in merito.

Per ora farei così: teniamo tutto così com'è, solamente lo faccio compilare e fixo 2-3 cosette. E ridiamo vita alla documentazione, raccogliamo le grammatiche ecc.
Insomma, facciamo un lavoro di consolidamento.
Dopodiché ci pensiamo a cosa fare per il futuro: anche una app Android sarebbe figa, ma non ci penso neanche di riscrivere Polygen in Java. Soprattutto l'analizzatore statico - più che non il generatore in sé -
diventerebbe un mare di codice ingestibile in qualsiasi linguaggio imperativo.

PS: se ti piacciono i linguaggi, guarda nel mio profilo github tra i miei altri progetti: ce n'è uno che si chiama Lw. E' un linguaggio funzionale general-purpose in fase di sviluppo di mia creazione. Se ami i linguaggi, i type system ecc potrebbe piacerti :)

from polygen-docs.

Sono d'accordo, coinvolgi più persone che puoi.

… anche una app Android sarebbe figa, ma non ci penso neanche di riscrivere Polygen in Java.

Varebbe la pena controllare i vari cross-compilatori Javascript (Emscripten, LLVM, etc.). Se non ricordo male, OCaml è uno dei linguaggi supportati per la cross-compilazione a Javascript, e questo lo renderebbe accessibile a quasi tutte le piattaforme.

Una cosa davvero bella sarebbe poter avere anche Polygen come libreria (statica o dinamica) per poterlo incorporare in altri programmi senza doverlo invocare esternamente. Questo renderebbe probabilmente più facile anche la cross compilazione a piattaforme cellulari, etc.

In passato esisteva una versione PolyGen per telefonin Window CE, ma il link è morto ora e non ho trovato altri riferimenti ad essa.

from polygen-docs.

La versione per Windows CE la do per dispersa, tanto comunque sarebbe inutilizzabile oggi.
La cosa che da anni pensavo di fare è esattamente quello che dicevi tu: fare una libreria con una semplice API per la generazione. Anche un servizio server sarebbe carino, cioè che polygen possa essere lanciato in modalità "listen": si apre una porta e resta in ascolto su un socket, così da poterlo usare come motore di generazione generico utilizzabile tramite una API a comandi.

from polygen-docs.

Secondo me, Tristano, è meglio confluire questo repo direttamente nel repo del Polygen.
Ci facciamo una directory doc e mettiamo lì dentro tutto questo.
E poi committiamo lì.

from polygen-docs.

Ah scusami, puoi rispondere alla 3 domande di sopra? Così capisco cosa devo fare per poter buildare la doc anche io

from polygen-docs.

No, troppi sorgenti e, soprattutto, la cartella dei tool si riempe di un sacco di binari terze-parti per la creazione dei documenti (e darebbe fastidio quando si cambia di branch e quella branch non ha lo stesso gitignore). Sarei per tenere più pulito il progetto Polygen, senza tutti sti sorgenti.

La mia idea era di creare qui una sottocartella con i soli documenti finali, e poi o:

1. incorporare la cartella come Git submodule (dovrebbe potersi fare, non ne sono sicuro); o
2. copiare i documenti "compilati" nell'altro repo.

La soluzine 1 consentirebbe di mantenere i documenti sempre aggiornati impostando il submodule di modo che sposti il puntatore automaticamente ogni volta che c'è un nuovo commit nella cartella dei documenti generati (qui).

Per la soluzione 2 basterbbe uno script locale che sincronizzi la cartella di questo progetto con quella di polygen.

from polygen-docs.

Conosci git e github meglio di me: la soluzione 1 mi piace, fammi vedere come si fa. Se ho capito bene è possibile dire che un progetto github è un sottomodulo di un altro?

from polygen-docs.

Se ho capito bene è possibile dire che un progetto github è un sottomodulo di un altro?

Sì, esatto. Come nel caso delle grammatiche che aveo incluso in polygen — nel mio progetto:

https://github.com/tajmone/Polygen

Se noti, la cartella grammars appare diversa: grammars @ c6d5ffc, accanto al nome c'è l'hash del commit a cui si referisce. E se clicchi sulla cartella finish sul repository delle grammatiche.

Praticamente, è un repository Git dentro un altro. Solo che tu decidi a quale commit puntare. Nel caso di API, può essere utile tenersi entro un range di versioni che garantisca la compatibilità. Nel caso di documenti, si può voler invece avere sempre la versione più aggiornata. Ci sono vari settaggi per controllare come gestire il puntatore.

I vantaggi sono ovvi: le grammatiche ed i documenti vengono stipati in un punto centrale, e tutti gli altri progetti che li usano verranno aggiornati automaticamente (o notificati, quanto meno). Questo semplifica la manutenzione ed evita la ridondanza degli sforzi.

Ma, ovviamente, nel tuo repository c'è una copia completa del progetto del submodule, e quindi anche se il progetto a cui punti dovesse sparire ne hai sempre una copia completa.

In teoria si dovrebbe poter includere anche solo una sottocartella del progetto — almeno lo spero, dato che è ciò che volevo fare in questo caso, importando solo la cartella dei documenti compilati. Mi documenterò su questo.

from polygen-docs.

Scusami, la mia risposta è andata persa (devo aver cliccato su Preview anziche Salva)...

Non ho mai approfondito la conoscenza di Pandoc, ho delle domande:

1. i sorgenti dei doc sono i markdown ed il resto è artifatto di building?
   cosa devo installare per poter buildare?

Nella cartella polygen-docs\docs-src\tools trovi un cript batch che scarica e dezippa tutti i binari richiesti (richede 7-Zip e cURL sul sistema). Sempre in quella cartella, c'è un README con instruzioni dettagliate. Ma basta lanciare lo script e fa tutto lui.

2. Pandoc su Cygwin pare non ci sia.

Qui trovi i precompilati per tutti i vari OS:

https://github.com/jgm/pandoc/releases

... ma lo script del punto 1 è la soluzione più comoda.

3. il sottosistema di commenti (esempio: !comment{ FIXME -- poco chiaro}) è puramente in-source o c'è qualche tool esterno (visuale o meno) che li genera/gestisce?

Fa parte della macro PP, un preprocessore che s'interpone tra il sorgente markdown e pandoc:

https://github.com/CDSoft/pp

PP offre potenti macro di default, e consente anche di crearne di proprie, ampliando i potenziali di markdown. Per esempio, mi interfaccio a Highlight, un tool esterno per colare la sintassi, tramite una macro PP che passa il blocco di codice nel suo parametro al tool esterno, e restituisce il risultato nel documento.

from polygen-docs.

L'unico problema con PP è che i binari precompilati per Windows sono disponibili solo in 64 bit; per chi avesse un PC a 32 bit toccherà compilarsi PP da Haskell.

from polygen-docs.

Mi sono documentato riguardo l'inclusione parziale dei submodules. In effetti, includere solo una cartella di un altro progetto è un po' complicato, ma comunque possibile con le versioni più recenti di Git.

Visto che la documentazione attuale è di soli due documenti, i quali sono perlopiù in forma definitiva, sarebbe più pratico usare uno script che copi i documenti da questo progetto alla cartella dei documenti su Polygen — se i documenti sono cambiati, Git li segnalerà come modificati, altrimenti no.

Siccome Git tiene conto solo dell'Hash dei file (e se ne frega della data di creazione e ultima modifica), direi che uno script è una buona soluzione.

In questo progetto, pensavo di creare nella root delle cartelle con il codice della lingua:

/en/
/it/

ecc.

in cui copiare le versioni "compilate" dei vari documenti, dalla cartella /docs-src/ alla cartella della corrispondente lingua.

Molto dipende se si deciderà di usare un sistema di nomi file regimentato, del tipo "Polyman_IT.html", "Polyman_EN.html", "Polyman_FR.html", ecc (cosa utile nella cartella di lavoro, ma non per forza in quella finale), oppure se adotteremo nomi file che riflettano il titolo, come "Manuale-Polygen.html", "Polygen-User-Guide.html". Nel secondo caso avremmo:

/en/Polygen-User-Guide.html
/it/Manuale-Polygen.html

... e questa disposizione dei file/documenti potrebbe essere replicata (tramite script di copia) in una cartella /documents/ nel repository Polygen — consiglio di non chiamare la cartella /docs/ perché su GitHub è una cartella speciale, ed è possibile usarla come cartella-sito: si può fare sì che i documenti markdown (ReST, Asciidoc, etc.) nella cartella docs vengano usati per generare i contenuti del sito GitHub Pages associato al progetto. Quindi si potrebbe avere un minisito per PolyGen senza dover ricorrere alla branch gh-pages (questa funzione del sito da docs è una nuova funzionalità abbastanza recente). Pensavo di lasciare aperta questa possibilità.

from polygen-docs.

Va bene, pazienza. Tanto saranno pochissime persone che hanno bisogno di buildare i doc.
By the way: lo script watch.sh usa il comando multiwatch, che in cygwin non esiste. Ho trovato watch per cygwin dentro il pacchetto procps-ng, ma non c'è multiwatch. Ti risulta?

from polygen-docs.

from polygen-docs.

Premetto che non conosco cygwin (e che cygwin è il motivo per cui non installo OCaml su Window).

Il multiwatch che uso qui è un package Node.js (probabilmente ispirato a un tool simile in ambienti Linux). Ti basta installare Node.js e multiwatch:

https://www.npmjs.com/package/multiwatch

from polygen-docs.

Io chiamerei il manuale qualcosa come Polygen-Man o Polygen-Refman, più il
suffisso IT o EN con l'underscore. Terrei regimentato il nome in tutte le
lingue.

Sì, anche a me piace. Allora se proponi il nome già adesso faccio che modificare il nome dei file generati nella cartella lavoro, così sono già a posto. L'attuale Polyman_IT.html è un po scarso. A me piace Polygen-Man_IT.html (etc), è più conciso e intuitivo.

Tanto questa branch di lavoro non la mergio in master, faccio un checkout della cartella di modo da non legare master a tutti sti commit e cambiamenti, e il giorno che cancello la branch di lavoro il database dell'indice si alleggerisce.

from polygen-docs.

Ah, la cartella tools non è in gitignore. E' voluto?

from polygen-docs.

Come no? Contiene un .gitgnore al suo interno (per ora, poi quando fondo il tutto in master magari muovo tutto nel .gitignore principale; ma adesso se faccio il checkout in master (in cui il gitignore è version controlled) finisce che mi vede quei binari come nuovi file untracked (a meno che, appunto, un gitignore nella cartella stessa lo impedisca)

from polygen-docs.

from polygen-docs.

Hai ragione tu, e torto io! A cause del .gitgnore nella cartella superiore, quell in "tools" era ignorato e non è stato pubblicato (ma localmente funzionava sul mio PC, perciò non me ne rendevo conto).

Ora ho aggiustato, fai il pull e si sistema... i file modificati dovrebbero diventare ignorati.

from polygen-docs.

Ho problemi a pushare per via del tuo commit. Un attimo che aggiusto la cosa.

from polygen-docs.

Ok, fatto.

from polygen-docs.

niente, continua ad ignorare il .gitignore. Devo capire perché.

from polygen-docs.

Risolto. I settaggi del .gitignore in "tools" erano tali che ignorava sé stesso (quindi, funzionava in locale ma non era tracciato da Git, e quindi non pubblicato).

Ora se aggiorni con un pull dovrebbe comparire, e tutti i binari risultare ignorati:

https://github.com/tajmone/polygen-docs/blob/draftwork/docs-src/tools/.gitignore

from polygen-docs.

Script Intuitivo?

Colgo l'occasione per chiederti cosa ne pensi dello script, è abbastanza intuitivo? So che è una toolchain abbastanza complessa, così ho pensato che questo script potesse semplificare la vita a potenziali traduttori e non scoraggiarli con instruzioni chilometriche.

Certo, devono pur sempre avere cURL e 7-Zip, ma almeno per quelle ho fornito dei link immediati.

Versione Finale Documento?

Altra domanda, una volta pronto, con che versione lo pubblichiamo?

Pensavo edizione v2.0 per chiarificare lo stacco dalle precedenti. Ma non è poi così necessario (ci sono anche le date), quindi v1.0 andrebbe anche bene. Che ne pensi?

from polygen-docs.

Resto in attesa di una tua conferma che il documento italiano è pronto per la prima release.

Appena confermi, tolgo i commenti di sviluppo, rinomino i file "Polygen-Man_IT.<ext>" e lo pubblico come 1.1.0 in master. A quel punto posso iniziare a lavorare al testo inglese (ho solo bisogno di pubblicare quello italiano in master prima, di modo da poter separare le bozze inglesi dal testo già pubblicato).

from polygen-docs.

Vai vai, rilasciali. Poi quando avrò finito il supporto per le cosette nuove lo aggiorniamo. Che dici, lo chiamiamo direttamente 1.1.0 o lo chiamiamo 1.0.6 per il momento e faccimao il version bump quando abbiamo anche la 1.1.0 del Folpygel?

from polygen-docs.

Secondo me associare l'edizione del manuale alla versione di PolyGen potrebbe causare confusione. Ho appositamente specificato accanto all'edizione del documento la version PolyGen a cui si rifà.

Inoltre, questo manuale riguarda la sintassi delle grammatiche, che potrebbe restare invariata indipendentemente dalla versione di PolyGen.

Per evitare confusioni e vincoli, ho scelto il termine "Edizione" apposta (anche se poi adotto lo schema vX.Y.Z, che è più informatico), e comunque la data è sempre riportata accanto all'edizione (e credo che questa sarà il riferimento per molti).

Che dici?

from polygen-docs.

Quanto sopra, anche in virtù del fatto che le edizioni in altre lingue potrebbero non sempre seguire strettamente quella italiana (p.es. qualcuno aggiunge qualcosa all'inglese, e ne incrementa la MINOR version, e nel frattempo qualc'un altro ha fatto lo stesso in quella italiana, ecc.)

Direi che la versione dell'edizione dovrebbe aiutare solo a capire se si ha quella più recente o meno, e dal numero di versione dovrebbe potersi intuire il grado di cambiamento (con MAJOR che indica cambiamenti non retro-compatibili, ossia nuove versioni di Polyge; MINOR indica nuove sezioni e contenuti, e PATCH modifiche minori, estetiche e correzioni di refusi).

from polygen-docs.

from polygen-docs.

consolidiamo un attimo cosa sono i numeri di versione del polygen ...

La definizione che hai riportato è in linea con SemVer, che è lo standard consigliato da GitHub (e in genere gli utenti GitHub tendono a presumere che lo schema di versione usato sia quello):

• https://semver.org/

Quindi direi che risulterà ovvio alla maggior parte degli utenti qui.

In linea teorica tutto questo inviterebbe a creare un documenti di
SPECIFICA del metalinguaggio con una sua numerazione (come si fa coi
linguaggi di programmazione) da tenere separata dalla versione del
programma (che sarebbe allineabile ad un compilatore).

Per esempio, potremmo chiamare PML (Polygen Meta Language) oppure XBNF
(eXtended Bakus-Naur Form) o un altro nome formale per il metalinguaggio e
fare un manuale per esso che si aggiorna solo quando ci sono novità di
specifica; e poi abbiamo un secondo manuale per il polygen inteso come
applicazione, con il manuale l'uso della command line ecc.

Mi pare un'ottima idea, e merita di essere definita ed implementata, anche a costo di ritardare un po' la pubblicazione dei nuovi documenti. Questo, inoltre, semplificherebbe la vita nel caso altre persone volessero creare port di PolyGen in altri linguaggi, restando fedeli alla grammatica PolyGen — cosa che per altro è già succsessa, come si evince dal tentativo di portare PolyGen in Haskell:

• https://github.com/svoisen/hs_polygen

Uno standard per la definizione del metalinguaggio, con tanto di schema di versione/revisione eviterebbe fin da subito il caos.

Personalmente, mi piace molto Polygen Meta Language — il termine BNF (e derivati) sono parecchio inflazionati, e eXtended Bakus-Naur Form non rende l'idea di ciò che Polygen fa (anche se XBNF suona bene).

In un certo senso è già così: nel senso che il manuale, come noi lo
intendiamo, in realtà è il manuale del metalinguaggio, non del programma.
A questo punto, visto che abbiamo fatto 30, facciamo 31 e dichiariamo
ufficialmente che il manuale è il manuale del meta linguaggio; e poi
trasformiamo il readme che spiega la command line in uno user manual
ufficiale del programma.

Daccordo al 100%! Per quanto riguarda la documentazione ufficiale dovrebbe esserci chiarezza. E, in effetti, mi aveva stupito che il "Manuale" ufficiale non trattasse la riga di comando.

Hai qualche idea in merito al titolo + sottotitolo, e al nome file?

from polygen-docs.

Anche OCaml si attiene alla Semantic Versioning syntax (semver), il ché operativamente si traduce in una cosa: possiamo usare cppo (il preprocessore C-like di OCaml, da non confondere con camlp4 o camlp5 che appartengono alla categoria dei più sofisticati e generali preprocess-parse-pretty-printer) per i version number ecc.
Mi pare tu ti muova bene in questi territori, quindi magari un piccolo task per te potrebbe essere il seguente: sistemare il meccanismo di version syntax che avevo fatto all'epoca (il semplicissimo ver.ml.template che genera ver.ml tramite sed con una regole di makefile) e portarlo allo stato dell'arte attuale secondo le convenzioni di semver.
Se leggi il man di cppo vedrai che ci sono alcune macro (si chiamano così i simboli user-defined del preprocessore) atte all'uopo.

Per quanto riguarda il manuale del polygen allora facciamo così: chiamiamo Polygen Meta Language il linguaggio e il manuale è la specifica di tale linguaggio, non della sua implementazione. Poi faremo anche un manuale d'uso del programma, della sua CLI ecc.

Direi dunque:

Polygen Meta Language Spec 1.0 (questa è la versione esistita per anni, senza import e le cose nuove)
Polygen Reference Manual 1.0.6 (questo è il manuale utente della versione 1.0.6 esistente)

Per i nomi dei file io terrei la seguente convenzione: tutto minuscolo separato da dash ed i punti nella versione diventaon underscore. Divetano quindi:

polygen-spec-1_0
polygen-refman-1_0_6

Se hai idee migliori dimmi pure.

from polygen-docs.

Mi piace il sistema di titoli e nomi file.

Nell'immediato, per rettificare la bozza italiana, mi servono il titolo e sottotilo interno al documento; del tipo:

title:    Polygen Meta Language
subtitle: Specifiche tecniche del del meta linguaggio PML

oppure:

title:    Polygen Meta Language Spec 1.0
subtitle: Guida introduttiva all'uso di PML

O qualcosa del genere. Che dici, Polygen Meta Language lo lasciamo in inglese, o è il caso di tradurlo? Secondo me nel titolo ci sta bene anche in inglese.

Vale la pena provare a modificare i metadati nel sorgente markdown e rigenerare il documento, per vedere con i propri occhi l'impatto dei vari titoli — sembrano caz**te, ma in realtà fa una gran differenza, perché titolo e sottotitolo balzano agli occhi e offrono una prima impressione molte forte, ogni volta che apriamo il documento; quindi è bene trovare un accostamento che sia elegante ed equilibrato.

Quanto ai nomi file, ovviamente nella cartella sorgente dei documenti i file avranno un nome che tiene conto solo della lingua, non della versione: polygen-spec_it, polygen-spec_en (per poter riusare gli stessi script con ogni versione). Invece nelle cartelle dei coumenti finali, possiamo aggiungere la versione oltre alla lingua: polygen-spec-1_0_it (o anche polygen-spec_it-1_0, a secondo di come preferiamo che vengano ordinati: tutti gli it insieme o tutte le stesse versioni assieme).

In questo progetto potremmo tranquillamente tenere copia di ogni versione pubblicata, a titolo di archivio storico. Es:

polygen-refman_en-1_0_6
polygen-refman_en-1_1_0
polygen-refman_it-1_0_6
polygen-refman_it-1_1_0
polygen-spec_en-1_0
polygen-spec_en-1_1
polygen-spec_en-1_2
polygen-spec_it-1_0
polygen-spec_it-1_1
polygen-spec_it-1_2

Invece nel progetto PolyGen terremo solo le versioni più recenti dei documenti, con o senza il suffisso della versione (diciamo che gli utenti danno per scontato sia sempre aggiornato). Un semplice script può gestire la copia dei documenti più recenti da un progetto all'latro, rinominando come richiesto.

Comunque al nome nelle cartelle finali possiamo pensarci anche dopo, intanto sistemo i nomi dei file di lavoro in giornata.

magari un piccolo task per te potrebbe essere il seguente: sistemare il meccanismo di version syntax che avevo fatto all'epoca (il semplicissimo ver.ml.template che genera ver.ml tramite sed con una regole di makefile) e portarlo allo stato dell'arte attuale secondo le convenzioni di semver.

OK. Avevo sbirciato ai sorgenti e da quel che ricordo direi che è una cosa di cui posso occuparmi.

allo stato dell'arte attuale secondo le convenzioni di semver.

Di recente ho scritto varie RegEx per validare stringhe SemVer 2.0, quindi sono abbastanza fresco su questo punto.

from polygen-docs.

from polygen-docs.

OK. Io inizio a rinominare alcuni file qui, e già che ci sono creo anche i sorgenti per la versione inglese, e separo gli script di watch (uno per ogni lingua). Così inizio piano piano a portare al markdown il testo inglese esistente, così guadagnamo tempo.

from polygen-docs.

Bene. Ho aggiornato il tutto.

Ora i file adottano questa convenzione per i nomi: polygen-spec:

• polygen-spec_inc_ebnf-abstract.markdown
• polygen-spec_inc_ebnf-concrete.markdown
• polygen-spec_inc_ebnf-lexrules.markdown
• polygen-spec_IT.html
• polygen-spec_IT.markdown
• polygen-spec_IT_inc-Tables.markdown

NOTA: I suffissi delle lingue li ho tenuti in maiusolo, pensavo potesse aumentarne la visibilità in Esplora risorse o nelle varie liste di directory. Ma ovviamente posso cambiarli in minuscolo. Tu che preferisci?

In teoria i nomi in questa cartella sono solo per il lavoro con i sorgenti, e non devono per forza rispecchiare quelli dei documenti finali nelle cartelle di "produzione" o da altre parti.

Watch Scripts

Ora lo script watch.sh è diventato watch_IT.sh in vista del fatto che fra poco inizio ad includere anche la bozza inglese e volevo separare i due script — in realtà non ne sono sicuro. L'idea originale era di avere un solo script di watch, il fatto è che questi controlla anche il file CSS, che è comune a tutte le lingue, e se questi viene ricompilato (da Sass) allora il watch lancia gli script di rebuild di tutte le lingue. Magari è preferibile fare il watching di una sola lingua per volta (anche perché ci metterebbe parecchio a convertire entrambi i documenti).

Ancora su Edizione vs PML v.

Tornando al punto della version PML rispetto all'edizione documento. Guardando il documento "compilato", mi sono reso conto che anche se lo standard PML dovesse restare invariato, il documento potrebbe comunque crescere (nuove sezioni, nuovi esempi, ecc). Qual'è la correlazione tra la versione del documento e PML?

All'utente finale interessa sapere non solo a quale versione di PML (e PolyGen) si riferisce il documento che ha tra le mani, ma anche capire se si tratta di una versione più recente rispetto alla sua (o all'ultima consultata), e poter avere un'idea del grado di modifiche introdotte — da qui l'idea originale di adottare uno schema simile al SemVer, anche se un documento non è certo una API, comunque le tre cifre di vX.Y.Z possono comunicare se si tratta di modifiche grosse, minime o mere modifiche estetiche e correzioni di refusi (l'equivalente dei bug nelle API).

from polygen-docs.

from polygen-docs.

Perché i contenuti inclusi sono solo blocchi di codice EBNF (passati ad Highlight per la colorazione).

Questi blocchi sono comuni a tutte le lingue, quindi li ho messi in file separati, _ebnf nel nome è solo un modo per raggrupparli assieme nell'elenco dei file, ed un promemoria. Tanto riguarda solo i sorgenti di lavoro.

from polygen-docs.

Per carità, non insisto - però è sufficiente polygen-spec-abs, polygen-spec-con e polygen-spec-lex (cioè abstract syntax, concrete syntax e lex rules). Mi sembra che appesantiscano il nome, ma è vero che è solo per noi, boh non so.

from polygen-docs.

Sì, posso abbreviarli come dici, ma terrei la parte _inc_ perché può tornare utile nell'automazione. ebnf_ lo si può togliere, tanto i documenti sono comunque markdown, al di là del contenuto.

• polygen-spec_inc_lex.markdown
• polygen-spec_inc_con.markdown
• polygen-spec_inc_abs.markdown

Diciamo che nella fase di lavoro tendo ad abbondare nei nomi, per facilitarmi la vita (che non ci vedo più bene come una volta), e per poter selezionare in fretta file simili in Esplora Risorse — e anche che faccio molto affidamento sul'autocomplete per raggirare la scrittura di nomi lunghi.

So che avere gli abbreviativi lingue in maiuscolo (IT, EN) può risultare una rottura di scatole nella digitazione dei nomi, ma vorrei tenerli così sia per la maggior visibilità che per eventuali automazioni di script (che altrimenti potrebbero intercettare frammenti di nome file che non riguardano la lingua).

from polygen-docs.

Ciò che rende questi nomi lunghissimi è l'estensione .markdown. Ma ho preferito evitare di usare .md dato che questa nel progetto viene usata per i documenti in GitHub markdown, per anteprime su GitHub.com. E siccome si tratta di documenti in pandoc markdown (con aggiunta di macro PP), ho ritenuto bene separarli (anche perché sono estensioni che ho associato ad editor diversi sul PC)

from polygen-docs.

Ok, li ho rinominati così (già pusshati):

• polygen-spec_IT_inc_tables.markdown
• polygen-spec_inc_lex.markdown
• polygen-spec_inc_con.markdown
• polygen-spec_inc_abs.markdown
• polygen-spec_EN_inc_tables.markdown

Ora tutto è in minuscolo, tranne la lingua.

from polygen-docs.

Ciao @alvisespano, ho modificato leggerment il testo (sia in italiano che in inglese) in 2.5.2 Selezione multipla:

Selezione multipla

Si prenda l'esempio in [@sec:etichette-selezione]: la definizione di S si occupa sostanzialmente di attivare le combinazioni delle etichette S,P e M,F per Ogg. Per evitare la frequente scomodità di dover compiere simili operazioni è possibile specificare a destra del punto tra parentesi tonde una serie di etichette separate dal pipe, anziché una singola etichetta.

In entrambi i documenti S,P e M,F appaiono uniti, con la virgola che fa parte del simbolo. Io l'ho modificato in:

delle etichette S, P e M, F per Ogg.

Ci ho riflettuto un po', e so che tecnicamente parlando era giusto così com'era poiché la virgola qui può essere vista come generazione posizionale automatica. Però ritengo creerebbe meno confusione separare i simboli come ho fatto, e lasciare che la virgola sia solo punteggiatura del testo (anziché la parola chiave ,) dato che la sezione Generazione posizionale viene più avanti nel testo, e che comunque l'esempio qui discusso non dipende da essa.

Ti volevo solo chiedere conferma se a te va bene, dato che ho visto che in entrambi i documenti avevi incluso queste coppie di simboli assieme alla virgola (non spaziata) tra i tag <code>, e quindi è stato sicuramente intenzionale.

from polygen-docs.

from polygen-docs.

Dici che è fuorviante? C'ho messo un po' a capire di cosa parlavi: intendi
dire che hai aggiunto uno spazio dopo le virgole nel testo perché la
notazione "S,P" sembrava un pezzo di sintassi del polygen?

Sì, mi riferivo proprio a quello. Mi sembrava voluto, e ho dedotto che sfruttavi la sintassi della generazione posizionale, ma a questo punto del documento ritenevo più opportuno separare i simboli.

Forse potremmo addirittura creare una perifrasi diversa per ovviare al
problema ulteriormente:

Grazie, il nuovo testo aiuta, semplifica la scorrevolezza della lettura. Quello precendete era molto sintetico, e in inglese un po' più difficile da articolare. Da un alto, l'esempio che segue subito dopo chiarisce il concetto, dall'altro se lo si vuole spiegare è meglio entrare nei dettagli — parto anche dal presupposto che, arrivato a questo punto, il lettore che studia il documento "tutto d'un fiato" inizia a essere affaticato e travolto dalla mole di concetti nuovi che si susseguono. Quindi tutto ciò che rende più fluida la lettura, fornendo i concetti anziché lasciarli dedurre al lettore, è un'agevolazione in tal senso.

from polygen-docs.

from polygen-docs.

Direi cha va bene così, è un buon compromesso tra una specifica formale della sintassi ed una guida all'uso della medesima tramite esempi concreti.

Non mancherò di segnalarti evntuali passaggi che potrebbero essere resi più chiari, ma in linea di massima quelli che ti ho sottoposto erano gli unici che mi venivano in mente.

Mentre traduco, e mi tocca leggere più volte le frasi del testo originale italiano, salta fuori qualche piccolo refuso di battitura che ci era sfuggito, e colgo l'occasione per correggerlo. Ma direi che quando avrò terminato con la prima bozza dell'inglese anche la versione italiana sarà stata rivista appieno.

from polygen-docs.

from polygen-docs.

(so che sei preso in questi giorni — io posto giusto per tenerti aggiornato, ma non c'è nessuna urgenza a riguardo)

Warnings di Selezione distruttiva

C'era un passaggio un po' oscuro in 4.2.2.3 Selezione distruttiva (sia in italiano che inglese) e l'ho modificato.

A un certo punto spiegava:

I casi fortunati in cui tale distruzione riguarda un’intera produzione vengono regolarmente segnalati da un warning (4.2.2.2) o un errore (4.1.4), ma nel caso in cui le produzioni distrutte siano all’interno di una sequenza non ci sarebbe modo, tramite solamente l’algoritmo di controllo delle epsilon-produzioni, di rilevare il problema, poiché di fatto non si è in presenza di epsilon-produzioni:

ma dopo l'esempio asseriva:

In tali casi viene generato un warning apposito che notifica l’utente del problema. Si badi che la correzione di tutti i warning di questo tipo irrobustiscono di molto una grammatica e talvolta possono aiutare persino a rilevare utilizzi concettualmente scorretti delle etichette.

Non era chiaro se in quest'ultimo passaggio "tali casi" si riferisse ai "casi fortunati" del paragrafo precedente, oppure a quelli dell'altro tipo ("in cui le produzioni distrutte siano all’interno di una sequenza").

L'ambiguità è data dal fatto che può essere intrepretato in 2 modi:

1. Specifica che correggendo questi tipi di warning/errori si irrobustisce la gramamtica (riferendosi a quelli dei "casi fortunati", nonché gli unici) — ovvero, i casi meno fortunati non c'entrano nulla perché tanto non sono intercettabili.
2. Spiega che per i casi meno fortunati vi è un warning apposito, diverso da quello per i "casi fortunati". E che sarebbero questi secondi warning che andrebbero corretti.

Ho dato per scontato che Polygen non sia in grado di rilevare in nessun modo le selezioni distruttive all'interno di sequenze, e che questo paragrafo volesse solo portare l'attenzione sull'importanza di correggere questi warning, così l'ho corretto in:

Quando Polygen indvidua una selezione distruttiva, genera un warning apposito che notifica l'utente del problema. Si badi che la correzione di tutti i warning di questo tipo irrobustiscono di molto una grammatica e talvolta possono aiutare persino a rilevare utilizzi concettualmente scorretti delle etichette.

spero di non aver travisato il testo.

from polygen-docs.

from polygen-docs.