-
Notifications
You must be signed in to change notification settings - Fork 1
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Stylesheets Copy-&-Subfolder Prevents CSS Debugging #94
Comments
I agree that solution 2 is a bad idea. I suggest to add CLI option The default value for this option is If this option is explicitly set to If this option is set to Another suggestion: Instead of only copying |
Sounds good.
The problem with this solution is that you then can only enforce linking-over-copy when CSS assets are within the same folder as the HTML file, which is not so flexible.
It's not clear whether this parameter can be passed multiple times on a single invocation or just once; if the former was the case, then it would be possible to specify both a custom CSS folder and the linking-over-copy option. Ideally, end users should be able to have total control over individual CSS files, both in terms of which ones get just linked and which ones are also copied to target path(s) — indeed, in complex projects there might be multiple folders for CSS files, e.g. to separate shared stylesheets from ad hoc stylesheets, especially in multi-page documents organized into separate subfolders according to chapter (or part, or whichever other partitioning device). Since in a field as vast as digital publishing is hard to pinpoint any single "works for all" solution that generalized all the possible uses and needs, IMO it's better to keep options as flexible and open as possible (along with simple and reasonable defaults). Probably the solution here should consist in the ability to specify multiple CSS files sets, and for each set whether it should also be copied to the target path or just linked. If the current It's not an easy choice, since the parameter value could be a directory, a file, multiple files (multiple directories too?), and we need to keep into account that OSs often differ when it comes to filesystem convention. Currently this parameter uses the comma character The point is that we should avoid at all costs any platform specific traps here, like OS dependent escaping conventions and rules (Win uses So, assuming multiple All these ramifications needs to be kept into consideration (not only for this specific parameter, but in general), especially since ultimately end users will be give the choice to pass options via CLI parameters, setting files, as well as within the PML source What I'm saying is that since we're looking into how to handle both simple and advanced uses for the E.g. above you proposed that the The
I don't see the benefits of this, since the I just don't see it as a viable solution. Currently I've solved the problem in the PML Playground by adding to its Rakefile a dedicated function that sanitizes the HTML files generated by PMLC by removing the Fortunately, with Ruby and Rake it's possible to come up with such solutions fairly easily, and in a cross-platform manner too. But my guess is that with tools like GNU Make or Gradle such a workaround would have been a nightmare of external dependencies and cross-platform yak shavings — which is why I deem it worth investing energy in empowering PMLC as much as possible, so it can be as self-sufficient as possible, even in complex projects. |
Rake Workaround in PlaceI've just pushed to the PML Playground repo the temporary fix for this problem via a new https://github.com/tajmone/pml-playground/blob/dacd5d0/Rakefile#L96 So, anyone in need of a quick and dirty solution to the current limitation can reuse the Ruby/Rake function from the above link, or adapt it according to need. Probably not the most elegant solution (and surely I don't claim any Ruby idiomacy, let alone eloquence in the lang), but at least it works — and I've tried to keep the time-penalty down to the minimum by avoiding loading the entire file in memory, but working a line-at-the-time with a temporary out file along with the original, which should circumvent big heap allocations and result in faster execution times. In any case, the added time penalty on the Rake build is barely noticeable so far (but there aren't many stylesheets to build the test docs against either). |
To achieve this I suggest to also add CLI parameter Taking into account all other useful remarks, the final documentation for parameters Parameter
|
I like your proposal and I think that having a separate parameter to handle CSS lists that need to be linked-to only is simpler than having a boolean parameter chained to the list. Below are some thoughts on things which I'm not entirely convinced of. Valid CSS
You mentioned this twice. But how is PMLC going to validate a CSS file? And why should it? I might add. It's the responsibility of the user to ensure that the CSS files which he picks are valid, not the job of PMLC. Also, during my trial and errors, when I realized that PMLC was copying and linking every file from the specified CSS folder, including non-CSS files, this didn't affect the final HTML document — the files which weren't CSS were just ignored, silently; only the browser Dev Tools would report errors for them, but they didn't impact negatively the document, they were just ignored. Parameter
|
Thanks.
PMLC does not validate CSS files.
Yes, that's what I wanted to express with "Each file must be a valid CSS file." Ok, to eliminate the confusion I'll replace it with: "Each file must be a valid CSS file, but PMLC does not check this."
I started with Maybe a better name would be
I totally agree with this basic principle. The reason I added
Yes, but only in Linux. Ok, let's support only the comma as separator.
This is OS-dependent and also depends on where the parameter is defined. In the CLI, a single string value must be assigned to each parameter. If the value contains spaces or other special characters like quotes, then the OS-specific rules must be applied by the user. For example, a parameter containing spaces must be enclosed with quotes on Windows (e.g. (Note: Just now I've discovered that I forgot to quote parameter values in the "Note 1" section of my previous comment. It's now fixed.) If a parameter is defined in a PDML document (e.g. in a PML
Ok. Then let's do what I suggested in my previous comment: "... allow a file or directory path. In case of a directory path, the output file name (without the .html extension) would be the same as the input file name (without the .pml extension)". If there are no other issues, I'll post an updated description for the three parameters. |
CSS Validation
I think the best way to avoid confusion is to not say anything beyond "a CSS file" — why on earth would anyone wish to link an invalid CSS file? It should be a fair assumption that PML end users have a propensity to honor standards, and that they expect them to function. The problem with adding unneeded qualifiers is that the reader is then left to wander whether in their absence some broader interpretation is due, or if they are missing out some other key categories. E.g. in the PML docs I've come across a few places where it mentions "a formal PML node", which left me with the hanging question "which are the informal nodes?" — and honestly, that question was burning so much in the back of my mind that it distracted me from the rest of my reading, because I kept wondering whether I had missed out some basic definitions. Formal compared to what? In writing in general, but in tech docs in particular, similar qualifier call of a clarification, be it a footnote explaining the difference or a link to a glossary.
|
Yes, ok.
In the world of programming, the term 'formal argument' or 'formal parameter' is commonly used to refer to its definition in the function. It consists of a name, a type, maybe a default value, description, etc. Wikipedia puts it like this: In a similar way, I use the term 'formal PML node' to refer to its definition (name, supported attributes, etc.).
I'm not sure to correctly understand the meaning of these three options (are they lists of paths or boolean values?), but if they are paths: I prefer to not rename To avoid the ambiguity with 'link', we could use And for the third type of directory/file list, I suggest
If users later ask to support the comma in paths, we could add the rule that two consecutive commas in a path is replaced with one comma (similar to how Excel allows to escape double-quotes). Adding this rule would be a non-breaking change, unless somebody used two consecutive commas in a path. |
Formal Nodes
Indeed, these terms are the subject of much confusion even in the "formal" programming jargon, otherwise the WikiPedia page you cited wouldn't use qualifiers like "sometimes called". Matter of fact, many people prefer to use the terms "parameter" and "argument" to distinguish between the two, rather than resorting to terms like "formal" — but then, this is a highly opinionated topic, like tabs vs spaces, which is not worth pursuing. I think the problem here is that PML is not aimed at software engineers but writers, so any assumptions regarding such specialized jargon are misplaced. I'm also not convinced that the comparison between nodes and parameters stands its ground, a node is more of a reserved keyword/token in PML, and unlike parameters it's not subject to different uses in the documentation and real practice (even attributes, being key-value pairs, don't quite fall in the same category).
In that case why not just say "formally defined node". I still don't see how this qualification improves the reading though — unless there's a real need to mention this "formality" to make a clear distinction between other cases/context where the current feature being documented doesn't apply, it should be just "a node".
The
I could, but I still don't see the point nor the benefits of bringing over to PML and the writers' world the semantic problems that afflict the software engineering community — most of which, BTW, exist only because of the different overlapping academic fields where these terms are used, where mathematicians, language engineers, and experts from other fields, all enforce their field-specific argot terms to describe the same things. PML being a syntax (and not a programming language), and its users being writers and editors, it might be more beneficial to stick to down-to-earth terms — the distinction between node and tag might already be enough of a technical burden. Here's an example of how the term "formal node" is used in the Ref Man (Lenient Parsing):
The question is how does the "formal" qualifier contribute to this sentence specifically? I underline specifically because since we rarely see this qualifier used elsewhere then we'll assume that in this context it contributes an important distinction. I don't see how interpreting "formal node" as "a definition or specification for a node" helps me understand better lenient parsing rules — on the contrary, I might think that I can't understand to which nodes they apply until I understand the distinction between formal and informal nodes. I'm not trying to "make an issue of small things", but I'm well aware how easy it can be for us developers to forget that our daily-work tech knowledge and jargon might not within the reach of end users, especially when dealing with a syntax which is aimed at writers, not programmers. I'm not even sure that it's safe to assume that a writer knows what a tree structure is, so terms like "node" and "attributes" might come as new challenges for someone who had a formal education in literature. E.g. from the PML User Manual: Also, what ultimately makes any document a good and flawless reading are the small details, and the care that goes into them to avoid unneeded "bumps".
A good litmus test for the above definition would be to go to a fiction writers convention and, during the lunch break, hand them over the above three lines and ask each person how it interprets it. My bet is that unless they have studies computer data structures or semiotics they won't have the slightest clue about arborific structures and their terminology, let alone that documents can be represented as if "they were trees". Usually writers think of documents as being organized in parts, chapters, scenes and paragraphs, and that's usually what word processors try to mimic too. The paradigm shift from the "common document model" to that of a Tree structure might require some effort and adjustment from someone who has never touched upon these topics — and, obviously, it's a required shift in order to properly understand how PML nodes work. I'm just saying that we should keep the documentation simple, remind ourselves that it's written for the benefit of the average user, so we should avoid introducing too many technical terms, except in "to learn more about..." links for the curious or savvy. This might require us to be less formal and more forthcoming in how we write, even if this might mean longer text contents, where the exceptions are fully explained rather than relying on formalism or specialistic jargon. But I also still fail to see the benefits of using "formal PML node". CSS Parameters
Yes, they are all intended for paths (dirs and/or files).
Even if you don't like "deploy" you could use some other term, but it's better having a fully qualified parameter than a non-qualified one — True, the typical user/writer might not know what "deploy" means in this context, but when it comes to parameters it's never a guessing game either, it's about useful mnemonics after having read the
The breaking change can be avoided by keeping a deprecated alias in place until the next MAJOR release, which would actually be better than an abrupt change of a parameter name from one incarnation to the other, since it allows a grace time to adapt scripts.
I like it, it's better than using the ambiguous "link". Probably both the terms "undeployed" and "unbundled" are puzzling for the non-tech user, but at least the former is less ambiguous to tech guys, since "bundling" calls to mind complex packaging and delivery, whereas "deploying" probably makes more sense in this context.
Sure, whatever is more consistent in PMLC parameters. |
Indeed. Good point!
It is now documented (since version 3 IRC), and it's a formal node like the other ones.
The term "formal node" is used only once in the whole PML website (but it's in the User Manual, not the Ref Man). I've (locally) changed:
... to:
Hence, the term "formal node" will no more be used in the next version of the PML website.
LOL! That would be a lot of fun (just kidding).
I see what you mean. We should indeed improve the manuals to make them more understandable for non-tech people (e.g. explain technical terms in side notes, or add links to easy-to-understand additional information).
I agree 100%. I will keep this in mind. And any PRs to improve the manuals and make them simpler are very welcome. |
I actually meant it. This is how a simple marketing research would be carried out. Indy developers, unlike companies who have a dedicated marketing research division, have to face the problem how being in touch with their target audience. When software developers create tools for developers it's easier, since they are members of the target audience themselves. Video game developing is easier, since we all tend to understand games and fun, but when targeting specific age groups you'd also need to carry out some on-the-ground research to get real feedback. But when it comes to developing tools dedicated to specific fields of application or jobs, it's really important to be in touch with the target audience and receive constant feedback. E.g. I've seen many editors for novelists, and couldn't avoid noticing that those developed by non-writers Indy developers didn't seem to match the real needs and work process of fiction writers, whereas the good ones where created by developers who were married to a novelist, and the novelists which is currently considered the best one was created by a software engineer who is a fiction writer in his free time. For some reasons, often developers chose to create tools for fields which they don't operate in, maybe because it's a good market niche, or for run, or other reasons. Another such example would be pixel art drawing tools, which is a niche small enough not to catch the interest of big corporations (like Adobe, etc.) so these tools are mostly developed by independent programmers. I was surprised to discover that in almost all cases the developers of these tools are not into computer graphics themselves, nor into drawing in general, which explains why these tools lack in features related to the drawing process and focus mainly on technical aspects of pixels rendition and manipulation — but there's much more to drawing than that. In our case, the target users for PML probably fall into different categories, but once we have clearly identified them it would be a good idea to find a way to get in touch with them in order to have a live feedback on how they use the tool, and work with writing in general. Community feedback via product forums, Issues, etc., only gives you insights into actual users of the product, but not of the target user base. If our target users where fiction writers (for the sake of example) then finding a way to get in contact with them would be most useful. Since novelists works independently, from home, the only way would be to go to conventions, meetings, etc., which would give us an opportunity to ask them to show us how they work on their laptops, which tools they use and how they use, and to see how they relate to PML, its documentation, etc. Alternatively, we could try to find some online communities where they gather and share knowledge, and present PML to them and ask for feedback. But live encounters are far better IMO, since as a developer you can learn a lot by watching how a user works, how he/she struggle with interfaces, etc. Developers can see "missing things" which users might not be aware of, simply because they have never seen features available in other tools, which might be borrowed and implemented to fulfill such needs. |
I totally agree. PML should evolve based of the real needs reported by real users. For example, Joel Spolsky puts it like this: "Nothing works better than just improving your product. Make great software that people want and improve it constantly. Talk to your customers (users) and listen. Find out what they need."
Yes! Definitely. |
Problem Description
As of PMLC 3.1.0, the new
--CSS_files
option always copies the specified stylesheets into acss/
subfolder created by PMLC, which hinders development of custom stylesheets when using CSS compilers like Sass, LESS, etc.When compiling to CSS, Sass also generates the required
.css.map
files, and at the end of each output CSS adds a comment containing a link to its corresponding map file, e.g.:/*# sourceMappingURL=pml-default.css.map */
These CSS map files allow developers to inspect and debug their stylesheets directly in their browser via its Developer Tools, which in most modern browsers include support for CSS maps and Sass/Less sources, which means that the end users are shown the real-use effect of custom CSS definitions directly pointing to their Sass sources and modules, not just the compiled CSS output.
But because the PMLC generated HTML documents are using a copy of the
.css
files (located in thecss/
subfolder) instead of the original CSS files generated by Sass, the CSS map links in these comments won't be pointing to the correct.css.map
files, thus breaking the advanced debugging features of browsers Dev Tools (e.g. Chrome).Required Solutions
We need either:
p2h
option, allowing end users to bypass the CSS-copying stage by having PMLC simply link to the original files specified in the--CSS_files
parameter, as they are, without creating copies.PMLC p2h
behavior when custom CSS files are specified via the--CSS_files
parameter — i.e. achieving the same as point (1) but without requiring additional CLI parameters.Solution (2) is probably a bad idea, since in most cases end users just want to employ the default stylesheets, or some custom stylesheets stored in PMLC data folders, where in both cases the idea is to create a copy of these stylesheet, which are just multi-use templates.
But even in these cases, it might be useful to be able to control where the CSS file copies end up — i.e. being able to bypass the
css/
subfoldering convention by either storing them in the same path as the HTML file, or in a custom folder with any arbitrary name.But it's clearly important to be able to inform PMLC when a set of custom CSS files need to be copied and linked in the final HTML docs, and when they need to be linked only instead — ideally, PMLC should allow even a combination of both, via different parameters that can be used alongside.
Current Workarounds
Currently there are three possible workarounds to this, all of which require post-PMLC interventions:
Tweak the generated HTML files, substituting all CSS paths within their headers, e.g.:
by stripping the
css/
path segment:Tweak the CSS copies within the
css/
subfolder, substituting all CSS map paths within their end comment, e.g.:/*# sourceMappingURL=pml-default.css.map */
by adding a
../
to the CSS path in order to seek for it in the parent-directory, where the Sass sources are usually located too, along with the original CSS files:/*# sourceMappingURL=../pml-default.css.map */
Copy into the
css/
folder all the Sass sources too (including their modules), so that the CSS map paths can be matched to their sources again.Solution (1) is usually better, since it then allows to view changes to the Sass-generated CSS files by simply refreshing the HTML test docs. The only downside is when there are more HTML test documents involved than CSS files.
Solutions (2) and (3) both result in duplicate files, especially the latter which creates redundant copies not just of the CSS files but also all their Sass sources. Solution (3) also requires rebuilding the HTML test documents via PMLC and then copying again all Sass/CSS file when there are significant changes within the Sass sources and/or their modular structure.
As you can imagine, all of these solution are nothing more than hack-&-slash workarounds to the current limitation imposed by the PMLC native subfoldering conventions. Needless to say, in automated projects any of the above solutions is far from ideal and requires considerate extra scripting work to implement as a post PMLC conversion fix.
The text was updated successfully, but these errors were encountered: