x/tools/cmd/godoc: add 'expand all' link to expand all examples

[vdobler]

The code examples are initially closed in the html output of
godoc.  While this is perfectly fine for online browsing it
is unsuitable for a printout:  During printing the examples
should be open/folded out.

[dsymonds]

Comment 1:

Printing such pages is not common, but this could be addressed by adding a little JS
toggle at the top to expand/collapse all the examples. I'd imagine some people printing
out reference material would *not* want the examples, so we should make sure that's easy
too.
It doesn't seem high priority, though.

Labels changed: added priority-later, removed priority-triage.

Status changed to Accepted.

[rsc]

Comment 3:

Labels changed: added go1.1maybe.

[mewmew]

Comment 4:

It would be possible to use CSS, if examples should be included by default when
printing. The js 'expand all' link would require user interaction before printing.
@media print
{
   .collapsed
   {
      display: none !important;
   }
   .expanded
   {
      display: block !important;
   }
}

[rsc]

Comment 5:

[The time for maybe has passed.]

Labels changed: removed go1.1maybe.

[adg]

Comment 6:

Labels changed: added godoc.

[rsc]

Comment 7:

Labels changed: added go1.2maybe.

[rsc]

Comment 8:

Labels changed: added feature.

[robpike]

Comment 9:

Not for 1.2.

Labels changed: removed go1.2maybe.

[rsc]

Comment 10:

Labels changed: added go1.3maybe.

[rsc]

Comment 11:

Labels changed: removed feature.

[rsc]

Comment 12:

Labels changed: added release-none, removed go1.3maybe.

[rsc]

Comment 13:

Labels changed: added repo-tools.

[agnivade]

@andybons / @bradfitz for decision.

[rsc]

Per @andybons and @bradfitz, a trivial CL doing this is OK.

[agnivade]

Perfect, thanks !

[agnivade]

@bradfitz / @andybons - I have been thinking about where to put this button on the page. I have decided to place it beside the "Example" header under which all examples are listed. It has one click access from the top level ToC and is in a position from where all examples are accessible.

It looks a bit clumsy to me. But I am not able to find a better place. Let me know if you think of a more suitable place.

/cc @ysmolsky , @jimmyfrasche for more inputs.

[jimmyfrasche]

If this is for printing, and I'm not sure where else it would be useful, I'd go with https://github.com/golang/go/issues/3081#issuecomment-66063442

Just works is a better UI than more UI

[agnivade]

True. Maybe I misunderstood; the title does say to add an 'expand all' link. But I don't think we should expand all examples by default during printing, which the comment is doing. The user should be able to control this with a toggle.

[jimmyfrasche]

The initial request does state that this is specifically for printing.

When would this be useful, other than printing?

When would you want to exclude some examples when printing?

[agnivade]

Yea, the title and the description are not in sync. ping @vdobler for clarification.

When would you want to exclude some examples when printing?

I might not want to print all examples always. For eg- I might want only 1 or 2 examples. So I can expand them specifically and then print the document. I think that's a fair thing to ask.

[andybons]

@agnivade I think your position in https://github.com/golang/go/issues/3081#issuecomment-396990983 is fine. Let's move forward with that.

[gopherbot]

Change https://golang.org/cl/118935 mentions this issue: godoc: add link to expand/close all examples

[vdobler]

@agnivade My original intention was to have all examples printed by default or by clicking once to open them all. I find it very annoying if I print out documentation just to find out during reading that half of it is missing because it was an "interactive" document. Like I do not order individual chapters from a book I like to have the whole together. Skimming over an uninteresting example is not a big deal for me in a printout.

[agnivade]

Thanks for clarifying.

or by clicking once to open them all.

Cool, we are going with that.