File Path Attributes and Cross-Platform Interoperability

[tajmone]

For those attributes that take file paths as their values, like absolute_or_relative_file_path (file attr.), relative_file_path (src attr.), etc.:

• Does PML enforce Unix-style paths, or does it also support Windows paths?
• Does PML sanitize and re-adapt paths for cross-platform interoperability?

This is something worth mentioning in the PML documentation!

Ideally, using a consistent path representation would be better, for it would promote PML documents portability; also, Windows supports / path separators too, whereas Linux and macOS don't support Win-style \ separators.

In any case, PML for Windows could handle internally any required path adaptations, by converting on the fly forward-slashes to back-slashes, and adding the : separator after the drive letter in absolute paths (e.g. c/Windows/ → C:\Windows\).

It might also be a good idea if PML could validate paths to ensure they are cross-platform, i.e. that they don't contain folder and file names which are invalid (reserved) in either Win, Linux or macOS — in case of a path that is invalid for the current OS, it should fail conversion with an error exit code, whereas paths which are invalid on other OSs should only produce a warning (or fail if a stricter build criteria is set via CLI options, when/if such a feature is implemented along the lines of Asciidoctor --failure-level WARN).

Surely, this feature needs to take into account parameters inside *_file_path attributes, but since validation occurs on-the-fly, at conversion time, it should be easy to validate path after parameters expansion, but maybe a bit more trickier to report errors.

[pml-lang]

Does PML enforce Unix-style paths, or does it also support Windows paths?

The paths allowed depend on the OS used to run the application.
If the converter runs on Windows then Windows paths are allowed.
As the converter runs on a Java Virtual Machine (JVM) and uses the standard Java API for paths, all this is managed internally by the rules of Java (which means that portability is ensured).

Does PML sanitize and re-adapt paths for cross-platform interoperability?

Yes, this is done internally by Java.

paths which are invalid on other OSs should only produce a warning

Good idea. But currently not yet implemented.

[tajmone]

As the converter runs on a Java Virtual Machine (JVM) and uses the standard Java API for paths, all this is managed internally by the rules of Java (which means that portability is ensured).

But Java could also support path via the file URI scheme, which would make PML source documents platform-agnostic, and which end users are already accustomed to anyhow, since it's the same scheme for web URL.

It might introduce some hardship (e.g. having to encode spaces in paths as %20), but also promote better file naming conventions for cross-platform interoperability.

Alternatively, PML could support both file paths and file URIs, the former being more practical for individual projects, the latter for cross platform shared projects.

Or a middle ground solution could be the original proposal, of expecting all paths to be Unix like, and handle their sanitation on Windows.

[pxml-lang]

PML could support both file paths and file URIs

Yes, both must be supported.

The choice of using a file or URL could be 'explicit', like this:

[insert file <path>]
[insert url <url>]

... or 'lazy', like this:

[insert <path or url>]

There is probably no portable, 100% reliable way to always decide whether a string is a URL or a file path (absolute or relative), apart from 'hacky' solutions like those suggested here.

Therefore we should support both syntaxes ('explicit' for safety, and 'lazy' for convenience).

We should come up with a simple, intuitive rule for the 'lazy' syntax, covering the common cases, e.g.:

• If the string starts with http://, file://, or ftp:// then it's a URL (we could also use a more general regex)
• In all other cases it's supposed to be an absolute or relative file path

[tajmone]

As long as the non-lazy solution are granted to always work correctly, it should be fine. When the lazy approach can't be resolved, it should be sufficient to throw an error at conversion time. Probably the lazy solution is going to be used for user specific projects anyhow.