PGML image (and link)

[Alex-Jordan]

In PGML.pl, there are a few hints that markup for images and links were planned, but not completed. If these were to be completed, how should the markup be? The suggestion in PGML.pl is that [! and !] would be the delimiters for an image. I'm familiar with using image() where you pass either:

• a web address URL, say https://domain.com/image.png
• a file path relative to the .pg file, say myimage.png
• insertGraph() with a dynamic generated graph that might be $gr

There are width and height in pixels, and the tex width. And following #559 alt should become a common option. So could/should it be like these?

• [!https://domain.com/image.png!]{400}{200}{tex_width}{alt text}
• [!myimage.png!]{400}{200}{tex_width}{alt text}
• [!$gr!]{400}{200}{tex_width}{alt text}

Could it work that way, treating all arguments as optional strings? First thought is that image() could be upgraded so that if it is passed a string, then it just returns that string. Then all three examples above could pass through image().

I would like to avoid something like [!$gr!]{width=>400, height=>200, tex_width=>something, alt=>'alt text'} but that could be an option with the above being a fixed-order shorthand.

Also trying to imagine other things you might want on an image. Maybe a border? Maybe like [!$gr!]* if sticking to solid black 1pt is OK.

So I'm seeking thoughts on how markup should work before getting into it. I'm less interested in the [<...>] for a URL, but thoughts welcome there too. Would/could it be like [<https://domain.com/site>]{Text for Link}?

[drgrice1]

I think your summary is generally correct of the general concept of the usage for an image. I think that both
[!$gr!]{400}{200}{tex_width}{alt text}
and
[!$gr!]{width=>400, height=>200, tex_width=>something, alt=>'alt text'}
should work. I prefer the latter.

I suspect that these were not implemented as you can use the [@ ... @]* construction for these things, and it was left at that. It might be nice to complete them though.

[dlglin]

I just enabled discussions in the pg repository.

[dpvc]

I suspect that these were not implemented as you can use the [@ ... @]* construction for these things, and it was left at that.

Actually, it was that I ran out of time (but yes, I knew that [@ ... @]* would be enough for now). I wrote PGML one summer when I was visiting my grandparent's farm, and the summer came to an end. PGML was really just an experiment to show that alternative syntaxes were possible and could be useful, though I never expected it to actully be the final product, and thought an "official" version might be developed. The parser is pretty opaque, to say the least, and it is virtually unmaintainable, but these things do tend to take on a life go their own, once they are released in the wild, even if unfinished.

If we were to follow the Markdown syntax (on which PGML is based), it would be

[! alt text !]{src}{other}{options}

which would at least encourage people to provide alt text for the images. But I can see the other notation working as well.

As for the successive braces versus arrow hashes, PGML is set up to allow both (without extra work), and you can use either one for things like answers, rules, and other items that take parameters.

[Alex-Jordan]

I should add: I think that having these (image markup; link markup; and if we go there, table markup†) would be useful for community building. With [@...@]*, it gets the job done. But what if a new PG author could get by with even less understanding of perl? Without needing to understand image(), or insertGraph()or key-value syntax?

I know it's impossible to remove perl from PG. But I have this sense for what turns off some of my colleagues off from even trying to code a PG problem. And my sense is that if you could do almost everything with PGML and "simple" perl variable assignments, it would make a difference. The next step might even be a palette tool that would just insert each of the PGML tokens and block delimiters. [Don't yell at me, I wouldn't use such a thing :) But I know people who would use it and will never learn things like [@...@]*.]

† @dpvc I haven't forgotten that old thread where we discussed this.

[Alex-Jordan]

I started https://github.com/openwebwork/pg/discussions/560. I can't seem to "close" this discussion, only delete it. To continue, please post on the PG version of the thread.

[drgrice1]

I should add: I think that having these (image markup; link markup; and if we go there, table markup†) would be useful for community building. With [@...@]*, it gets the job done. But what if a new PG author could get by with even less understanding of perl? Without needing to understand image(), or insertGraph()or key-value syntax?

It is worth noting that [@ ... @]* is a PGML construct and not perl at all.

[Alex-Jordan]

It is worth noting that [@ ... @]* is a PGML construct and not perl at all.

Yes but if you are using [@...@]*, you are putting stuff in for the ... that is perl.

[drgrice1]

Yes, but you are putting in PG functions (like image or DataTable, etc). It will never be possible to write a PG/PGML problem without calling any of these functions.

[drgrice1]

It still won't be possible. You will still be calling random, loadMacros, Context, etc.

[drgrice1]

Look, I am not saying that implementing the image and link PGML constructions is a bad idea, I am just saying that it isn't going to remove the need to understand some basic perl and function calling and such. If you really want to do this, then you should implement a WYSIWIG PG problem editor.

[Alex-Jordan]

What are your thoughts on the first proposed markup versus the Markdown flavor that Davide cited?

[drgrice1]

I am not certain.

His suggested markdown syntax seems consistent with how answer rules are inserted, and yours with how substitutions are done. Also, yours is consistent with the suggested markdown for this on the Interactive PGML Lab page (albeit I may be making an interpretation as to what is meant there).

If we went with @dpvc's suggested format, would the alt text be able to still be optional? It seems like the required portion should be in the the brackets, and the only thing here that should be absolutely required is the image itself.

[Alex-Jordan]

Yeah, while I think it would be nice to follow a "standard" like Markdown, I'm not sure about requiring alt text for basic functionality. In a different context, yes. But with images in math exercises, adequate alt text can be very long and typically people will get it wrong. Like "a graph of y=x^2" when you are first introducing that curve and the point was to make the reader more familiar with it by experiencing its shape. So to someone who is not already familiar, that description is not helpful.

Another consideration is that blank alt text carries meaning (that the image is deemed decorative).

So I still lean toward the first form, with the content of [!...!] being the first argument to image(). But I'm open to more arguments in favor of something else.