Replies: 2 comments 7 replies
-
Inline Text Styles
Already on my todo list :-). Easy to add in PML. Will be done in one of the next versions.
Yes. CriticMarkup Styles for Proofreading
Yes, this can be implemented quickly, if needed in the future. Bold vs Strong & Italic vs Emphasis
Yes, we should support both, as in HTML, because it makes sense. Sometimes, font-changing and semantic tags are needed in the same document. Suppose a writer wants to display emphasized text in red. To achieve this he changes the CSS for tag It is [em very important] to write the note in italics, like this: [i text of note in italics]. This is only possible (without hacks like using a span with a specific CSS class) if both tags are supported: If we support both tags, that won't change people's ubiquitous habit to use the much easier to type I wonder if we shouldn't 'promote' Alternative Tag NamesSee my comment from today here |
Beta Was this translation helpful? Give feedback.
-
The only carefeul consideration there would be about choosing adequate class names to allow fine grain CSS control (IMO).
Good, that would be the safest approach, without taking any opinionated position (even though that's necessary at times).
I think that often-used tags should be given higher precedence in short naming, in general, after all bold and italic where represented by one char in the original HTML spec. When other tags share the same initial letter, usually trimming them down to one syllable work ( But keeping some sort of "roadmap table" with all possible future candidates, and their PML tags representation might be a good idea, even if these will not be implemented anywhere soon (or ever), just to avoid future clashes. |
Beta Was this translation helpful? Give feedback.
-
|
Hey just stumbled upon PML and am considering if this would be interesting to support or make the primary form of inputting pages in the CMS I'm developing. Some things I wanted to mention/ask. I couldn't find, on the website, how to do inline text styles apart from italic, though I understand the project is still in its early days and active development, but from the freeCodeCamp article (that's how I learned about PML in the first place it looks like you did it like this Personally I think the square ones seem to look cleaner so I think I prefer them 👍 hmm writing it out like this it might be kinda confusing but also more concise keeping you from "bracket hell" when you for example would want to write something bold, italic and striked through 🤯 maybe like instead of The tilde/squiggly Also as a side note: I found it kind of unnecessary complicated to find the GitHub link from the website, I think it could be more prominent and at least on the front page or all pages, also to make it clear it's open source and not something proprietary (which I didn't expect but got confused when not finding a link to the repo) Is there native "frontmatter"/meta support? |
Beta Was this translation helpful? Give feedback.
-
|
Hi Can, Thanks for your interest in PML.
Note that the freeCodeCamp article is not well formatted, because the article was initially published on freeCodeCamp's Medium website, but then they moved the article to their own website (when they left Medium) without editing it for proper formatting. A better version is available on PML's website.
Yes, that's the right syntax.
Interesting idea.
Yes, it's confusing if any combinations (and not just a defined set of combinations) are allowed, because there is no way for the parser to know if you mean
To avoid the ambiguity, we could add a separator, like this:
However, this would make the syntax more complex, and add complexity in the parser, as well as in editor plugins and other tools. Moreover, allowing any combinations would lead to problems if two combined nodes have one or more attributes with the same name, unless we add another special syntax to relate an attribute assignment to a specific node. I'm not sure if such use cases happen often enough to justify this added complexity. "Everything should be as simple as possible, but not simpler." (Albert Einstein). As @tajmone pointed out, it might make sense to provide a well defined set of combinations to cover "a few special cases for commonly used combination of nodes". The challenge would then be to define which combinations are "commonly used". However, note also that user-defined nodes allow users to define their customized set of combined nodes like
Note: This is written as
You're right! In the next days I'll add a link to GitHub on the front page.
Not yet, but it's planned to be added in the future. |
Beta Was this translation helpful? Give feedback.
-
|
Wow thanks a lot for those very in-depth and quick answers 😃 Uuhm yea I haven't considered editor support 😅
Though I like your version with a delimiter 👏 it's not just about a few characters less to write but about keeping it "cleaner" by no having to nest any further. Yea just read about user defined nodes more in detail and also scripting nodes Though in this case I personally think it should be baked in. To me it looks scary, cumbersome and more error prone to have to nest that deep "just" to add more than one inline style to a few characters. Thanks for pointing me to the reference docs, that's where I saw the requirement for In some cases I use Markdown to allow single line to include rich text. Also sorry, I now feel I kinda highjacked this discussion instead of opening a new one 😬😅 |
Beta Was this translation helpful? Give feedback.
-
Yes the main objective is to allow creating full documents. Maybe in the future it will also allow snippets, like AsciiDoc's option not to create a full document (template and all) so that it might be used also for processing single paragraphs or other text snippets. There are many features that Christian is working on right now, for the upcoming v3.x, which will open up new horizons in terms of users being able to control almost every aspect of PML, from the HTML template, custom nodes, and even redefining the native nodes. Probably these features alone, along with scripting, should be enough to enable handling standalone snippets.
IRC, exposure of PML documents AST is a planned feature, which will allow users to operate directly on the document nodes to manipulate them, as well as leveraging the AST to export/import between PML and other syntaxes (similarly to how pandoc exposes its AST to custom filters, either via Lua or JSON). One of the innovative aspects of PML is its openness to customization, where instead of enforcing a predefined syntax on how to handle documents it favors exposing the mechanisms to cover different needs. But of course, this is a delicate balance between having a tool that can be used out-of-the-box to produce well styled documents vs having a too generic tool that can't do much without custom extensions. So, in that respect, the future shape of PML will depend largely on users feedback, trying to find that right balance in real world needs, rather than just opinionated views on how documents should be structured semantically, etc. Excessive native features can end up bloating the syntax, meaning that customization might require overriding too many default nodes for users to obtain what they want. Here's where PDML comes into the scene, which is the core engine and sub-grammar that powers PML. Hopefully, in the future the two (PML and PDML) will grow in a symbiotic balance that will result in two powerful tools that can be used to handle documentation projects in a highly flexible way, offering many access points for controlling the toolchain details. For these reasons, any suggestions and practical examples of how different users work on their documentation projects, the various hacks they use to obtain certain results, etc. are valuable feedback in helping shape the future of PML. It's hard (if not impossible) to avoid making opinionated choices in a lightweight markup syntax, but listening to how others approach editorial tasks can at least help to avoid making irreversible choices that might preclude some options, leaving instead the doors open to them via some exposed mechanism that allows overriding the default ways of the syntax. |
Beta Was this translation helpful? Give feedback.
-
FYI: There is now a link to the Github repositories on PML's front page, in the "What is PML?" section. |
Beta Was this translation helpful? Give feedback.
-
THIS ^ 100%. With the power to define, include, and nest nodes within nodes, a la PDML, but inside PML (and maybe combined with node overrides, though I have mixed feelings on that one), developers could derive their own one-use or reusable 'dialects' of PML, whether with mere syntactic candies like |
Beta Was this translation helpful? Give feedback.
-
A few thoughts on inline text styling...
I think that it would be great if PML will support the following additional text styles:
(other possible candidates are shown below, in the CriticMarkup section)
As for how to represent these tags in PML, without clashing with existing tag names, here's a table illustrating viable solutions:
<strike><del>{strike{strikethrough<sub><sub>{sub{subscript<sup><sup>{sup{superscript<u><u>{u{underlineSome of the above proposed PML nodes need special consideration regarding which HTML tag they might convert into. E.g.
{strikeshould be intended to cover the mere text styling, not the proofreading functionality (mentioned below), i.e. it should represent a definitive stricken out text, not to be confused with a diff marker (in other words, a prose deletion, not a diffing tool log). The point is that if the CriticMarkup styles were to be supported at one point, these might need to be associated to specific tags or classes that will ensure (or allow) consistent styling, as seen in diff tools.CriticMarkup Styles for Proofreading and Diffs
Some markdown flavors, like MultiMarkdown, even offer CriticMarkup inline styles to represent draft editing (diff markers) such as:
These are mainly implemented as a feature to allow visual inspections of changes, and either accepting or rejecting them — i.e. similar to how MS Word works. The MultiMarkdown CLI tool allows to process a document by accepting or rejecting all changes, and editors plug-ins offer the same feature on a per-change basis.
Today, with most people using version control tools in collaborative editing, this feature might not be as needed as in the past (not for proofreading, at least), since tools like Git and GitHub offer these features in pull requests. But these inline styles might be actually useful in some type of documents (e.g. tutorials) where authors wish to show code/text changes or diff results.
In any case, it's worth keeping open the possibility of implementing them in the future, and keep an eye for potential tag names conflicts with shorthand tags.
Bold vs Strong & Italic vs Emphasis
A notable change in HTML's history was the shift from
<b>to<strong>and from<i>to<em>. See:The relevance for PML really boils down to which HTML tag they'll generate. From what I saw, most lightweight markup syntaxes will generate the new semantic version of these tags (
*word*→<em>word</em>and**word**→<strong>word</strong>).I personally think that the current PML use of
{boldand{italicto represent Bold and Italic, respectively, is a good and straightforward choice; but some might argue that mapping them to Strong and Emphasized might be more "semantic", or that these semantic counterparts might deserve a tag of their own.In any case, the question is a bit intricate (especially since people keep using
<b>and<i>in every day practice, and CSS allow to take over the look and style of both the older and newer tags), and it might deserve some extra attention. From what I understood, the original intentions behind the "semantic move" for these two tags were amply misunderstood, and reflected poorly in daily practices during the transition to HTML5. Also, many people are still using<b>and<i>for various reasons (including backward compatibility and SEO hacks).It would be great to hear end users' feedback on this, and they'd like PML to cover these HTML4 vs HTML5 tag differences — but lacking a big userbase, we could simply snoop around what people are saying in other lightweight syntaxes' forums (I'm sure we could find some discussions on the topic).
On Alternative Tag Names
As a closing note, a consideration on supporting variations of tags names, like
{documentand{doc...Ad I wrote elsewhere, I think that alternative IDs and syntactic sugar tend to obstruct search-&-replace operations,
codeprose refactoring, and in general stand in the way of code consistency and any programmatic operations (scripts, extensions, etc.) which need to cater for all possible variants.Also, these "lazy" alternatives (or sugar) usually provide little benefits for end users, since good editors will allow them to apply styles via keyboard shortcuts (Ctrl+B for
{bold, etc.) and snippets, anyway.So, translating the
<b>tag to{boldactually makes two chars longer, whereas{bis a closer match, and shorter.Surely, there are many (if not most) cases which demand more than a single character, either to avoid clashes or ambiguity. E.g.
<sub>and<sup>both start with an 's' (and Strikethrough too), so their minimum representation should be three chars (just like in HTML):{suband{sup. I'm just not sure how much benefits are gained from also supporting the{subscriptand{supscriptalternatives.E.g. the
{doctag, is it's meaning explicit enough? Well, I'd say that in the context of editing documents using a plain-text markup language it would be reasonable to expect end users to be able to understand intuitively that it doesn't stand for "doctor" or "docks", but for "document". Also, we can assume past experience and exposure to HTML tags; failing that, there's the PML Reference Manual and the command line help too.When different ways to represent a tag exist, each editor might choose its own opinionated way of spelling them out when it comes to shortcuts/snippets — one might chose the longer tag, others the shorter, which ultimately means that in collaborative editing projects you'll end up with different styles (just like in Markdown some use
*for bold/italics, and others use_).Of course, the PML Spec could always state which is the idiomatic way to use tags ... but then what's the point of supporting the non-idiomatic syntax?
By design, a lightweight markup syntax should be a slimmed down version than its counterparts (usually, HTML being the general reference for comparison). The fact that many such syntaxes also support "lazy variants" seems a contradiction (usually enforced by the need to support legacy formatting), because since the goal is to provide a lightweight alternative to "classical syntaxes", whenever a lighter/slimmer way is possible then it should be the official way to do it (if not the only way).
Some of these "lazy" alternatives are hacks based on the how the parser works; e.g. Markdown quotation block, which don't require adding a
>at the beginning of each wrapped paragraph line:> I'm a quotation spanning across multiple lines.which is parsed as if it were:
IMO, it's best to design a syntax in a way that you don't get to these cases, because if you do you're already dealing with some obscure parsing rules. But if you do, I think that you should then clearly define what is idiomatic vs what's lazy. And the official converter tool should also support idiomatic-validation and code linting, in order to allow published source files to display consistent styles (the tool should warn about any violation of idiomatic styling, even an extra spurious space, for the sake of code consistency and preventing source-noise).
Of course, the downside of an idiomatic linter is that it might require supporting all previous versions of a syntax (and maybe even to specify the syntax version used in a document) in order to be able to always upgrade old documents to the idiomatic standard of the latest syntax version. But this would make life so much easier for those who work with that syntax (no need of all those external tools to enforce code consistency and prevent commits noise), since the converter tool will be handling all the cleanup operations.
Needless to say, these are just general considerations which stem from my past experience working with different syntaxes and tools, and how their evolution through various major releases affected my work, and my personal conclusions and desires for features that would have made life a bit easier, but never came into being. It's also true to different people use the same tools for different goals, and you never cease to learn by listening to what others are doing, and that it can be surprising to realize how different their needs can be for any given syntax. So no single user is ever going to provide the "best" solution — there are no "best" solution, just different ones based on different needs.
Beta Was this translation helpful? Give feedback.
All reactions