Comments (7)
I agree 100% with everything mentioned in your post. These limitations will be removed in the next PML version (the version I'm currently working on, written in Java).
Wonderful! I could then finally start using PML in executable ebooks (which all use custom protocols like ebook:///
, etc.) and in-software documentation (via WebControl).
Absolute and relative URLs and file paths will be supported for all media assets, and the paths and URLs will no more be validated by PMLC (unless explicitly asked for).
The idea of allowing validation on demand is good.
How are you going to implement it, via CLI option or per element via node attributes?
That's actually a feature I've been pondering on in my free time, when I try to think of missing features in the various markup languages which could be added to PML. A draft idea I had in mind was the ability to enable gathering info on an image at conversion time, e.g. to calculate its width and height and inject them in the final HTML in order to ensure that its placeholder (while loading) is of the correct size.
E.g. it could be something like:
[image ( source=pear.png width=extract ) ]
where the special value extract
implies that PML should locate the image and extract it's dimensions info from its header. The generated HTML should be something like:
<img src="pear.png" width="300">
The idea is that the special extract
attribute value could be used in various places where meta-data extraction from external assets might be useful. In some media types metadata might play a greater role than others, e.g. containing info about the title, author(s), creation date, license, etc., and sometimes even preview images or cover-art; and the extract
feature would allow to re-use a same PML block as a template for each external assets, since only the file name would be required to obtain the value of all other fields, e.g.:
[youtube_video
yid = NUDhA4hXdS8
caption = extract(title)
]
i.e. assuming that title
is a valid metadata entry name that can be somehow obtained via YouTube API once you known the video's YID.
Surely, the ability to extract metadata and info for all the various possible assets would require implementing a dedicated function for each asset type, and knowing where and how the data is stored. But maybe if PMLC could expose a public API for the extract(x)
function for each node involving an external resource, then maybe end users could provide the data extraction code themselves, e.g. via script nodes or some external custom tool invoked via the command line or as a process.
This feature would be very useful when creating catalogues of assets, o handling dynamically generated html pages with lots of images (which might take time to load) which are computed at conversion time (e.g. based on the files present in a given folder), etc.
from pml-companion.
I agree 100% with everything mentioned in your post. These limitations will be removed in the next PML version (the version I'm currently working on, written in Java). Absolute and relative URLs and file paths will be supported for all media assets, and the paths and URLs will no more be validated by PMLC (unless explicitly asked for).
from pml-companion.
How are you going to implement it, via CLI option or per element via node attributes?
I was already thinking of a general way that would allow to define default values for all attributes of all nodes. Default values could be defined:
- in a shared config file, valid for all documents.
- in a not-yet-existing
config
node, a direct child of thedoc
node (overrides 1) - in CLI arguments (overrides 2)
Each default value can of course be explicitly overridden for each individual node in a document.
Note that script nodes can also be used to define default values, as demonstrated here.
the ability to enable gathering info on an image at conversion time, e.g. to calculate its width and height and inject them in the final HTML in order to ensure that its placeholder (while loading) is of the correct size.
...caption = extract(title)
Very nice idea to optimize and automate!
from pml-companion.
The options precedence seems good, but you should also consider introducing a precedence modifier, like the @
symbol in Asciidoctor (see Altering the assignment precedence in Asciidoctor Manual).
This allows to change the default precedence, e.g. by prefixing an option with the @
either in the CLI, the node definition or the settings file. This becomes quite important when dealing with complex projects that share common settings file or invocation commands, and some documents might need the option (or attribute, etc.) defined in the document to have higher precedence over the CLI, and viceversa.
- in a not-yet-existing
config
node, a direct child of thedoc
node (overrides 1)
So, if I've understood correctly, all the document options will be part of the [doc
attributes and/or sub-nodes, along with meta-data, etc. Pandoc uses a YAML section for metadata, placed at the beginning of a document, but then in the actual AST the metadata and options are effectively sub-nodes of the metadata
node, so I guess that PML approach is more similar to the latter, since it's always closer to an AST in its syntax.
It makes sense. Then I imagine that ultimately the nodes tree will be something like:
-+- [doc +
+- [metadata
+- [options/settings
+ ...
If end users have access to all nodes, dynamically from within the document itself (e.g. to read metadata or settings, or even change them) it could lead to very interesting use cases. E.g. conditional text could be shown depending on a metadata or setting value, and so on (e.g. omit contents if it's a sample/demo version of an eBook).
from pml-companion.
consider introducing a precedence modifier
Good point.
I imagine that ultimately the nodes tree will be something like:
-+- [doc +
+- [metadata
+- [options/settings
+ ...
Yes, exactly.
If end users have access to all nodes ...
Yes, meta- and config-data should be available as maps (dictionaries) in script nodes.
Moreover, for each meta-data there should be an attribute (maybe named show
, with sensible default values) to define if the data will be displayed automatically in a meta-data-table at the beginning of the document. E.g.:
[meta
[author Albert Newton] [- shown by default -]
[license (show=yes) MIT]
[license_URL (show=no) https://opensource.org/licenses/MIT]
]
from pml-companion.
Moreover, for each meta-data there should be an attribute (maybe named
show
, with sensible default values) to define if the data will be displayed automatically in a meta-data-table at the beginning of the document.
That's an excellent idea. It allows to store extra info even if not actually displayed in the document. I don't like the name show
though, it's a bit vague. maybe more context-appropriate candidates could be: display
, hidden
, reveal
(although none of them really conveys the document-specific goal).
from pml-companion.
inability to use images stored on the web, or provide links that use relative paths, or protocols others than those accepted by PMLC
Fixed in version 3.0.0.
Moreover, a shared options file, valid for all documents, as well as an option
node (a direct child of the doc node) have been added in version 3.0.0.
from pml-companion.
Related Issues (20)
- JavaScript Date function fails in user-defined node HOT 2
- Discrete Headings to Exclude Sections from TOC HOT 5
- Broken Tables in PML 2.3.0 HOT 3
- Problems with [text Node HOT 2
- PMLC: Add Opts to Launch Manuals HOT 3
- Node Repetition via Asterisk HOT 2
- PML Docs: Add Version Info to Ref Man & Create Docs Archive HOT 5
- Why Multiple Heading IDs? HOT 4
- Fatal Conversion Error: [text Inside [title HOT 2
- Resources directory written to '?/.config' when inside Docker container HOT 2
- Resources directory written for non-action commands like help HOT 2
- PMLC v3.1.0 Segfault on Linux HOT 5
- HTML Attributes Ignored on Images HOT 4
- List Enhancements HOT 7
- CSS Option Treats Everything As CSS HOT 8
- Stylesheets Copy-&-Subfolder Prevents CSS Debugging HOT 12
- Parser Inconsistency with Quoted IDs HOT 3
- PMLC 3.1.0 Crashes on Empty [options Node HOT 2
- Delimited Text Syntax and Unbalanced Delimiters HOT 3
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from pml-companion.