CSS Option Treats Everything As CSS

[tajmone]

Not really a bug in PMLC itself, but a potential cause of bugs in the generated HTML files.

When invoking PMLC 3.1.0 with command PML_to_HTML and option --CSS_files followed by a directory, PMLC then treats any file within that directory as if it was a CSS file, regardless of its extension (or lack thereof), so in the generated HTML file you have something like this:

<meta name="generator" content="PML 3.1.0 (www.pml-lang.dev)" />
<title>Style Sheet Demo Document</title>
<link rel="stylesheet" href="css/demo.html">
<link rel="stylesheet" href="css/extended.html">
<link rel="stylesheet" href="css/pml-default.css">
<link rel="stylesheet" href="css/pml-default.css.map">
<link rel="stylesheet" href="css/pml-default.scss">
<link rel="stylesheet" href="css/pml-print-default.css" media="print">
<link rel="stylesheet" href="css/pml-print-default.css.map" media="print">
<link rel="stylesheet" href="css/pml-print-default.scss" media="print">

This is extremely inconvenient for any developer, since it forces them to specify CSS files individually, whereas it would be convenient to just pass a folder path and expect PMLC to selectively include only files with the .css extensions.

Having a folder with CSS files only is counter intuitive for a developer, since Sass files, along with generated CSS maps for debugging stylesheets are usually kept in the same directory. So, the idea of having a "pure CSS folder" is rather naive, and in any case there's always the risk of end users forgetting some file behind, or temporary and system files (often hidden from the end user) in that folder ending up in the generated HTML being linked as a stylesheet.

In other words, it makes sense that PMLC should natively filter directory contents by the .css extension, and accept any individually specified file as is, regardless of its extension. This is IMO a sensible default, since it applies reasonable file-extension conventions for folder contents filtering, without preventing custom extensions being explicitly used for individual files.

Right now, passing a folder path doesn't seem neither practical nor safe, for it only makes sense if the folder contains CSS files only — which is rarely the case, and hard to guarantee since temporary files (including hidden files) can easily end up there, especially since browsers tend to create temporary files next to the CSS stylesheets when accessing the advanced developer tools (e.g. Chrome).

Blindly linking to any files in the CSS target folder could even potentially result in accidentally revealing personal data, or divulging source files (e.g. if the toolchain tracks the linked stylesheets to post-process them, etc.).

[tajmone]

P.S. — the above issue actually does expose private data and source files.

I've just realized that the the -css option actually copies all the files from the specified folder to the css/ folder which it generates. So, yes, in this case it's simply copying all its contents (which might be Git ignored in a project) to the output directory of the generated HTML document (which is not necessary Git ignored, and surely not expecting any unrelated files).

[tajmone]

The fact that PMLC creates a copy of the stylesheet indicated via the -css option has some impractical implication for developers:

• Recompiling the CSS from Sass won't have affect unless PMLC is also executed again, since the specified stylesheet has to be copied again.
• When debugging stylesheets, you loose the CSS map files created by Sass, which are crucial when working with browser developer tools (one has to manually copy them to the target css/ folder created by PMLC).
• Projects end up having duplicate CSS files.

While the idea behind PMLC creating a copy of the specified CSS makes sense when the user wants to reuse stylesheets stored in a library collection (i.e. stored in the default PMLC assets path), the above considerations should also be considered, because developers might need a quick solution to bypass these defaults and have a more "raw" approach to PML to HTML conversion:

• No output/ or css/ subfoldering conventions: all output files default to same folder as sources, unless otherwise specified.
• Any stylesheet indicated is meant to be used by the final document, as is — no copies, and the HTML source must be able to link relatively to the CSS file, even in projects with complex structures (i.e. having to navigate to parent directories first, if required).

Especially in complex projects which have various demos and a test suite, end users need to be able to have fine grain controls on these aspects.

If the default behavior is important to preserve because it facilitates basic users, and reflects the most common use cases, maybe it should be possible to have a -dev option to enforce different defaults, to accommodate advanced users too (without having to use tons of CLI options).

[pdml-lang]

expect PMLC to selectively include only files with the .css extensions.

Yes, will be done in the next version. Only files with extension css will be copied. Other files will be ignored. Or are there other file types that should be copied too by default?

Especially in complex projects which have various demos and a test suite, end users need to be able to have fine grain controls on these aspects.

IMO these are advanced options we should indeed add later. But to get it right, we first have to specify exactly what to do and what not to do (i.e. which CLI-options to add, and how do they work).

[tajmone]

Yes, will be done in the next version. Only files with extension css will be copied. Other files will be ignored. Or are there other file types that should be copied too by default?

I can't think of any other extension, .css is the standard. In any case, since any individual file passed by the user will be accepted (regardless of its extension), special cases could still be handled on a per-file basis; this proposal only concerns the default behavior on how to handle directories.

IMO these are advanced options we should indeed add later. But to get it right, we first have to specify exactly what to do and what not to do (i.e. which CLI-options to add, and how do they work).

The problem here is that I have no idea about the details of PMLC folder naming conventions when it comes to defaults, since they are not documented (or, if they are, they are sparsely documented here and there).

From what I've seen, I'm guessing that the current behavior is trying to simplify usage for the average (non tech) end user by having PMLC enforce some conventions upon the workflow, i.e. defaulting all output into the output/ subfolder, and all CSS files to css/ within the output folder.

Other than that, I'm in the dark as to any other conventions regarding other types of assets — where do they go? Will JS files and images go to a js/ and images/ subfolder, respectively? and how will PMLC discern between images and other assets types, by tracking all existing image extensions? and what about other types of assets?

Since each user has its own set of preferences, and because each different usage kind requires different defaults, I personally think its hard to enforce a standard that will work well for everyone because working on a single article, a website, a multi-page documentation or an eBook, are quite different tasks, each bearing its own ideal defaults.

I personally think that in general is better to default to a vanilla behavior, and offer options to customize it, rather than enforcing presets of a certain usage kind and having end users struggle with CLI options to overcome them.

Having said that, I do understand that the involved settings to control the workflow can be numerous indeed:

• Specify a CSS folder or sets of files which PML should copy and link to.
• Specify a CSS folder or sets of files which PML should simply link to.
• Specify an assets folder, a files list or file-matching pattern of assets which PML should copy to the output folder.
• Specify the output folder for generated contents (HTML files, along with any generated assets, like diagrams from ASCII definitions, etc).
• Specify which HTML templates to use.

And possibly other settings too.

But then, if PMLC could make use of "options files" which can be stored either in the PMLC data folder or within the project directory tree, end users will be able to create their custom settings files for common tasks and reuse across different projects, which would only require specifying the path of this file (or just its name, in case of data-folder stored settings) via single CLI option.

But then, still, this is something which requires careful planning and consideration, and brainstorming all the possible use cases and varying needs. And, quite frankly, since further changes to the CLI options will lead to breaking changes, I'm not sure whether this would result in more damage than good — the PML 3.x transition broke all existing projects not so long ago.

I strongly believe that this is a phase in which PML needs stability, so that people can feel safe adopting it. Breaking changes should only be introduced across MAJOR version bumps, and never within a same MAJOR incarnation — doing so destroys entirely the credibility of a tool, making it unusable in any long term projects.

Although it's a challenging task to keep up with features requests and advancement of any tool while keeping up with the non-breaking changes policy within MAJOR versions, the whole idea is that by having a thoroughly planned roadmap it should be possible to incrementally implement new features without breaking existing ones, and at the same work toward the next MAJOR release in order to make room for those features that demand breaking changes.

This approach is the only way to reassure end users that they can use a tool for their project and be able to update the tool without having to re-adapt their source projects.

From a developer's point of view, you have to juggle with all feedback and needs for change, on the one hand, and the need for stability on the other. The "next MAJOR version" is your safety anchor: you can project onto it all those improvements and fixes that can't go in the current incarnation due to breaking changes. There will always be a second a thought, a regretted feature, and some amazing (albeit backward-breaking) new proposed feature which is going to make PML better, but it will simply have to wait the next MAJOR release.

This way, you are granted sufficient time to start working ahead of time of the next incarnation, so that when its release time comes they have been already beta-tested and are production ready.

[pml-lang]

I have no idea about the details of PMLC folder naming conventions when it comes to defaults, since they are not documented

Default values for CLI options of command PML_to_HTML are documented here (look at fields Default Value and Description for each CLI option).

I'm guessing that ... defaulting all output into the output/ subfolder, and all CSS files to css/ within the output folder

The doc for CLI option output states:

The default value is defined as follows:

• If the input is a file, then the output will be 'output/{input_file_name}.html' (where {input_file_name} is replaced by the input file's name, without its extension).
• If the input is read from STDIN, then the output is written to STDOUT.
  If the value of this parameter is explicitly set to 'stdout', then the output is written to STDOUT

There is currently no CLI option to define the CSS output directory. It is always sub-directory css in the output directory.
But I've posted a suggestion for an additional option.

I'm in the dark as to any other conventions regarding other types of assets

The doc for CLI option resources states:

A comma separated list of resources that will be copied into the output directory.
Each resource can be a directory or file path. Each path can be absolute or relative.
If a directory is specified then all files in the directory are used, including files in subdirectories.
By default directory 'resources' in the current working directory is used.

Hence the user can control where to store JS files, media files, and any other assets.

I personally think that in general is better to default to a vanilla behavior, and offer options to customize it, rather than enforcing presets of a certain usage kind and having end users struggle with CLI options to overcome them.

Yes. For missing options I suggest to open an issue (as done already here).

But then, if PMLC could make use of "options files" which can be stored either in the PMLC data folder or within the project directory tree, end users will be able to create their custom settings files for common tasks and reuse across different projects, which would only require specifying the path of this file (or just its name, in case of data-folder stored settings) via single CLI option.

That will be implicitly supported in the CLI as soon as it's done in pp-libs. I need to re-implemnt (in Java) what was already done in PMLC version 1 that used PPL.

Alternatively you could use an options node in the PML document, imported with [u:insert_file ...].

Breaking changes should only be introduced across MAJOR version bumps, and never within a same MAJOR incarnation

After version 1.4.0 2021-04-16, breaking changes in PMLC only appeared in major versions. This will always be the case, as required by semantic versioning (which is now used in PMLC)

There will always be a second a thought, a regretted feature, and some amazing (albeit backward-breaking) new proposed feature which is going to make PML better, but it will simply have to wait the next MAJOR release.

Agreed.

[tajmone]

Default values for CLI options of command PML_to_HTML are documented here [...]
The doc for CLI option output states: [...]

Although the PMLC CLI opts are documented, that's the documentation I've been struggling with most. Partly, it's due to its formatting, especially the tables-packed info (which requires horizontal scrolling the sidebar), and partly because examples are often non exhaustive.

I'm planning to contribute to the contents of this guide, but first I must make sure I correctly understand the parameters, which is not always the case when it comes to edge cases.

Hopefully, now that CSS work in the Playground has resumed (and now that I've found a workaround to the css/ constrain by hacking the CSS paths, and can benefit from full Sass/CSS debugging in the browser) I should be able to come up with an alternative stylesheet, at least for the online documentation.

A better stylesheet might improve the documentation accessibility, because I realize that in my case I'm often misreading the docs due to typography being hard to read for me (my vision is badly impaired), but also because headings beyond <h4> are too small (<h6> is even smaller than the base typeface), so I often skip through section headings simply because I'm not seeing them while sifting through the docs.

In a local branch, I'm trying to improve the typography of the default CSS, by applying vertical rhythm, better font faces, and using margins and color to better distinguish between structural elements of the document (e.g. headings).

Good pagination can make the world difference in terms of how a document is accessible for constant consultation. Reference documentation is more intended for quick sifting and finding info than reading, so visual cues and good space management can really help there.

Well, now I'll get back to work on the PML Playground hack to fix the CSS paths, which ready to be published, only needs some source polishing and documenting, and by tonight we'll have full access to CSS debugging within the browser, showing the Sass sources of each style, not just the compiled CSS (which is really cool).

I wish there more than just 24 hours in a day (or, alternatively, more minutes in an hour, whichever is more realistic) so that I could give more to the project.

[pml-lang]

I'm planning to contribute to the contents of this guide

That would be great. Such documents should indeed be edited/improved by other people, because the creator of a product often omits (unconsciously) to explain what is obvious for him, but not for other people. I'll do my best to be more explicit in the future.

In a local branch, I'm trying to improve the typography of the default CSS, by applying vertical rhythm, better font faces, and using margins and color to better distinguish between structural elements of the document (e.g. headings).

Great!

[pml-lang]

Only files with extension css will be copied.

Fixed in version 4.0.0.