Description and nickname on individual license pages

[mlinksva]

Individual license pages don't display the license description or (if available) nickname provided in the front matter of files in _licenses, e.g., http://choosealicense.com/licenses/eupl-1.1/ and https://github.com/github/choosealicense.com/blob/gh-pages/_licenses/eupl-1.1.txt

This info seems somewhat useful, especially if one gets to an individual license page through a search engine rather than by navigating the site.

These fields are accessible as page.description and page.nickname and might be added to _layouts/license.html or _includes/sidebar.html, depending on where they ought be displayed.

I'm terrible at making this look nice. If anyone wishes to tackle this, make a pull request. Alternately, if anyone feels this is a terrible idea, scream.

[LeoFNaN]

Hi @mlinksva,
I think this is a good idea. I attached something I came up with, I tried to keep it minimal and give more space for any future additions if needed. I saw that the site is using qtip2 so I was going to use it when the user hovered over the link. Let me know what you think.

[mlinksva]

@LeoFNaN thanks for coming up with this! Seems reasonable to me for the description. I don't think hover-over to see nickname often shorter than "nickname" is very reasonable. But maybe the nickname could be in the title area of the hover over box, rather than the duplicative "Description"?

[waldyrious]

As a user, I would expect the description to appear in a paragraph below the title and before the full text of the license. I can't see any good reasons to use a "hover to see" mechanism when we could just plainly add the text there.

By the way, the nickname could be in the sidebar, before the usage instructions.

[mlinksva]

I generally dislike hovering or clicking to see, but in this case I like that it would very crisply separates the summary from the license text.

Of course the description could also go in the sidebar. Maybe that's the easiest thing to do.

[LeoFNaN]

Ok you guys bring up some good points, I was in a make it subtly interactive mode last night :) So description block in the sidebar, then the nickname and the rest of the content after.

[mlinksva]

Would you like to make a PR implementing in the sidebar?

[LeoFNaN]

I'm actually trying to run the repo on my machine but having issues with script/server throwing an error...I wanted to take a look at it before I created a PR.

Conversion error: Jekyll::Converters::Scss encountered an error while converting 'assets/css/application.scss': Invalid CSS after "...s/normalize.css": expected "{", was "" on line 1

See #383

[mlinksva]

@LeoFNaN I'm not getting that error. Did you follow the steps in https://github.com/github/choosealicense.com#run-it-on-your-machine ? If there's some way the documentation or something else could be improved to avoid other contributors getting that error, I'd like to do so.

[LeoFNaN]

@mlinksva Yes that's what I followed. In the application.scss file there are 2 rows of dashes at the top of the file and when I removed them script/server was able to complete...but then application.css wasn't generated so styles weren't applied, I added application.css just so I can have a look at the changes. I'm on windows so that can be the problem :)

Update: I tried Vagrant - Jekyll on Windows same error while ssh'd into the box. This should be it's own issue.

Further discussion located here #383

[LeoFNaN]

How about displaying nickname and family side by side? check out the image.

Also, has it been considered to changing the function of the button from copy license to clipboard to Download the LICENSE.txt file? Adding a little convenience and possibly removing the content about creating the file under how to apply. As well as adding a button to the bottom of the page so visitor doesn't need to scroll back up?

[mlinksva]

The family shouldn't be displayed. It's used for grouping on /licenses but isn't 100% accurate taken as facts about licenses.

The copy button is useful for pasting into an editor, but download with conventional filename seems useful too. Maybe another button, "Download as LICENSE.txt" or similar?

Please do open a separate issue about the error you've gotten and I'll try to reproduce.

[mlinksva]

Note the download could be created with javascript, like described in http://cwestblog.com/2014/10/21/javascript-creating-a-downloadable-file-in-the-browser/ or alternately Jekyll would have to output a bare LICENSE.txt file for each license. The latter would be slightly nicer as bare license texts would have URLs.

[LeoFNaN]

Ok family meta noted.

Let me know what you think but I feel moving how to apply underneath permissions, conditions and limitations will provide more context with the use of the license rather then having how to apply at the top (which can be further justified to move to the bottom if its decided to add a download button). It's a small matter but just letting it out there.

Yeah I think another button will be nice and thanks for the link, should I create a separate issue for it and see where it goes?

[waldyrious]

I really like your proposal overall @LeoFNaN, with the caveats pointed out by @mlinksva. I also like the option to have urls for the bare licenses. Moving "how to apply" to the bottom also seems like a good choice to me, assuming a workflow where one would learn about the license first, and then decide to use it.

[mlinksva]

I'm not thrilled with moving how to apply down because it'd often be below the fold and distant from the copy and/or download actions. Longer term I wonder if it'd make sense to reserve the sidebar for actions and application documentation (button(s) and how to apply) and description into the main column, but clearly separated from the license text. Permissions/conditions/limitations could be arranged horizontally as they are on /licenses. Then you'd have

TITLE            |  copy
                 |  download
Description      |  howto
                 |  who's using
License Text     |

In any case let's get the download action in first. Go ahead and create an issue for it, or a PR directly.

[waldyrious]

I wouldn't mind the usage instructions being presented in a popup/tooltip format, and thus fit next to the copy/download buttons, in a single line on the sidebar. As in: copy | download | how to apply?

That said, I also like the idea of "reserving the sidebar for actions and application documentation (button(s) and how to apply) and description into the main column"

[LeoFNaN]

Alright I applied a mix of the feedback. I added Nickname next to Description title, and altered the how to apply content to make up for whichever use case (copy or download) and changed the button colors a little (that can be reverted if preferred).

@waldyrious I tried to apply the buttons and how to apply on one line but it seemed a little busy for one line also the sidebar felt empty and unbalanced in comparison to description and P|C|L being placed in the main column.

[waldyrious]

I love it :) great work!

[mlinksva]

Indeed, it looks great. I don't think the Description heading is needed, nor the dash(?) before Nickname.

[waldyrious]

Nor the word "nickname" itself, I suppose.

[LeoFNaN]

Thanks guys. i feel like the nickname by itself may be out of place especially since the description heading may be removed, should the nickname be moved?

@mlinksva should i perform the changes off the current pr or close it and create another?

i'll get on the button after this one :)

[mlinksva]

@LeoFNaN create another PR. I just merged #382

[mlinksva]

Regarding the nickname, I think it's useful to display. Maybe in the new PR try without any label. That might work decently.

[mlinksva]

Fixed by #399. Thanks @LeoFNaN!