details tag to hide/reveal in html scribble documents

[spdegabrielle]

the details tag might be a good addition to scribble html rendering

see @plragde question on slack https://racket.slack.com/archives/C06V96CKX/p1589635196467200

perhaps falling back to aside for cases when it doesn't work see #205

The HTML5

element? https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details

Good browser support with the exception of IE11 and earlier. :(

[spdegabrielle]

https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details

<details>
    <summary>click to reveal</summary>
    Something special like an answer.
</details>

[spdegabrielle]

Example of defining a new scribble component https://github.com/racket/scribble/blob/master/scribble-lib/scriblib/figure.rkt#L110

[bennn]

Here's an example with <details> that works out of the box:

#lang scribble/base

@(require
   (only-in scribble/core make-style)
   (only-in scribble/html-properties alt-tag))

@(define details-style (make-style #f (list (alt-tag "details"))))

@(define (details . arg*)
   (apply elem #:style details-style arg*))

@; -----------------------------------------------------------------------------

This is a Scribble document with a @tt{details} element.

@details{
 The @tt{alt-tag} style property can change the HTML tag that
 Scribble creates for an @tt{element} or @tt{paragraph}.

 @url{https://docs.racket-lang.org/scribble/core.html#(def._((lib._scribble%2Fhtml-properties..rkt)._alt-tag))}
}

https://docs.racket-lang.org/scribble/core.html#(def._((lib._scribble%2Fhtml-properties..rkt)._alt-tag))

[jackfirth]

This is separate from the question of how to implement it, but I don't think we should be encouraging the use of <details> in API reference documentation. People use ctrl+F to search reference documentation pages all the time, but the contents of a <details> tag are hidden from searches. There are probably some good use cases for <details> in Scribble documents but any implementation of such a feature should come along with warnings of its potential for misuse.

[spdegabrielle]

I added the example from @bennn to https://github.com/racket/racket/wiki/Add-a-tag-to-scribble (listed in https://github.com/racket/racket/wiki/Artifacts )

I don't think I'm alone in really struggling to comprehend scribble documentation.

I think this example belongs in the scribble documentation - not in the wiki - though I'm not sure where.

I've modified the above to demonstrate the summary tag nested in the details tag.

#lang scribble/base

@(require
   (only-in scribble/core make-style)
   (only-in scribble/html-properties alt-tag))

@(define details-style (make-style #f (list (alt-tag "details"))))
;summary
@(define summary-style (make-style #f (list (alt-tag "summary"))))

@(define (details summary . arg*)
   (apply elem (elem summary #:style summary-style) #:style details-style arg*))

@; -----------------------------------------------------------------------------

This is a Scribble document with a @tt{details} element.

@details["the details heading"]{
 The @tt{alt-tag} style property can change the HTML tag that
 Scribble creates for an @tt{element} or @tt{paragraph}.

@url{https://docs.racket-lang.org/scribble/core.html#(def._((lib._scribble%2Fhtml-properties..rkt)._alt-tag))}
}

[spdegabrielle]

I'm convinced this is a bad idea now. Closing.

[bennn]

I agree about the need for some kind of doc update. Outputting a specific HTML tag is a basic task and the answer is hard to find.

Maybe Scribble needs an FAQ, maybe we can get by with more indexing.