search

pml-lang / pml-companion

Java source code of the 'PML Companion (PMLC)'
https://www.pml-lang.dev
GNU General Public License v2.0
22 stars 1 forks source link

PML Docs: Add Version Info to Ref Man & Create Docs Archive #79

Open tajmone opened 2 years ago

tajmone commented 2 years ago

PML Reference Manual: Add Version Info

Please, add to the online PML Reference Manual the PML version it refers to, like it's done with the PML User Manual.

Currently, it's hard to tell what PML version the Ref Man refers to, since it only mentions the publishing (last edited?) date.

The way the User Man displays the info summary via a table just below the document title is very helpful, the same should be done for the Ref Man too.

Docs Archive

It would also be quite useful if you could provide an online archive of all the documents and JSON-tags files of the various PML releases, for consultation and comparison purposes — especially useful for developers of PML related projects, so they can keep track of the syntax changes across releases, but also for users who need to migrate documentation projects created for older versions of PML and need to focus on the syntax changes.

Since each version of the documentation source files is specific to the PML syntax of the release it refers to, building them from source is not an option for it would require to install each PML release (for pre-3.0.0 PML versions, which relied on an installer) — hence the need for their pre-converted HTML versions to be stored somewhere accessible.

Under PML Website …

If space on the official PML website is not a concern, you could just add the HTML docs adopting a version-based naming convention, e.g.:

In Dedicated Repository …

Alternatively, you could just create a dedicated repository with all these HTML and JSON docs (e.g. pml-docs-archive) and serve them online via GitHub Pages, so end users can either consult them online or clone the repository locally.

pml-lang commented 2 years ago

The way the User Man displays the info summary via a table just below the document title is very helpful, the same should be done for the Ref Man too.

It's done already in my local dev branch. Will be included in the next version 3.

provide an online archive of all the documents and JSON-tags files of the various PML releases

Yes, should be done.

If space on the official PML website is not a concern, you could just add the HTML docs adopting a version-based naming convention

Yes, that would probably be the most convenient option. And there should be an index page with the whole list, sorted by descending version number.

tajmone commented 2 years ago

It's done already in my local dev branch. Will be included in the next version 3.

I've never quite understood why you handle all development in local branches instead of public dev branches.

This morning I went to check if I could contribute to the documentation and fix some text problems in PML 3.0.0's Changelog, but noticed that there are no dev branches, just main, so I gave up.

Usually repositories open to contributions host all the dev branches (actually, they even setup a CI service to provide nightly builds of the latest dev branch, either daily or weekly), and provide a CONTRIBUTING.md document with guidelines on how to contribute and the adopted naming convention for the various dev branches (baseline branch, feature branches, etc.).

Landing on a repository that doesn't expose dev branches and contributors' guidelines gives the impression that the project is not open to third party contributions at all (many repos are indeed so, either because they are personal projects, proprietary or simply aren't expecting anyone to contribute) but AFAIK this is not the case with PML (on the contrary, much has been planned around the expectation of contributions).

Now that PML is entirely in Java (no longer in PPL) I'm open to the idea of attempting code contributions too, not just documentation. But if only the main branch is publicly available contributions are not possible since any PR would conflict with your local dev branches, being out of synch.

pml-lang commented 2 years ago

Usually repositories open to contributions host all the dev branches

IMO there was no need to have a public dev branch prior to version 3, when PMLC was written in PPL.

But now that everything is in Java, and the code reorganized to facilitate contributions, there should be a public dev branch too. I plan to do that after version 3 is published.

tajmone commented 2 years ago

IMO there was no need to have a public dev branch prior to version 3, when PMLC was written in PPL.

Since the documentation it's embedded in the source it would have allowed contributions to the documentation text, even if just typo fixes. Also, the PML 3.0 Changelog needs some serious English text revision, which won't happen if the dev branch is made public only after its public release.

pml-lang commented 2 years ago

the PML 3.0 Changelog needs some serious English text revision

I've just created branch develop for the Changelog. Contributions are welcome! I will create develop branches for the other repositories too.