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

PMLC: Add Opts to Launch Manuals #77

Open tajmone opened 2 years ago

tajmone commented 2 years ago

Christian, it would be nice to have dedicated options in PMLC to open up a bundled version of the PML Reference Manual and PML User Manual, respectively, which always matches the PMLC version.

Since the online version of these docs don't always match the latest release, and because end users might be sticking to a specific (older) version of PML for their work, it would be a great service to grant quick access to local copies of the docs, matching the exact PMLC version being used.

I'm aware that the PML package does contain the PML Reference Manual sources (but not the PML User Manual) and that users could build the document themselves in a few steps, but having a PMLC option to open up both docs in the browser would be a much easier way to go about it.

Something like:

pmlc userman
pmlc refman
pml-lang commented 2 years ago

The reference manual and user manual are both already bundled with the distribution. They are stored in the following sub-directories of the distribution: docs\ref_manual\index.html docs\user_manual\index.html

However, note that the location of the manuals will change in the next version. This will be necessary because the new version will be distributed as a single standalone exe file. At first execution, the manuals will automatically be stored into a version-dependant APPDATA sub-directory, together with other files used by PML (default CSS files, etc.)

having a PMLC option to open up both docs in the browser would be a much easier way to go about it. Something like: pmlc userman pmlc refman

Yes! Excellent idea. This would be much more convenient for the user.

users could build the document themselves in a few steps

This option is currently available only for the reference manual. This option will remain in the new version. The reason for allowing the user to create the reference manual (although it's available already in a specific directory) was to integrate user-defined-nodes in the reference manual (not done yet).

tajmone commented 2 years ago

At first execution, the manuals will automatically be stored into a version-dependant APPDATA sub-directory, together with other files used by PML (default CSS files, etc.)

It would be nice if PMLC help will also print information about the location of these folders and files, i.e. for completeness sake. This would also be quite useful if these folder were to change in the future (e.g. their folder names, or filenames, etc.).

was to integrate user-defined-nodes in the reference manual (not done yet).

you mean like if there are some user defined nodes like a third party library, i.e. that they will end up being documented in the local PML Reference Manual? or is it just that you'll integrate those parts of the PDML documentation that deal with custom nodes?

The idea of being able to generate reference docs for custom nodes is interesting though, especially if these were distributed as some sort of reusable library — i.e. having a way to distinguish these type of reusable assets, and provide some means of documenting them, either via in-source comments or a PML document with a special naming convention that can be automatically associated as being the documentation of a user component. This would mean that end users would be able to generate a single documentation file for their entire library collection.

pml-lang commented 2 years ago

It would be nice if PMLC help will also print information about the location of these folders and files

In the new version I've already implement a new CLI command pmlc info. This command displays various useful information about PML, including the location of the data directory on the user's machine.

Here is an output example of the new version under construction:

           App name: PML Companion
         Short name: PMLC
            Version: 3.0.0
       Version date: 2022-03-08
   Shared data dir.: C:\Users\NAME\AppData\Roaming\PMLC_3
       Working dir.: C:\tests\PML\quick_test
            OS name: Windows 11
      Java version.: 17.0.2

you mean like if there are some user defined nodes like a third party library, i.e. that they will end up being documented in the local PML Reference Manual?

Yes, exactly.

This would mean that end users would be able to generate a single documentation file for their entire library collection.

Yes, that's the final goal.