search

golang / go

The Go programming language
https://go.dev
BSD 3-Clause "New" or "Revised" License
124.03k stars 17.67k forks source link

x/tools/cmd/present: add support for quote #30343

Open lucor opened 5 years ago

lucor commented 5 years ago

This proposal is about to add support for quote into the present tool.

An implementation is available here: golang/tools/pull/30

It introduces a "quote" function into the template to inject quotes and citations.

The text after ".quote" is embedded in a blockquote element after processing styling. The text after the optional "//CITATION:" is treated as a citation and embedded in a cite element after processing styling.

Example:

.quote Never memorize something that you can look up //CITATION: Albert Einstein
rsc commented 5 years ago

/cc @andybons @dmitshur

dmitshur commented 5 years ago

Thanks for the proposal!

As an observation, accepting this proposal would incur the cost of increasing the number of invocations available in the present format from 8 to 9:

 .code x.go /^func main/,/^}/
 .play y.go
 .image image.jpg
 .background image.jpg
 .iframe http://foo
 .link http://foo label
 .html file.html
 .caption _Gopher_ by [[https://www.instagram.com/reneefrench/][Renée French]]
+.quote Never memorize something that you can look up //CITATION: Albert Einstein

That means users of present will need to learn one more verb, and make decision on when to use it instead of not using it.

@lucor In your proposal, you've described this new type of invocation, but there's not much justification for why it's being added and what kind of problem it's meant to resolve.

Can you please elaborate on how it will fit into the present format as a whole? What is the experience of adding a quote in a present talk right now, i.e., before this proposal, and how does it change after this proposal? Examples of present text, and screenshots of what the rendered result looks like would be very helpful.

At a first glance, it seems similar/related to the caption invocation. Can caption be used in place of quote to achieve a similar effect, or is the dedicated quote invocation justifiable of its cost?

lucor commented 5 years ago

@dmitshur thanks for the feedback!

Right now it seems not possible to highlight some text as a quote in a present talk. The idea was to present the quotes like the HTML blockquote element.

Example:

* Quote Example

.quote Never memorize something that you can look up //CITATION: Albert Einstein

quote_screenshot

With regard to the caption invocation, it was my initial attempt too... but if it seems related to add caption to images.

andybons commented 5 years ago

@dmitshur what do you think?

dmitshur commented 5 years ago

Thanks for providing that example and screenshot, it's very helpful.

Right now it seems not possible to highlight some text as a quote in a present talk.

I'm not sure if you meant to imply "other than to use an iframe", but if not, it is possible by using an iframe with custom HTML/CSS.

I've seen some examples of iframes used to implement things that the present format doesn't provide native support for. Of course, it's less convenient and requires more work, but the upside is that any custom behavior is possible, and the amount of special present syntax is kept smaller. As one example, clicking with the mouse on the gray textbox on this slide makes a Gopher appear, via an iframe.

In order to make an informed decision of whether this quote feature is something that warrants first-class syntax support in the present format, I think it would be helpful to provide some statistics on existing present talks and see how often people try to include quotes.

If it turns out that there's a sizable amount of such talks, then we should accept this proposal. But if it turns out that very few existing talks tend to include quotes, then it's probably better not to add the new syntax and have people continue to rely on iframes to implement custom features for their talks.

lucor commented 5 years ago

Thanks for the feedback.

I'm not sure if you meant to imply "other than to use an iframe", but if not, it is possible by using an iframe with custom HTML/CSS.

Apologies, I've missed the possibility to add it using an iframe

If it turns out that there's a sizable amount of such talks, then we should accept this proposal. But if it turns out that very few existing talks tend to include quotes, then it's probably better not to add the new syntax and have people continue to rely on iframes to implement custom features for their talks.

Agreed :)

andybons commented 5 years ago

Let's just try this. We’ll figure it out as we go.