search

tajmone / polygen-docs

PolyGen Documentation
GNU General Public License v2.0
1 stars 0 forks source link

Ultimi Ritocchi Prima della Pubblicazione #1

Closed tajmone closed 6 years ago

tajmone commented 6 years ago

Ciao @alvisespano,

Sono in dirittura d'arrivo con il lavoro per il manuale italiano.

Sto rileggendo tutto il testo alla ricerca di possibili refusi. Prima di pubblicarlo aspetto il tuo benestare; se nel frattempo vuoi dargli un'occhiata anche tu.

Frase "sorta di circuiti"

A mio avviso, questa frase è poco chiara (sia nell'italiano che nell'inglese):

Questa grammatica non potrebbe produrre alcun output, poiché la generazione, indipendentemente da quale simbolo non terminale abbia inizio, incorrerebbe in un ciclo ricorsivo infinito.

Altri casi, più subdoli, possono dare luogo a sottocicli — una sorta di circuiti:

— 4.1.2 Ricorsioni cicliche e non-terminazione

Quel "una sorta di circuiti" non mi risulta molto chiaro — forse "corto circuito"? Nel paragrafo precedente menziona il "ciclo ricorsivo infinito"; in che modo quest'altro esempio differirebbe?

tajmone commented 6 years ago

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:

tajmone commented 6 years ago

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.

alvisespano commented 6 years ago

Gli do un'occhiata adesso.

alvisespano commented 6 years ago

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 :)

tajmone commented 6 years ago

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.

alvisespano commented 6 years ago

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?

tajmone commented 6 years ago

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.

alvisespano commented 6 years ago

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 :)

tajmone commented 6 years ago

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.

alvisespano commented 6 years ago

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.

alvisespano commented 6 years ago

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ì.

alvisespano commented 6 years ago

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

tajmone commented 6 years ago

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.

alvisespano commented 6 years ago

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?

tajmone commented 6 years ago

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.

tajmone commented 6 years ago

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.

  1. 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.

  1. 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.

tajmone commented 6 years ago

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.

tajmone commented 6 years ago

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à.

alvisespano commented 6 years ago

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?

alvisespano commented 6 years ago

Mi sembra una buona idea usare gli script, se includere una sottodir è complicato. Tanto in pratica la documentazione è stabile da 15 anni :D Se ogni tanto cambiamo qualcosa, lo script è sufficiente - basta scrivere nel readme come fare, per noi stessi quando ci dimenticheremo, intendo :) Le cartelle en/, it/ ecc nella root del repo mi sembrano una scelta intelligente; alternativamente una cartella out, oppure dist, sembrerebbe ricordare una cartella bin, ma declinata per la documentazione anziché per del software eseguibile. Tuttavia il non riuscire a trovare un nome che mi piace per tale cartella mi fa ripiegare sulla soluzione con le cartelle a top level.

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. E nel repo del polygen ci mettiamo i render finali nella cartella documents. Lo stile dei nomi delle cartelle (src, doc, grm) era originariamente uno stile unix-like che forse oggigiorno è un po' passato.

Il giorno 15 gennaio 2018 15:44, Tristano Ajmone notifications@github.com ha scritto:

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à.

— You are receiving this because you were assigned. Reply to this email directly, view it on GitHub https://github.com/tajmone/polygen-docs/issues/1#issuecomment-357702054, or mute the thread https://github.com/notifications/unsubscribe-auth/ACcZxnfTYQFROOYyTkXa8IgTQdoOi4nNks5tK2RQgaJpZM4RdRPh .

tajmone commented 6 years ago

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

tajmone commented 6 years ago

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.

alvisespano commented 6 years ago

Io direi "Polygen-Man_IT.html" e buona notte.

Il giorno 15 gennaio 2018 16:53, Tristano Ajmone notifications@github.com ha scritto:

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.

— You are receiving this because you were assigned. Reply to this email directly, view it on GitHub https://github.com/tajmone/polygen-docs/issues/1#issuecomment-357721026, or mute the thread https://github.com/notifications/unsubscribe-auth/ACcZxtvi10kG7qJUh8pyI39xmMsB-VAoks5tK3RtgaJpZM4RdRPh .

alvisespano commented 6 years ago

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

tajmone commented 6 years ago

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)

alvisespano commented 6 years ago

Ho usato gli script che mi hanno scaricato e creato vari file, e cerca di committarmeli.

Il giorno 15 gennaio 2018 17:05, Tristano Ajmone notifications@github.com ha scritto:

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)

— You are receiving this because you were assigned. Reply to this email directly, view it on GitHub https://github.com/tajmone/polygen-docs/issues/1#issuecomment-357724581, or mute the thread https://github.com/notifications/unsubscribe-auth/ACcZxi3cmUZOHIMbOcD-vhMysfn0-PIwks5tK3c8gaJpZM4RdRPh .

tajmone commented 6 years ago

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.

tajmone commented 6 years ago

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

tajmone commented 6 years ago

Ok, fatto.

tajmone commented 6 years ago

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

tajmone commented 6 years ago

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

tajmone commented 6 years ago

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?

alvisespano commented 6 years ago

Dunque, gli script sono ottimi: percepisco il tuo senso per l'eleganza integrato col compromesso per la semplicità. Perdonami ma sono un linguaggista ed un teorico/filosofo della programmazione, quindi a volte do peso a questioni di stile :) Secodno me sono giusti così.

Per quanto riguarda la versione, io farei un version bump alla 1.1.0. Il minor number indica un revamp, non giustificato da un major bump alla 2.0, ma nemmeno da una revision sul terzo numero.

Il giorno 15 gennaio 2018 17:45, Tristano Ajmone notifications@github.com ha scritto:

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?

— You are receiving this because you were assigned. Reply to this email directly, view it on GitHub https://github.com/tajmone/polygen-docs/issues/1#issuecomment-357735457, or mute the thread https://github.com/notifications/unsubscribe-auth/ACcZxgqlN0TN-jFOqiuQbKHnQw9lnA9uks5tK4CjgaJpZM4RdRPh .

tajmone commented 6 years ago

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).

alvisespano commented 6 years ago

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?

tajmone commented 6 years ago

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?

tajmone commented 6 years ago

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 MINORversion, 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 MAJORche indica cambiamenti non retro-compatibili, ossia nuove versioni di Polyge; MINORindica nuove sezioni e contenuti, e PATCHmodifiche minori, estetiche e correzioni di refusi).

alvisespano commented 6 years ago

Il tuo discorso è giusto (infatti una volta neanche avevo il numero di versione nella doc, ma era soltanto una), tuttavia consolidiamo un attimo cosa sono i numeri di versione del polygen:

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.

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.

Il giorno 17 gennaio 2018 11:38, Tristano Ajmone notifications@github.com ha scritto:

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 MINORversion, 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 MAJORche indica cambiamenti non retro-compatibili, ossia nuove versioni di Polyge; MINORindica nuove sezioni e contenuti, e PATCHmodifiche minori, estetiche e correzioni di refusi).

— You are receiving this because you were assigned. Reply to this email directly, view it on GitHub https://github.com/tajmone/polygen-docs/issues/1#issuecomment-358265087, or mute the thread https://github.com/notifications/unsubscribe-auth/ACcZxvDqNwFVLV9ra1d8y9zmIKCIBsodks5tLc20gaJpZM4RdRPh .

tajmone commented 6 years ago

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):

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:

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?

alvisespano commented 6 years ago

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.

tajmone commented 6 years ago

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.

alvisespano commented 6 years ago

Direi di non tradurre il titolo: Polygen Meta Language Spec rimane in inglese, ed il sottotitolo magari in italiano cone suggerivi.

Il giorno mer 17 gen 2018 alle 16:42 Tristano Ajmone < notifications@github.com> ha scritto:

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.

— You are receiving this because you were assigned.

Reply to this email directly, view it on GitHub https://github.com/tajmone/polygen-docs/issues/1#issuecomment-358344398, or mute the thread https://github.com/notifications/unsubscribe-auth/ACcZxgl01GXgXnpW_s8Xi849k4_cesCjks5tLhT-gaJpZM4RdRPh .

tajmone commented 6 years ago

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.

tajmone commented 6 years ago

Bene. Ho aggiornato il tutto.

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

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).

alvisespano commented 6 years ago

Scusa, perché c'è il suffisso "inc_ebnf"?

Il giorno 17 gennaio 2018 18:06, Tristano Ajmone notifications@github.com ha scritto:

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).

— You are receiving this because you were assigned. Reply to this email directly, view it on GitHub https://github.com/tajmone/polygen-docs/issues/1#issuecomment-358372614, or mute the thread https://github.com/notifications/unsubscribe-auth/ACcZxo3lpqov9bT9lobwwl4DVlVyV4K7ks5tLih8gaJpZM4RdRPh .

tajmone commented 6 years ago

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.

alvisespano commented 6 years ago

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.

tajmone commented 6 years ago

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.

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).

tajmone commented 6 years ago

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)

tajmone commented 6 years ago

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

Ora tutto è in minuscolo, tranne la lingua.