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?

In §3.1
There are two different version of the same paragraph

Keep in mind then that it is up to you [...]

and

Bare in mind that you’ll need to provide [...]

I think the second one flows better. I would also suggest to change

Bare in mind that you’ll need to provide a non-recursive production somewhere along the line, in order to guarantee to the program an exit point from the recursion, at one point or another; otherwise, a cyclic recursion error will be generated by the grammar checker (see section 4.1.2).

to

Bear in mind that you’ll need to provide a non-recursive production somewhere along the line, in order to guarantee an exit point from the recursion, at some point; otherwise, a cyclic recursion error will be generated by the grammar checker (see section 4.1.2).

The English PML Spec 1.0 documentation (Ed. v1.1.0, 2018/02/10) contains a considerable number of typos and spurious paragraphs left over from the editing stage (either the original Italian text or alternative translations that were accidentally left behind).

Live Previews

Up-to-date Live HTML Previews of the v1.1.1 release candidate (WIP), directly from the dev branche, will be available at this link:

• English PML Spec 1.1.1-rc preview

Whenever a fix is applied to the source doc, the HTML document will be rebuild to ensure that proofreaders have access to on-line previews of the latest edited version of each document.

Current Work Plan

I've already started to track the various issues under the PML Spec EN v1.1.1 milestone and I'm planning an updated edition (Ed. v1.1.1). Obviously the Spec version remains the same (PML 1.0), it's just the document edition that's being updated, and this will not introduce new contents but just fix the existing ones.

All fixes and updates for the English doc will be commited to the dev1.1.1_EN branch, and ultimately squashed as a single commit on master when it's ready.

Needed Support

I would really appreciate some help with the revision of the English text, i.e. searching for linguistic typos, stray paragraphs and any problems with the examples (PML source and their productions) and the pointing them out by creating new Issues here.

NOTE — For convenience, we'll adopt en_US dictionaries for proofreading, since many programming terms have become standard in theri US form even in the UK.

@alvisespano, if you could double check all the examples (both sources and productions) it would be really helpful. Many examples were re-adapted by myself in occasion of the new markdown edition of the Specs, in an attempt to make them "more English", so chances are that in various occasions I might have gotten the productions samples wrong (e.g. in one case, I forgot to translate some Italian words).

@RBastianini, I was wondering if you'd like to help in this revision work, since the English PML Specs also apply to your Polygen-PHP project, since it's 100% Polygen compliant — b.t.w., excellent work there! well done.

In the next revision of the English PML doc we should fix the title-casing of all section titles according to Chicago Manual of Style rules.

I usually rely on this online tools for the task:

https://capitalizemytitle.com/

• In §2.7 the secondary sentence of the first paragraph is missing the subject

  Many spoken languages allow changing the order of some words (or groups of words) in a sentence without altering its original meaning; likewise, at a macroscopic level, sometimes is possible to swap the order of sentences within a phrase.

  should instead be

  Many spoken languages allow changing the order of some words (or groups of words) in a sentence without altering its original meaning; likewise, at a macroscopic level, sometimes it is possible to swap the order of sentences within a phrase.

• (REJECTED) In the following sentence, the order of words can be altered for a more natural flow:

  To avoid writing each and every variation of a sequence in which some atoms swap positions, you can enclose within curly brackets { and } the subproductions that need to be permutated.

  →

  To avoid writing each and every variation of a sequence in which some atoms swap positions, you can enclose the subproductions that need to be permutated within curly brackets { and }.

• I believe that the two following examples are incorrect. They are syntactically acceptable, but they do not produce the expected results, due to the use of unquoted commas ,.

  S ::= {in 10 minutes}^, {at 3 o'clock}^, {"I" {will depart} {alone}} ;
  

  should instead be

  S ::= {in 10 minutes}^"," {at 3 o'clock}^"," {"I" {will depart} {alone}} ;
  

  and

  S ::= {in 10 minutes}^, {at 3 o'clock}^, ("I" {will depart} {alone}) ;
  

  should instead be

  S ::= {in 10 minutes}^"," {at 3 o'clock}^"," ("I" {will depart} {alone}) ;
  

  We can remove some of the punctuation signs by using dashes in place of commas, so we at least don't require to concatenate them to the preceding word, such as

  S ::= {in 10 minutes} "-" {at 3 o'clock} "-" {"I" {will depart} {alone}} ;
  

  and

  S ::= {in 10 minutes} "-" {at 3 o'clock} "-" ("I" {will depart} {alone}) ;
  

• In §2.10, the first sentence can be rewritten in order to facilitate the reader:

  Binding is, in general, a declarative construct that associates a series of productions to a non terminal symbol. Each binding introduces in the environment (see section 2.11) that association, and every production generated in that environment can refer to its non terminal symbol.

  →

  Binding is, in general, a declarative construct that associates a series of productions to a non terminal symbol. Each binding introduces that association in the environment where it is declared (see section 2.11), and every production generated in that environment can refer to its non terminal symbol.

• The two ending sentences in §2.10.1 can also be tweaked:

  The production associated to Fruit does not undergo an immediate production but is closed together with the current environment according to scoping rules.

  →

  The production associated to Fruit does not undergo an immediate generation but is closed together with the current environment according to scoping rules.

• Also, there's a typo: occurence -> occurrence (actually this one is repeated a few times in the following paragraphs, consider doing a bulk replace).

• In §2.10.2, I would personally replace the words in bold a single time with just once.

In §1. What is a grammar? of the English PML Specs there are two consecutive paragraphs that have identical meaning:

By default, a term beginning with a capital letter is considered as non-terminal (thus bound to a definition) and a term beginning with a non-capital letter as terminal (a simple word). If you need then to specify a capital word you must quote it in order to get the program not to mistake it for a non-terminal symbol:

As a convention, any term beginning with a capital letter is considered a non-terminal symbol (therefore bound to a definition) and any term beginning with a non-capital letter is considered a terminal symbol (i.e., just a word). If you need to generate a word starting by capital letter you must place it within quotes, so that the program doesn’t mistake it for a non-terminal symbol:

Probably these are variations of the same paragraph left over from the editing stage, and one of the two was accidentally left there. We need to decide which of the two is better and delete the other one.

This repository hasn't been updated for quite a while, so at some point we might want to ensure its usability with the latest dependencies versions.

• Check that the docs can still build as expected with the latest versions of the third party tools and, if they don't, either fix the sources accordingly or skip updating:
  • pandoc v2.1 (x86) → v2.10.1
  • PP v2.2.2 (x86_64) → v2.14.1 — (download page)
    • CAN'T UPDATE! The PP macros won't work with latest PP version.
      We'll have to skip the PP update until they are fixed.
      • Task moved to #33.
  • pandoc-crossref v0.3.0.0 (x86) → v0.3.7.0a
  • Highlight v3.42 (x86_64) → v3.57 — (download page)
• Update the current GitHub HTML5 Pandoc Template (v2.0) to the latest version from pandoc-goodies (v2.2) to ensure full compatibility with current pandoc version (see tajmone/pandoc-goodies#10).
• Update the download.bat script accordingly.

Although this isn't strictly necessary (end users can always download the exact versions of the dependencies via the download.bat script offered in the repo) it's still preferable to keep the assets up-to-date with the latest tools.

Since the Polygen definition for Highlight is now included in the official package (and has been so for a while, after this repository was created), we could safely remove the polygen.lang file from the repository.

• Delete polygen.lang
• Delete ebnf2.lang
• Update the READMEs accordingly.
• Remove Highlight definitions from .gitattributes

I still haven't set my mind on this, and will wait before taking any action — this Issue is here mainly as a reminder of this possibility.

NOTE — the Polygen syntax in the repository and the one shipped with Highlight are currently identical. The same goes for the ebnf2.lang definition, which is identical to the one in Highlight.

Considerations

There are pros and cons to this action:

Cons

If we ever need to update/improve the Polygen or EBNF definition, keeping it within the repository is a better option (and doesn't add any burdern).

Since the repository is set to download and use a specific version of Highlight, we don't need to worry about future updated of the app not being backward compatible.

Pros

On the other hand, if the Polygen or EBNF definition is updated mainstream (e.g. by a third party) it we would loose any benefits — integrating the new version would only require updating the download script that selects a specific release of Highlight.

Although I'm the creator and maintainer of both syntaxes, it's possible that someone will update one of those syntaxes in the future (more so the EBNF syntax) — which might bring benefits to us, but could also crack things up.

Conclusion

Either way, manually overriding the Polygen or EBNF syntax in the repository is a simple cut and paste operation, and keeping the definition local to the project allows ensuring that the exact Polygen definition is used, regardless of the Highlight release that end users adopt.

So it might be better right now to keep things as they are, and keep any eye on how Highlight evolves and if its syntaxes are updated (or, indeed, if the application undergoes changes that might require fixing the definitions).

In PML Spec (Italian), change the title of §4.2.2.1 from

§4.2.2.1 Inesistenza del simbolo I

to:

§4.2.2.1 Inesistenza del simbolo 'I'

replacing the inline code style with single quotes, which is more appropriate in titles.

(in the English doc this was already take care of)

Preparation for a new release (v1.1.1) is on its way. The goal is to update the toolchain and revise both PML Spec documents, especially the English edition (which contains many left over paragraphs from the editing stage).

Live Previews

Up-to-date Live HTML Previews of the v1.1.1 release candidates (WIP), directly from their dev branches, will be available at these links:

• English PML Spec 1.1.1-rc preview
• Italian PML Spec 1.1.1-rc preview

Whenever a fix is applied to the source docs, the HTML document will be rebuild to ensure that proofreaders have access to on-line previews of the latest edited version of each document.

Dev Branches and Strategy

Development will occur in the following branches:

• dev1.1.1 — development baseline for commits that are common to the PML Spec doc in both locales.
  • dev1.1.1_EN — dev branch for Eglish PML Spec (Ed. 1.1.1).
  • dev1.1.1_IT — dev branch for Italian PML Spec (Ed. 1.1.1).

This workflow allows separating the work on each language, as well as their common assets, and simplify integrating changes across them.

The dev1.1.1 branch will also to used to squash all the changes to both document into a single commit per document, allowing us to prepare a clean-history for the final merge into master and the new 1.1.1 release.

Milestones and Issues

All pending tasks are grouped under three different milestones, in a similar fashion to the branches structure:

• PML Spec v1.1.1 (EN+IT) — Issues common to the PML Spec doc in both locales.
  • PML Spec EN v1.1.1 — Issues specific to the English edition.
  • PML Spec IT v1.1.1 — Issues specific to the Italian edition.

• Find an alternative example without labels? (see #36)

@RBastianini pointed out in #26:

In §2.4.2 the second example uses labels, a concept that has not yet been introduced to the reader. Maybe we can remove them from the example, so it becomes less confusing? (Actually, this suggestion also applies to the italian documentation).

I've moved the proposal into this independent issue for it deserves a thread of its own, and because it applies to both the Eglish and the Italian PML Spec documents.

As I already commented to the original post:

There are a couple of similar instances in both documents. I also found them confusing initially. It's also true that writing a specs doc without incurring in similar situations is not easy, but if it's avoidable I agree that it would be better to remove such examples and (if strictly required) provide a cross reference to the topic section (for the benefit of those who are re-reading the documents).

I think that readers tend to spend some time studying the examples in order to make sense of what they've learned so far, so I'm totally in favor for this type of revision. What do you think @alvisespano?

Ciao @alvisespano,

Ho creato anche una sintass per EBNF di modo da colorare anche le regole EBNF riportate in Appendice. Il risultato lo trovo gradevole e più facile da leggere.

Mi sono permesso anche di ritoccare la EBNF delle Regole lessicali perché colorandone la sintassi mi sono reso conto che qualcosa non andava (nota, è la stessa regola in cui era andato perso un carattere). Prima era:

Term ::= [a-z 0-9 '][a-z A-Z 0-9 ']*
      |  " [A-Z a-z 0-9 ( ) _ - ? . , ! : \ & # + * / % $ £ ` [ ] { } ~ @ ; : | < > = ^ ' \ "]* "

Il problema era alla fine della stringa: \ "]* " (seconda riga) — quelle virgolette tra il backslash e la parentesi quadra chiusa. Il parser di Highlight la vede come chiusura della stringa, e quindi con le virgolette successive (che dovrebbero essere quelle di chiusura) apre una nuova stringa che prosegue per svariate righe, ingarbugliando la sintassi.

L'ho cambiato in \ ]* ":

Term ::= [a-z 0-9 '][a-z A-Z 0-9 ']*
      |  " [A-Z a-z 0-9 ( ) _ - ? . , ! : \ & # + * / % $ £ ` [ ] { } ~ @ ; : | < > = ^ ' \ ]* "

Dall'analisi dei sorgenti del Lexer, direi che è così che dovrebbe essere, ma ammetto di non conoscere a fondo la notazione EBNF, quindi spero di non aver fatto danni.

In §2.7 Permutazioni fix the following two examples by enclosing within quotes the commas (which are intended to be printed out):

• S ::= {tra 10 minuti}^, {alle 3 in punto}^, {{io} {partiro'} solo} ;

  → S ::= {tra 10 minuti}^"," {alle 3 in punto}^"," {{io} {partiro'} solo} ;

• S ::= {tra 10 minuti}^, {alle 3 in punto}^, ({io} {partiro'} solo) ;

  → S ::= {tra 10 minuti}^"," {alle 3 in punto}^"," ({io} {partiro'} solo) ;

(Error pointed out by @RBastianini in #35, for the English docs)

I've just noticed that we never created a tagged release for the initial project (v1.1.0).

We're still in time do so, and we indeed should do it in view of the upcoming new release (v1.1.1).

Now that we are updating the project we need to add a CHANGELOG.

• In README.md add a new "Changelog" section listing all the significant changes to the repository — grouped by version and/or date.
  • Link to archived/README.md for the PML Spec docs CHANGELOG.
• In archived/README.md add new "Changelog" section listing all changes to PML Spec documents, grouped by version releases, and then by document locale.

The idea behind keeping two different changelogs is that the one in the main README should provide info about changes in the repository (e.g. under "August 2020" we'll mention the switch to Dart Sass, dependencies updates, etc.), which don't necessarily relate to the PML Spec documents.

Changes to the PML Spec documents should be documented in the archived/ folder's README, which contains a copy of every document released.

This separation of changelogs is better for all users — maintainers and contributors — for it allows to focus on specific aspects of the project.

In the future, if the "Changelog" section in the main README becomes too long, we can move it to a separate CHANGELOG.md document.

In both the English and Italian version of the PML documentation, there are some missing / implicit details regarding a few behaviours around label selection. They might not be of importance, but since I was surprised when I discovered them, I thought they were worth bringing up to your attention.

A consequence of some of these findings is that the formal language definition (§5.1) is incorrect / incomplete.

Label group concatenation

In §2.5.2 is shown how multiple label selection groups can be concatenated to reduce the verbosity of the grammar definition, such as in S ::= Conjug.(S|P).(sp|pp) ;. However, I believe this contradicts the concrete syntax in (§5.1), where an atom is defined as follows:

ATOM   ::= Term
        |  "^"
        |  "_"
        |  "\"
        |  UNFOLDABLE
        |  ">" UNFOLDABLE
        |  "<" UNFOLDABLE
        |  ATOM "."
        |  ATOM DotLabel
        |  ATOM ".(" LABELS ")"

and thus I think the correct definition should instead be

ATOM   ::= Term
        |  "^"
        |  "_"
        |  "\"
        |  UNFOLDABLE
        |  ">" UNFOLDABLE
        |  "<" UNFOLDABLE
        |  ATOM "."
        |  ATOM DotLabel
        |  ATOM (".(" LABELS ")")+

In order to implement compatibility with this syntax in Polygen-PHP (which I wrote according to the abstract and concrete language definitions from the readme on the official site and thus, did not support it at first), I resorted to adding this extra abstract-to-concrete-syntax conversion step (I think you might at most be interested in the docblock at the beginning of the file, where the conversion step is described through an example). Depending on how this was originally implemented in Polygen, it might also mean that there exists an extra undocumented conversion step, and thus that §5.5 needs amending as well. However I might be completely wrong on this part, as support for this syntax might be embedded in the parser for the concrete definition. I remember close to nothing about my OCaml days at the university, so I couldn't figure this out on my own.

Single label concatenation

Although it might be somewhat considered implicit in §2.5.2, multiple label selections can not only be concatenated when in groups (S ::= Something.(l1|l2).(l3|l4);), but also when taken singularly ( S ::= Something.l1.l2.l3.l4;). Both declarations are correctly accepted by Polygen and influence label selection as expected. I believe that this means that the concrete syntax for ATOM is again partially incorrect and should be amended as follows:

ATOM   ::= Term
        |  "^"
        |  "_"
        |  "\"
        |  UNFOLDABLE
        |  ">" UNFOLDABLE
        |  "<" UNFOLDABLE
        |  ATOM "."
        |  ATOM (DotLabel)+
        |  ATOM (".(" LABELS ")")+

Dot concatenation

For completeness sake, although not particularly useful, it is possible to concatenate multiple dots: S ::= Something.....;. This does not change the behaviour of the dot operator, and would still result in the same output no matter if one or one thousand dots were employed.
Again, this require updating the ATOM concrete definition:

ATOM   ::= Term
        |  "^"
        |  "_"
        |  "\"
        |  UNFOLDABLE
        |  ">" UNFOLDABLE
        |  "<" UNFOLDABLE
        |  ATOM "."+
        |  ATOM DotLabel+
        |  ATOM (".(" LABELS ")")+

Resetting on non-(non-terminals)

Another oddity I discovered, is that label reset token can not only be employed on non-terminals, but also on terminals, although it does not seem to affect the selection in any way. In order to prove this for Polygen-PHP I wrote this test where the following grammar demonstrating this property can be found.

S ::= A.a;
A ::= a: a B and. C;
B ::= a: b | c: nope;
(* When the time comes to generate C, no suitable productions will be found given the currently selected labels. *)
C ::= g: c;

This grammar is correctly parsed by Polygen, but can only produce one result, which is and b and.

To be fair, although I don't think this is explicitly stated in the documentation, it is correctly represented by the ATOM definition (which also tells us that we can use the selection reset token on ^, \ and _, which similarly does not affect the the label scope).

Selecting on non-(non-terminals)

Everything in the previous section also applies when using labels (as correctly reported by the TERM definition). So both S ::= Something and.also.this; and S ::= Something and.(this|that); are acceptable declarations, but the selected labels don't affect the generation in neither of the examples.

Mixing labels, groups and dots

Another interesting discovery I made, is that dot labels, label groups and label reset tokens can be mixed when selecting, like in the following declaration: S ::= Something.and..(notice|the|double|dots).before.the.round.braces.(and|at|the).end..;. This once again means that the ATOM definition is incorrect. I'm unsure about how to fix this, but I believe this could work:

ATOM   ::= Term
        |  "^"
        |  "_"
        |  "\"
        |  UNFOLDABLE
        |  ">" UNFOLDABLE
        |  "<" UNFOLDABLE
        | ATOM SELCTN+

SELCTN ::= "."
        | DotLabel
        | ".(" LABELS ")"

Label precedence

A consequence of the previous discovery, is that we can mix together label selection and label reset, so I got curious about the precedence of these label operations during parsing.
Turns out that in Polygen, label operations are processed from right to left, as demonstrated by this test) in Polygen-PHP.
The test uses the following grammar

S ::= Generate.one.a..two.b Generate.two.a..one.b Generate.one.b..two.a Generate.two.b..one.a;
Generate ::= a: A | b: B;
A ::= one: a | two: aa;
B ::= one: b | two: bb;

that can only produce the following output: a aa b bb, basically ignoring every other selection that comes to the right of the label reset token.

• Document how versions scheme apply to the project:
  • Repository releases version.
  • PML Spec documents version and Edition.

The versioning scheme follows SemVer, except that instead of the repository code the version number focuses on the PML Spec document(s). This might require some explanations in order to avoid confusion.

Although it's nowhere mentioned, this repository employed Ruby Sass, which is now deprecated and no longer mantained. We need to switch to Dart Sass, and update the build scripts accordingly (there are minor invocation-syntax differences).

• Adapt all Sass related scripts to Dart Sass:
  • SASS-BUILD.bat
  • SASS-WATCH.bat
• Remove the .sass-cache entry from .gitignore
• In docs-src/README.md add Dart Sass to the optional third party tools, and mention the switch from Ruby Sass.

(EDITED by @tajmone)

• In §2.5.1 there are the following typos.

  Bare in mind that you can use consecutive selections, at different times, to populated the list of selected labels: this technique may be useful for propagating specific attributes to affect the generation.

  Bare -> Bear, to populated -> to populate.

• In §2.6 there are the following typos.

  It is often reuired, mainly for style purposes, to respect capitalization rules — for instance, after a full stop.

  reuired -> required.

• Following that, there are two very similar versions of the same paragraph (already mentioned in #7)

  In order to solve this problem, the language provides the backslash keyword , which makes the program perform the capitalization of the very following terminal symbol, i.e. switching its first letter to uppercase.

  In order to solve this problem, the language provides the backslash keyword , which instructs the program to capitalize the first letter of the next terminal symbol encountered (if it isn’t already a capital letter).

  Of which I think the latter is the one to keep.

• In the next sentence there are two typos:

  Bare in mind that backslash capitalization is active until the following generated terminal symbol is encountered, therefore any other atom (epsilon, concatenation or the capitalization operator itself) encountred in the meantime will act as usual.

  bare -> bear and encountred -> encountered.

I've created the new Dashboard Project PML Docs Revision and moved therein all Issues proposing text revisions and improvements for the PML Spec documents (both EN and IT) — i.e. #8, #29, #32.

Right now I would like to focus on the imminent v1.1.1 release, which will fix the many typos in the English document and update the toolchain dependencies, and release it as soon as possible.

Contents revisions and improvements will take longer, so it makes more sense to pile up all revision proposal for some other future release in order to be able to work on them with more time at hand and without keeping on hold v1.1.1.

This Issue can be used to host a general discussion on revising the PML Docs contents (e.g. guidelines, ideas, etc.), whereas specific topics or sections will be dealt with in separate Issues.

In §2.6 Capitalization of the English PML doc there's a paragraph appearing twice:

In order to solve this problem, the language provides the backslash keyword \, which makes the program perform the capitalization of the very following terminal symbol, i.e. switching its first letter to uppercase.

In order to solve this problem, the language provides the backslash keyword \, which makes the program perform the capitalization of the very following terminal symbol, i.e. switching its first letter to uppercase.

We need to delete one occurrence.

Last-minute checlikst before merging into master the dev1.1.1 branch and creating the 1.1.1 release:

• polish/squash commits in dev1.1.1 branch to leave behind a clean history.
• Double-check the CHANGELOGs. (see #34)
• Check/fix PML sources:
  • Remove -rc from version (1.1.1-rc → 1.1.1-rc):
    • PML EN
    • PML IT
  • Edition date must match day of release (today):
    • PML EN
    • PML IT
  • Update CHANGELOG (PP comment block) at source end:
    • PML EN
    • PML IT
  • Rebuild both documents.
  • Copy them (again) to root folder (replacing current releases):
    • PML EN
    • PML IT
  • Copy them to archived/ folder:
    • polygen-spec_EN_1_1_1.html
    • polygen-spec_IT_1_1_1.html
    • Update archived/README.md
• Update README.md:
  • Update release badge to 1.1.1.
• Merge Squash dev1.1.1 into master.
• Create the 1.1.1 release.

The (Node.js) tool multiwatch is no longer available on NPM, so we need to remove all references to it from the repository and replace it.

• Find an alternative tool, or remove the watch scripts:
  • The onchange tool (Node.js) offers all the functionality of multiwatch, and much more.
  • Fix the scripts that depend on multiwatch:
    • docs-src/watch_EN.sh
    • docs-src/watch_IT.sh
• Amend docs-src/README.md:
  • multiwatch mentioned in Optional Third-Party Tools section.
  • Update all references to docs-src/watch_EN.sh and docs-src/watch_IT.sh.

Multiwatch was used to track changes to PML sources (markdown and CSS) and rebuild the document whenever changes were detected.

We need a replacemente tool, or to just drop the watch scripts altogehter (although they were quite handy during development).

In §3.1 Recursion of the English PML doc there are two consecutive paragraphs that have identical meaning:

Keep in mind then that it is up to you providing a non-recursive production somewhere in order to let the program stop recurring sooner or later, otherwise a cyclic recursion error will be generated by the grammar checker (see section 4.1.2).

Bare in mind that you’ll need to provide a non-recursive production somewhere along the line, in order to guarantee to the program an exit point from the recursion, at one point or another; otherwise, a cyclic recursion error will be generated by the grammar checker (see section 4.1.2).

Probably these are variations of the same paragraph left over from the editing stage, and one of the two was accidentally left there. We need to decide which of the two is better and delete the other one.

Alcune considerazioni sulla Polygen Meta Language Spec.

Alla luce degli innumerevoli problemi nella compilazione con OCaml (ulteriori ricerche mi hanno confermato che installare OCaml su Windows 10 è problematico), credo che la ristampa di questi documenti acquisti ulteriore importanza.

Una definizione formale della specifica PML, soprattutto in inglese, faciliterà il compito a chiunque volesse implementare Polygen in altri linguaggi — e credo che questa possibilità sia realistica visto che ho già individuato un simile tentativo in Haskell, ed esisteva anche un port per telefonini in passato.

Fosse anche che qualcuno dovesse implementarlo in qualche linguaggio di scripting (es: Python, Ruby, Javascript) per semplificarsi il lavoro sfruttando l'esistenza di librerie di lexing and parsing, sarebbe comunque ottimo.

Quanto ai binari Windows, credo che questi seguiteranno a funzionare per parecchi anni dato che Windows ha comunque sempre offerto la possibilità di eseguire applicazioni in modalità compatibilità, e per quanto riguarda la DLL di Cygwin, questa verrà sempre aggiornata dato l'elevato numeri di applicazioni che dipendono da essa. E comunque, non è detto che prima poi OCaml per Windows non venga rimesso a nuovo (anzi, direi che Andreas Hauptmann sta lavorando attivamente in quella direzione).

Alla fine dei conti, dato che ad oggi ci ritroviamo con dei binari Polygen funzionanti, vale la pena investire energie più nella direzione della documentazione che non dello sviluppo (o riscrittura) del Polygen stesso (soprattutto visti i molteplici problemi con OCaml).

Credo che se la documentazione inglese non fosse stata incompleta (nonché poco visibile e pubblicizzata) in tutti questi anni (oltre 10!) il Polygen si sarebbe diffuso molto di più nel mondo, e avremmo assistito a svariati tentativi di porting ad altri linguaggi. Il fatto che la documentazione inglese delle grammatiche fosse incompleta deve averne ostacolato l'uso (e quindi anche la diffusione) nel mondo anglofono.

Spero quindi che la ristampa di questi documenti, e la nuova edizione inglesa completa sulla PML possano dare una spinta di rinnovamento al Polygen.

Credo sarebbe utile in tal senso una chiarifica riguardo la licenza GPLv2. Essa, mi par di capire, concerne solo il programma e la documentazione, e non lo standard del metalinguaggio PML, giusto? Ossia, la spec di PML è libera, e chiunque può implementarla in altri linguaggi senza i vincoli della GPLv2?

Varrebbe la pena specificare questo punto in entrambi i documenti.

Altresì, andrebbe considerata l'idea di ufficializzare la spec in qualche modo, chiarendo quale sia il suo riferimento originale, di modo che eventuali varianti da essa possono essere chiaramente percepite come tali. Magari, alla fine del lavoro di ristampa, potresti clonare il progetto sotto il tuo account così da ufficializzarlo e auto-linkarlo nei documenti stessi. GitHub offre anche la possibilità di associare un sito a ciascun progetto, e si potrebbe pensare di pubblicare il documento di specifica inglese come sito pubblico.

In §2.11.2 Local envirnoments of the English PML doc the example production contains some Italian text:

EXAMPLE

S ::= \i am (X := Adj; Very ::= very [Very]; X ^ "," maybe Very X | definitely Very Adj) and Adj ;
Adj ::= handsome | nice ;

PRODUCES

I am handsome, maybe very handsome and nice
I am handsome, maybe very handsome and handsome
I am handsome, maybe very ... handsome and nice
I am handsome, maybe very ... handsome and handsome
I am nice, maybe very nice and handsome
I am nice, maybe very nice and nice
I am nice, maybe very ... nice and handsome
I am nice, maybe very ... nice and nice
I am decisamente very handsome and nice
I am decisamente very handsome and handsome
I am decisamente very .. handsome and nice
I am decisamente very .. handsome and handsome

Where decisamente should be replaced by definitely.

This was probably an omission during the adaptation of the original examples in the course of the new English revision of the spec.

In §2.12 Positional generation of the English PML doc there's a left over Italian sentence (already translated) which needs to be deleted:

È importante capire che la generazione posizionale non sostituisce il sistema di label, ma offre un’alternativa sintetica ad esso nei frequenti casi in cui verrebbe utilizzato per declinare termini. Non è difficile immaginare comunque come tale meccanismo possa tornare utile in altri contesti; ad esempio, a livello macroscopico, per specificare relazioni tra porzioni di una frase:

It’s important to understand that positional generation is not a substitute of the labels system, rather it’s a concise alternative to it for those frequent scenarios where it would be employed for declination purposes. Nonetheless, it’s easy to envisage how this feature could be useful in other contexts too; for example, on a macroscopic level, to specify relations between portions of a sentence:

• Fix PP macros to work with PP v2.14.1.
• Switch from PP v2.2.2 to v2.14.1 — (download page):
  • Update docs-src/tools/download.bat script.
  • Update PP version in READMEs:
    • docs-src/README.md
    • docs-src/tools/README.md

Updating from PP v2.2.2 to v2.14.1 breaks the macros, preventing building the documents (see #5 for details).

I should try to fix the issue locally, if it's easy to do so.

If not, we'll just keep using the current PP version and wait for the macros to be updated in the upstream pandoc-goodies repository.

Ho "pusshato" la bozza inglese sulla branch di lavoro:

• http://htmlpreview.github.io/?https://github.com/tajmone/polygen-docs/blob/draftwork/docs-src/polygen-spec_EN.html

(dovrei forse dire che l'ho «spinta sul ramo»? Ma italianizzando, si dice «pushare», «pusshare», «pusciàre» o «pucciare»? Ma i "pusher" non sono quelli che ... ? (sì, insomma, hai capito.) Non ti rendi conto di quanto sia assurda e astrusa la terminologia di Git finché non provi a tradurla o maneggiarla in italiano.)

Per ora mi sono limitato a riformattare gli esempi e varie ripuliture tramite search-&-replace.

Da una lettura veloce direi che servirebbe anche una riaggiustatina al testo, alcune frasi suonano un po' forzate in inglese. Pur restando fedele al testo italiano, vorrei rifrasare in uno stile più inglese. Ho carta bianca in merito?

Invece, riguardo i termini tecnici che subentreranno con la traduzione delle sezioni mancanti, non mancherò di interpellarti.

Bare in mind

Fix: bare -> bear 🐻

In §2.11.3 Static lexical scoping of the English PML doc there are three left over Italian sentences (already translated) which needs to be deleted:

Si badi infine che i binding sono ricorsivi, pertanto non è possibile fare riferimento alla definizione di un simbolo nell’ambiente in una ridefinizione in override del medesimo simbolo.

Bare also in mind that bindings are recursive, therefore you can’t refer to a symbol’s environment definition from within an override redifinition of the same symbol.

and, further on:

L’occorrenza di X nel secondo binding innestato viene dunque vista come una ricorsione, non come un riferimento alla X dell’ambiente padre.

The occurence of X inside the second inserted binding is thus seen as a recursion, not as a reference to the X of the parent environment.

Analogamente in presenza di una serie di binding in rapporto di mutua ricorsione:

Analogously, in the presence of a series of binding related by mutual recursion:

In §2.7 Permutation of both the English and Italian PML docs, two consecutive examples tend to appear to have identical Polygen sources, whereas in fact the second example employs round braces instead of curly ones (i.e. ("I" {will depart} {alone}) ; vs {"I" {will depart} {alone}} ;):

EXAMPLE

S ::= {in 10 minutes}^, {at 3 o'clock}^, {"I" {will depart} {alone}} ;

PRODUCES

in 10 minutes, at 3 o'clock, I will depart alone
at 3 o'clock, in 10 minutes, I will depart alone
in 10 minutes, I will depart alone, at 3 o'clock
at 3 o'clock, I will depart alone, in 10 minutes
I will depart alone, in 10 minutes, at 3 o'clock
I will depart alone, at 3 o'clock, in 10 minutes
in 10 minutes, at 3 o'clock, I alone will depart
at 3 o'clock, in 10 minutes, I alone will depart
in 10 minutes, I alone will depart, at 3 o'clock
at 3 o'clock, I alone will depart, in 10 minutes
I alone will depart, in 10 minutes, at 3 o'clock
I alone will depart, at 3 o'clock, in 10 minutes

EXAMPLE

S ::= {in 10 minutes}^, {at 3 o'clock}^, ("I" {will depart} {alone}) ;
PRODUCES

in 10 minutes, at 3 o'clock, I will depart alone
at 3 o'clock, in 10 minutes, I will depart alone
in 10 minutes, at 3 o'clock, I alone will depart
at 3 o'clock, in 10 minutes, I alone will depart

Since it's quite possible that the average reader might not detect the subtle difference between the use of round/curly braces in the two source examples (they look similar, especially with medium font sizes) it might be worth adding an explicit note to highlight the difference between the two examples.

In §2.13 Iteration of the English PML doc there's a left over Italian sentence (already translated) which needs to be deleted:

Si potrebbe ritenere ragionevole che venisse iterata sempre la stessa generazione, ma non è così (come dalle regole di traduzione ¿sec:regole-traduzione?), poiché nella maggior parte dei frangenti il comportamento di cui sopra è preveribile ed inoltre semanticamente affine all’analogo costrutto EBNF. È possibile tuttavia ottenere l’effetto ipotizzato in maniera piuttosto semplice sfruttando il binding forte (vedi section ¿sec:sospensioni?):

One might have — quite reasonably so — expected to see the same generation being iterated every time, but this is not the case (as stated in the translation rules 5.5) because in most scenarios the behavior of the above example is the preferable one instead, and also because it bears semantic affinity with its analogous EBNF contruct. It’s nevertheless possible to achieve the former behavior in a rather simple manner, by exploiting strong binding (see section 2.10.2):

In §4.1.5 Overriding of non-terminal symbols of the English PML Specs, there's an untranslated occurrence of the word EXAMPLE in Italian:

ESEMPIO

S ::= (A ::= apple | orange | banana ; A ::= tangerine | melon ; a ripe A) ; 

(EDITED by @tajmone)

• In §2.4 there is the following odd sentence:

  Polygen provides a powerful unfolding system which, in general, allows to raise to the level of the current sequence a series of productions which would otherwise be folded (either by a subproduction or a non-terminal symbol) .

  I think that the Italian phrase structure was kept while translating the text into english:

  Il Polygen dispone di un potente sottosistema di unfolding che, in generale, permette di portare al livello della sequenza corrente una serie di produzioni altrimenti raccolte in una sottoproduzione o da un simbolo non terminale.

  If we move some bits around the sentence flows better

  Polygen provides a powerful unfolding system which, in general, allows to raise a series of productions (which would otherwise be folded either by a subproduction or a non-terminal symbol) to the level of the current sequence.

• I'd also improve this other sentence by adding a verb to the secondary sentence:

  Not every atom supports unfolding though, only those for which this operation makes sense: refer to section 5.1 for a syntactical formalization of this subset.

  Not every atom supports unfolding though, only those for which this operation makes sense do: refer to section 5.1 for a syntactical formalization of this subset.

• In §2.4.1, there is the following typo:

  but this way we loose the original architecture, which folded all dog breeds within a dedicated non-terminal symbol, and increases drastically the amount of editing work required.

  loose -> lose

• and the order of words should be adjusted for a better flow:

  but this way we lose the original architecture, which folded all dog breeds within a dedicated non-terminal symbol, and drastically increases the amount of editing work required.

• I also think this sentence can be improved:

  In order to solve this problem (which is an instance of the wider problem of irregular distribution of probability affecting subproductions)

  I think that "broader" would be a better fit in place of "wider".

• [MOVED TO → Issue #32] In §2.4.2 the second example uses labels, a concept that has not yet been introduced to the reader. Maybe we can remove them from the example, so it becomes less confusing? (Actually, this suggestion also applies to the italian documentation).

• In §2.4.5 there is the following typo:

  As stated in section 2.8, deep unfolding leads to a subproduction where everything has been flatted out.

  flatted -> flattened.

In §2.3 there are the following typos:

The set of produceable sentences is as expected; indeed, the definition for the non-terminal symbol S is internally interpretet as follows:

interpretet -> interpreted

the requested increases and decreases in probability are proportionally fullfilled

fullfilled -> fulfilled.

In §2.12 Positional generation of PML English doc there's a typo that needs fixing:

As a workaround to the burder of having to specify [...]

Fix: burder → burden

Convert the dependencies downloader script from batch to Bash script, so we can leverage the curl and tar tools that ship with Git for Windows

• Convert download.bat to download.sh:
  • Ensure that the script works with the cURL that ships with Git for Windows.
  • Replace the calls to 7z.exe with Tar.
• Amend docs-src/README.md accordingly.

With this solution end users won't have to install any dependencies to run the downloader script.

I quick glance into tar seems to confirm that it should support all the archive formats involved, but I need to actually test it against the archives of the dependencies.

Notes

Originally, I though we could keep using a batch script and switch from 7-Zip to Tar, since Windows 10 now ships with native versions of both cURL and Tar (bsdtar, using libarchive).

But as an afterthought, I think it's better to use Bash scripts instead, for various reasons:

• It will work with any Windows edition that support Git for Windows.
• It allows integrating download.sh with the other scripts in the toolchain.
• In the future, download.sh could be tweaked to support fetching the dependencies for other OSs too.
  • Once it supports also on Ubuntu, it could be added to the Travis CI build (right now, to test the builds we'd have to run a separate job on Windows Server).

References

• MS Dev Blogs » Tar and Curl Come to Windows!
• MS Tech Community » Tar and Curl Come to Windows!
• libarchive.org

Before the PML Specs Ed. v1.1.1 updated, I should add to the repository EditorConfig settings to ensure code styles consistency across the project's sources.

• EditorConfig setup:
  • Create .editorconfig settings file and add definitions for:
    • Repository settings files.
    • GitHub (*.md) docs
    • pandoc (*.markdown) markdown source.
    • PP files (*.pp).
    • Sass (*.scss) and CSS (*.css) files.
    • Batch scripts (*.bat).
    • Bash scripts (*.sh).
    • Plaintext files.
  • Amend sources files to ensure their compliance to the EditorConfig settings until they pass the EClint validation test.
  • Add custom validation script (via EClint).
• Travis CI setup:
  • Enable Travis CI validation via EClint.
  • Add Travis CI status badge to README.
• Document EditorConfig settings and the need to abide to code styles conventions.

This will allow most modern editors to automatically pick-up the code settings (natively or via a third party plug-in), so contributors won't have to worry about potential conflicts with their local settings and the project's requirements.

In addition, we'll be able to use the EClint tool (Node.js) to validate all commits and PRs via Travis CI, thus intercepting and preventing commits that would add noise to the project due to whitespace differences (inconsistent indentantion, trailing spaces, etc.).

• In §2.11.2 and following I see more occurrences of the "bare" typo. I remember that you @tajmone mentioned doing a search and replace, so maybe I'm not looking at the latest revision?

In §2.11.3 there are many Italian leftover paragraphs in the documentation:

• "Si badi infine che [...]",
• "L'occorrenza di X [...]",
• "Analogamente in presenza [...]".

Also, still in §2.11.3 I think there is a typo:

The occurence of X inside the second inserted binding

should be

The occurrence of X inside the second nested biding

• I still see the "occurence" typo in the docs. 👀

In §2.12, there are the following typos:

• "burer" -> "burden"
• I would also suggest rephrasing this sentence

This feature — which is operationally equivalent to using labels and selections, but less verbose — allows to express in an extremely concise way groups of suffixes, declinations, conjucations, etc.

to

This feature — which is operationally equivalent to using labels and selections, but less verbose — allows to express groups of suffixes, declinations, conjucations, etc, in an extremely concise way

• Leftover Italian paragraph "È importante capire che [...]"

In §2.13:

• Leftover Italian paragraph: "Si potrebbe ritenere ragionevole [...]".
• I think that the sentence would sound better

One might have — quite reasonably so — expected to see

as

One might have — quite reasonably — expected to see

or as

One might have expected — quite reasonably — to see

I can't really offer an explanation to why, but I believe it flows better.