newsdev
compare to Markdown
The first question that popped into my head was "how does this relate to Markdown?", but was surprised that it wasn't mentioned on the homepage. I think it would be a useful reference point for anyone evaluating it. Thanks!
In fact, the website’s comparisons to YAML and JSON confused me, because neither of those are a markup language, meaning a language for annotating a document. I was looking for a comparison to HTML, the first markup language I could think of.
Is ArchieML a markup language, like HTML and Markdown, or a data serialization language, like YAML and JSON? The example document looks mostly like a marked-up document, but all the syntax examples look like serialized data.
It wouldn’t be the first time a language ending with “ML” found out its name was wrong. Both YAML and TOML started out calling themselves a markup language, and then changed their acronym later, when they realized their mistake. “YAML Ain’t Markup Language”.
There is some discussion on markup languages vs. data serialization languages on the Stack Overflow question If YAML ain't markup language, what is it?.
@roryokane's point is good, and that's probably the larger question to address in the docs. At the risk of sounding deliberately esoteric, I don't think it fits perfectly into either category.
It is an object notation in the same sense that YAML is an object notation, given that the "significant" lines translate into a single representation of a data object. The document is notation that describes an object.
But it also has aspects of a markup language. In this example:
myKey: This is the first line of a value
This is the second line
:end
I could argue that the pairing of myKey: and :end represent semantic tags no different than <myKey>...</myKey> do in HTML. Like in HTML, the value hidden in the text above is not inherently a string (since the second line's inclusion as part of the value is dependent on an :end tag following it), but just a series of characters that is semantically described as myKey by the opening and closing tags. You could argue that myKey: and :end function no differently than opening and closing "s.
Similarly, it functions as a semantic markup language in that is describes what part of the document shouldn't be included in the output. JSON doesn't define "comments", and in YAML the same argument could be made as in the previous paragraph.
We can including something about this in the intro to ground understanding, but I think given the confusion even over the meaning of "YAML", it's a bit of an academic concern and I still feel comfortable with it being an "ML".
ArchieML vs Markdown
Archie and Markdown both take semantic plain-text information and convert them into structured data.
Markdown
Markdown (1) provides hierarchy, ordering, and emphasis to plain-text and (2) it structures the plain-text as HTML data; it is the most straight forward way to convert plain-text to web formatted data.
Archie
Archie is focused on the structured data in the document. Archie converts plain-text into serialized data objects with key-value pairs.
Archie is meant for plain-text therefore a Markdown parser should be applied after Archie.
Effectively, Markdown down communicates structured content to HTML and Archie does the same for Javascript.
Archie, Markdown, JSON playground
This playground shows an example of how structured Markdown data and ArchieML can be used together.
If the keys can hidden then Archie and Markdown can be combined into a powerful unit.
Archie is like YAML Front Matter
Archie is very similar to YAML front matter used on jekyll pages in that it provides a way to combine structured and unstructured data. YAML front-matter is serialized and placed into plain text. Subsequently, the plain-text would be parsed by Markdown.
Combining Markdown and Archie could make a powerful parser similar to the abstraction in Jekyll pages. You can create structured data and presentation layers at the same time. Front Matter parsers export both the structured front matter and the a object content which is a block a unstructured plain-text that can be used later. If Archie could have an option to retain the content then you it could have enormous utility.
Archie is meant for plain-text therefore a Markdown parser should be applied after Archie.
Mostly true, however, Archie's initial use-case was to be written in a structured word-processing document - a Google Doc. The export of Google Docs to plain text is a potentially fragile part of the pipeline. Conversion of other rich text formats (HTML, Word, etc.) to plain text is possible but there is not a common implementation of this operation that can be relied on to produce the same Archie-compatible output.
Archie is meant for plain-text therefore a Markdown parser should be applied after Archie.
Again, mostly true, but there are some clashes between the Archie spec and Markdown that prevent this from working seamlessly. If you want to store Markdown data in ArchieML value fields, you need to protect [links](), (as [[links]]()) because Archie will strip out [bracketed text].
Maybe my comments were better placed in the javascript repository. But, archieml.js doesn't do anything more than turn a string into data.
Markdown + Archie Document
A markdown document typically contains purely semantic information, but some of that content can be used as structured data. Archie appends keys to the semantic information so that the data can be structured; the keys are not important to the semantic presentation. Basically, if you could strip the keys from the plain text then you'd left with a markdown document.
I understand links are a problem, but there are a few easy ways around that.