archieml.org
archieml.org copied to clipboard
newsdev
Proposed new object type: markup object
The more we have been using archieml, we've found that we'd like to write text with even less structure and only key items that we want to insert in between paragraphs of text. To achieve this we'd like to propose a new object type, which we'll call a markup object for now.
A markup object would begin with a keyword in angle brackets. Here's an example of the input:
headline: Page Headline Goes Here
intro: Some introductory text.
<freeformText>
This is one paragraph of text.
Here is another paragraph of text.
image: map1.jpg
credit: Photographer Name Here
Yet another paragraph of text.
[This text will not be parsed.]
graphic: chart1.png
credit: Artist Name Here
More paragraphs of [this text will be ignored] text here.
More paragraphs of text here.
And what the output would look like:
output = {
headline: "Page Headline Goes Here",
intro: "Some introductory text.",
freeformText: [
{key: "", content: "This is one paragraph of text."},
{key: "", content: "Here is another paragraph of text."},
{key: "image", content: "map1.jpg"},
{key: "credit", content: "Photographer Name Here"},
{key: "", content: "Yet another paragraph of text."},
{key: "graphic", content: "chart1.png"},
{key: "credit", content: "Artist Name Here"},
{key: "", content: "More paragraphs of text here."},
{key: "", content: "More paragraphs of text here."}
]
}
The main idea is to create an array of the paragraphs that you could just pour into an html document. Each paragraph would have two attributes: key and content. Unkeyed paragraphs would just have an empty string for its key, but a paragraph with a key would have that key attribute.
And once we implement nesting, then we would probably want do something like this so we could do a little more logic when inserting assets:
headline: Page Headline Goes Here
intro: Some introductory text.
<freeformText>
This is one paragraph of text.
Here is another paragraph of text.
{.image}
name: map1.jpg
credit: Photographer Name Here
{}
Yet another paragraph of text.
[This text will not be parsed.]
{.graphic}
name: chart1.png
credit: Artist Name Here
{}
More paragraphs of [this text will be ignored] text here.
More paragraphs of text here.
which would become:
output = {
headline: "Page Headline Goes Here",
intro: "Some introductory text.",
freeformText: [
{key: "", content: "This is one paragraph of text."},
{key: "", content: "Here is another paragraph of text."},
{key: "image", content: {
name: "map1.jpg",
credit: "Photographer Name Here"
}},
{key: "credit", content: "Photographer Name Here"},
{key: "", content: "Yet another paragraph of text."},
{key: "graphic", content: {
name: "chart1.png",
credit: "Artist Name Here"
}},
{key: "", content: "More paragraphs of text here."},
{key: "", content: "More paragraphs of text here."}
]
}
Unfortunately with this object type, we can’t have freeform comments everywhere, as in the other archieml object types. Anything that you want to be commented would have to appear inside square brackets and not look like a key (ie. not at the beginning of the line and have spaces, etc.). We’ll have to sort out how we will handle freeform comments inside objects and arrays nested inside markup objects. I think that we can allow them in theory, but haven’t worked out all the ramifications.
Why? need easier way to insert and move assets in between text blocks.
Why are we proposing this? Some of our recent projects like this graphic we were frequently moving graphics and photos between different paragraphs of text and the “sectioned” structure of the standard “array of objects” object made moving the assets very tedious. A new “markup” object type will let us just write and edit linearly.
In general, I like this. How would the object be closed?
On Wed, Apr 22, 2015 at 12:21 PM Archie Tse [email protected] wrote:
The more we have been using archieml, we've found that we'd like to write text with even less structure and only key items that we want to insert in between paragraphs of text. To achieve this we'd like to propose a new object type, which we'll call a markup object for now.
A markup object would begin with a keyword in angle brackets. Here's an example of the input:
headline: Page Headline Goes Here intro: Some introductory text. <freeformText> This is one paragraph of text. Here is another paragraph of text. image: map1.jpg credit: Photographer Name Here Yet another paragraph of text. [This text will not be parsed.] graphic: chart1.png credit: Artist Name Here More paragraphs of [this text will be ignored] text here. More paragraphs of text here.
And what the output would look like:
output = { headline: "Page Headline Goes Here", intro: "Some introductory text.", freeformText: [ {key: "", content: "This is one paragraph of text."}, {key: "", content: "Here is another paragraph of text."}, {key: "image", content: "map1.jpg"}, {key: "credit", content: "Photographer Name Here"}, {key: "", content: "Yet another paragraph of text."}, {key: "graphic", content: "chart1.png"}, {key: "credit", content: "Artist Name Here"}, {key: "", content: "More paragraphs of text here."}, {key: "", content: "More paragraphs of text here."} ] }
The main idea is to create an array of the paragraphs that you could just pour into an html document. Each paragraph would have two attributes: key and content. Unkeyed paragraphs would just have an empty string for its key, but a paragraph with a key would have that key attribute.
And once we implement nesting, then we would probably want do something like this so we could do a little more logic when inserting assets:
headline: Page Headline Goes Here intro: Some introductory text. <freeformText> This is one paragraph of text. Here is another paragraph of text. {.image} name: map1.jpg credit: Photographer Name Here {} Yet another paragraph of text. [This text will not be parsed.] {.graphic} name: chart1.png credit: Artist Name Here {} More paragraphs of [this text will be ignored] text here. More paragraphs of text here.
which would become:
output = { headline: "Page Headline Goes Here", intro: "Some introductory text.", freeformText: [ {key: "", content: "This is one paragraph of text."}, {key: "", content: "Here is another paragraph of text."}, {key: "image", content: { name: "map1.jpg", credit: "Photographer Name Here" }}, {key: "credit", content: "Photographer Name Here"}, {key: "", content: "Yet another paragraph of text."}, {key: "graphic", content: { name: "chart1.png", credit: "Artist Name Here" }}, {key: "", content: "More paragraphs of text here."}, {key: "", content: "More paragraphs of text here."} ] }
Unfortunately with this object type, we can’t have freeform comments everywhere, as in the other archieml object types. Anything that you want to be commented would have to appear inside square brackets and not look like a key (ie. not at the beginning of the line and have spaces, etc.). We’ll have to sort out how we will handle freeform comments inside objects and arrays nested inside markup objects. I think that we can allow them in theory, but haven’t worked out all the ramifications.
Why? need easier way to insert and move assets in between text blocks.
Why are we proposing this? Some of our recent projects like this graphic http://www.nytimes.com/interactive/2015/04/20/world/europe/surge-in-refugees-crossing-the-mediterranean-sea-maps.html we were frequently moving graphics and photos between different paragraphs of text and the “sectioned” structure of the standard “array of objects” object made moving the assets very tedious. A new “markup” object type will let us just write and edit linearly.
— Reply to this email directly or view it on GitHub https://github.com/newsdev/archieml.org/issues/13.
I think we could use the same conventions for closing that we use for [array] and {object} type objects in which empty brackets, like <>, would close a "markup" object -- or beginning any root-level object, eg. [myArray] or {myObject}, would also automatically close the markup object. Of course the object would also automatically close at the end of the document or if the parser encounters :ignore.
I like this too. It seems to go a long way toward solving an issue we've seen come up multiple times: how do you structure a multimedia document (text + images + anything) in a way that doesn't use HTML, which is far too verbose in many cases.
The output format for this type of data could even be a useful model outside of ArchieML - I could imagine a CMS making an article available as a structured array with a mixture of text and objects representing arbitrary types of embeddable media.
For that reason, and in the interest of keeping the output clean, I wonder if using an empty string as the key of text makes sense: it's fairly verbose, and using an empty string as an identifier feels a bit off.
What the freeformText array wound up as an mixture of strings and objects. Lines of text would be added to the array as strings, and keys would just create objects that contain those keys; no need to add key and content as padding:
freeformText: [
"This is one paragraph of text.",
"Here is another paragraph of text.",
{
"image": {
name: "map1.jpg",
credit: "Photographer Name Here"
}
}
]
The nested objects make sense. Since this is an array, maybe we'd also say that top-level keys within it function like they do in "normal" arrays as well, by grouping them together.
<freeformText>
This is one paragraph of text.
Here is another paragraph of text.
name: map1.jpg
credit: Photographer Name Here
Yet another paragraph of text.
freeformText: [
"This is one paragraph of text.",
"Here is another paragraph of text.",
{
name: "map1.jpg",
credit: "Photographer Name Here"
}
]
In some ways, that would make <> arrays function just like normal complex arrays, but with the rule that freeform text within them gets added to the array as strings, instead of ignore them?
Archie already uses braces and brackets; adding <> introduces some confusion to me. I can imagine using Archie within an HTML document and the <freeformText> annotation would be confusing.
Liquid expression fences {% .. %} and {{ foo | bar }} could be references to this issue.
I would keep the key/content pairs and use text, p, or paragraph for the key name:
<freeformText>
headline: Story Headline
This is one paragraph of text.
Here is another paragraph of text.
freeformText: [
{ key: "headline", content: "Story Headline" },
{ key: "text", content: "This is one paragraph of text." },
{ key: "text", content: "Here is another paragraph of text." }
]
That keeps the structure consistent and easy to render:
<% _.each(freeformText, function(block) { %>
<div class="<%= block.key %>">
<%= block.content %>
</div>
<% }) %>
I agree that conceptually, a CMS should be more flexible in content structure. Instead of arbitrarily separating headline and byline text fields from the article body, for example, the CMS should be agonistic about where elements go. (What if your story is an FAQ with multiple headlines and bylines? The standard CMS precludes entire genres of stories.)
In that spirit, I think paragraphs of text should be treated fundamentally the same as other types of content. Paragraphs are just a different type of text markup, like headlines and sources.
For nested objects, I would be inclined to keep attributes all on the same level:
freeformText: [
{ key: "headline", content: "Story Headline" },
{ key: "text", content: "This is one paragraph of text." },
{ key: "image", name: "map1.jpg", credit: "Photographer Name Here" }
]
From something like this (I am agnostic about the exact syntax):
<freeformText>
headline: Story Headline
This is one paragraph of text.
{.image}
name: map1.jpg
credit: Photographer Name Here
{}
@tonyfast raises a good point that angle brackets (ie. <>) are not a good delimiter since your content may be html in which case it will be very confusing. @giratikanon and @mericson noted that this is just a special case of the array object, so perhaps some form adaptation of square brackets will make more sense.
Here are some possibilities:
-
[*arrayname] -
[*arrayname*] -
[+arrayname] -
[_arrayname] -
[arrayname]* -
[arrayname]+
Keep in mind that freeform text objects can be nested or contain other nested objects, so the notation should make sense with the leading-dot notation we're using for nested elements.
Of these examples, I think I like
-
[+arrayname] -
[arrayname]+
but am not enamored with them. Please offer other suggestions.
I agree with @tonyfast about the angled brackets, and I now agree with @giratikanon about rendering plain-text lines as objects with a key so the internal data structure is more consistent (I'd vote for text).
Since @archietse brought up nesting freeforms, and containing nested objects within freeforms, I've sketched out what some of those scenarios might look like.
For the syntax to trigger the freeform, I agree that noting it as a "special" array of some sort makes sense. For consistency with the nested notation, and flexibility in the event we need to add more special versions of objects, I would vote for the [+arrayname] notation (or something other than the +). That way, users can always just place these "flags" at the beginning of a key, and combine them however they need, e.g. [.+arrayname] or [+.arrayname] for nested freeforms. Keeping the significant markup within the brackets (as opposed to [arrayname]+) also preserves the idea that anything after the brackets is ignored.
Top-level freeform, nested object
[+freeform]
headline: Story Headline
This is a text paragraph
{.image}
name: map1.jpg
credit: Photographer name here
{}
[]
Top-level freeform, nested array
[+freeform]
headline: Story Headline
[.array]
* one
* two
[]
[]
Top-level array, nested freeform
[array]
headline: Story Headline
[.+freeform]
headline: Story Headline
This is a text paragraph
[]
[]