CSS Option Treats Everything As CSS #93
Comments
|
P.S. — the above issue actually does expose private data and source files. I've just realized that the the |
|
The fact that PMLC creates a copy of the stylesheet indicated via the
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:
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 |
Yes, will be done in the next version. Only files with extension
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). |
I can't think of any other extension,
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 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 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:
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. |
Default values for CLI options of command
The doc for CLI option The default value is defined as follows:
There is currently no CLI option to define the CSS output directory. It is always sub-directory
The doc for CLI option A comma separated list of resources that will be copied into the output directory. Hence the user can control where to store JS files, media files, and any other assets.
Yes. For missing options I suggest to open an issue (as done already here).
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
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)
Agreed. |
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 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 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. |
Add to `Rakefile` new `HackCssPath()` function to strip the `css/` prefix from CSS file paths within PMLC generated HTML files, in order to force stylesheets test docs of the `:css` task to use the CSS files created by Sass, instead of their copies created by PMLC within the `css/` subfolder. This hack allows us to benefit from full CSS-to-Sass debugging when inspecting the test documents in Chrome browser via the Dev Tools. For more info on this fix, see: pml-lang/pml-companion#93
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.
Great! |
Fixed in version 4.0.0. |
pml-lang
added
enhancement
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_HTMLand option--CSS_filesfollowed 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: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
.cssextensions.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
.cssextension, 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.).
The text was updated successfully, but these errors were encountered: