Example examples

[drwelby]

https://github.com/drwelby/example-links/blob/main/examples/maxar-ard-item.json

I don't have any non-container links to use but for our existing docs in various formats it seems to fit other than the question of #1

[m-mohr]

Great, thanks. I could add it to this repo, if you are okay with it?

Looking at it and also my examples, I'm not 100% sure container is a good key though. Thoughts?

[drwelby]

If we were to use this extension in the future we would probably place the links at the Collection level, but you are welcome to use these examples as more "real" examples.

"Container" works OK, but would it make more sense to flip the concept to something like "example:executable"?

[m-mohr]

Then I'm waiting for a Collection example, which is currently missing anyway, thanks :-)

Hmm... also not 100% happy with executable. People may "complain" that Jupyter Notebooks can also be executed, I guess....

[drwelby]

example:raw or example:source for code?

example:document[ation] for containers that are meant to be read?

I guess the possibility of a zipfile of examples makes "container" good even if not immediately obvious?

[m-mohr]

Yeah, maybe it's already the right term. Haven't though of zip files yet, but is also an idea.

Let's see whether other input comes in, otherwise I'll just release what we have, I guess. Thanks!

[drwelby]

Is there a case where the mimetype is not sufficient for client to decide what it can do?

[m-mohr]

Not sure I fully understand what you are thinking about, but "text/html" as media type doesn't indicate whether it's an html example or an html page (as container) containing something else, right? Thus, there's example:language. The difficulty is that you'd need a language <-> media type mapping to detect whether the values are the same (i.e. both HTML or not). That's difficult. So went for a very expressive thing, as also media types may not always be defined for languages etc.

[drwelby]

For example, does text/html plus example:language=Python infer that the example is Python within an html page, while application: x-python is enough to know the example is a standalone Python file?

I guess you could have text/plain plus example:language=Befunge and not be able to tell if this is a text document about Befunge or a Befunge script as text.

[drwelby]

https://github.com/drwelby/example-links/blob/main/examples/maxar-ard-collection.json

Here's a collection.

[m-mohr]

For example, does text/html plus example:language=Python infer that the example is Python within an html page, while application: x-python is enough to know the example is a standalone Python file?

Yes, if it's not clear from the media type you need to specify the language, we can clarify that.

I guess you could have text/plain plus example:language=Befunge and not be able to tell if this is a text document about Befunge or a Befunge script as text.

the scenario is a Befunge script as it doesn't set container to true. If it's a text document containing something like annotated Befunge snippets, then you need to set the container flag. "about" is a bit difficult, because for that there's the about relation type for it ;-)

Thanks for the collection, will add it.

[drwelby]

The main problem this solves is that a STAC catalog can render a link, or a formatted code block?

[m-mohr]

@drwelby Indeed. I plan to implement this in STAC Browser soon. Could also be used in other use-cases, I hope.