Create reference docs

[Synchro]

For many of the functions, there isn't any complete documentation - the main docs are more of a language overview that happens to mention most of them. Some of the colour functions have quite complex meanings and it would make the overview too long to incorporate them in there, so I suggest we create a separate reference documentation page that contains complete docs on every function. That way the main page can be slimmed down to provide a simpler overview without cluttering it with detail. Good idea?

[rmariuzzo]

@Synchro I think it is a great idea. You can count on me for adding the documentation for the 9 blending mode a pushed weeks ago. Where can I start from?

[Synchro]

I've done a rough draft of a reference page in my fork in templates/pages/reference.md. You'll find placeholders for the colour blending modes there. I moved the old file called 'reference.md' because it didn't contain any reference info, just testing config.

All function docs follow the same basic pattern:

• name
• description
• params
• result type
• example call and output

I don't know what you think of that layout, or whether (for example) we should describe the params inline with the function name. It struck me that for the color functions it would be very nice to have color chips next to each example so that it's not quite so abstract!

At the moment they're mostly in source-code order: they should probably be alphabetical within each section. It would also be useful to have a table of contents, but I've no idea how to build one in markdown!

Going through these functions made me realise that there may be some inconsistencies in accepted parameter formats - something that cropped up in this issue - and I want to be sure any of these are cleared up. For example, the threshold parameter in the contrast function I wrote could be a percentage or a float, but I don't know that both have been tested.

[lukeapage]

will look later.. but the test pages look wrong - I'm not aware that less.js uses vows.. maybe it should be deleted rather than moved

basically any function that accepts a percentage calls a number() function that converts 100% => 1 so it therefore accepts a percentage or a float. Whether the float is intended or not, I don't know.

[Synchro]

I'm looking at this in mix:

var p = weight.value / 100.0;

and this in contrast:

if (typeof threshold === 'undefined') {
    threshold = 0.43;
} else {
    threshold = threshold.value;
}

mix is expecting a percentage, and is doing the /100 itself. contrast is expecting a float, but will it work if given a percentage because it uses .value? Neither are calling a number() function. Are either/both wrong?

[rmariuzzo]

@Synchro, concerning the reference page, I took a look a it, and it looks great for me. I agree with you what would be nice to put some color chips side by each blending mode. I will start next week adding the proper reference for each blending mode.

I have a question, can I pull your fork to my fork then push my future changes (blending mode reference)?

[Synchro]

Yes, that's what I intended, that way we (and anyone else who cares to help!) can collaborate on getting the docs in good shape before we issue a pull request.

[Synchro]

Just wondering - should this flavour of the docs be done in the wiki, rather than as I've done them here?

[Synchro]

Any chance of an answer on this? I don't want to go any further on the docs if it's heading in the wrong direction, and docs updates are definitely needed for 1.3.x.

[rmariuzzo]

Im ready to write up the docs but Im clueless about where to put it.
Please, I need to know where to add it.

Rubens Mariuzzo
On Oct 4, 2012 2:37 AM, "Marcus Bointon" notifications@github.com wrote:

Any chance of an answer on this? I don't want to go any further on the
docs if it's heading in the wrong direction, and docs updates are
definitely needed for 1.3.x.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/26#issuecomment-9131997.

[Synchro]

Well you can fork my repo and submit changes to that, but I'd like to be sure whether we should be doing it this way or putting stuff in the wiki. For the writing itself it probably doesn't matter much either way since they both use markdown, so just go ahead and write stuff wherever is convenient! I've been using a command-line markdown parser for testing.

[rmariuzzo]

Ok, I will start right away!

Rubens Mariuzzo
On Oct 4, 2012 11:01 AM, "Marcus Bointon" notifications@github.com wrote:

Well you can fork my repo and submit changes to that, but I'd like to be
sure whether we should be doing it this way or putting stuff in the wiki.
For the writing itself it probably doesn't matter much either way since
they both use markdown, so just go ahead and write stuff wherever is
convenient! I've been using a command-line markdown parser for testing.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/26#issuecomment-9144361.

[lukeapage]

I don't think it matters too much where the documentation is.. Personally I would prefer an extra page on the website - I think its more visible than on the wiki.

I was hoping @cloudhead would give us rights to the website and npm for releases and this would allow us to update the documentation at the same time.

Documentation is probably the least fun aspect of open source so personally I applaud you for what you have done so far - thanks.

[rmariuzzo]

Just to let everybody know, maybe I'll finish the docs by the end of
October, because Im getting married in October 13th. ;-)

Rubens Mariuzzo
On Oct 7, 2012 6:35 AM, "Luke Page" notifications@github.com wrote:

I don't think it matters too much where the documentation is.. Personally
I would prefer an extra page on the website - I think its more visible than
on the wiki.

I was hoping @cloudhead https://github.com/cloudhead would give us
rights to the website and npm for releases and this would allow us to
update the documentation at the same time.

Documentation is probably the least fun aspect of open source so
personally I applaud you for what you have done so far - thanks.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/26#issuecomment-9206846.

[Synchro]

Hope you had a great wedding! Recovered yet?
I just discovered that markdown doesn't allow setting colors 💩 which rather scuppers our plans for CSS color world domination.
In other news I was led to this Quicklook plugin (just grab the binary) which makes markdown previewing very easy, if you're on OS X.

[rmariuzzo]

Hi @Synchro, everything went fine with the wedding arrangements! Now I'm back from Honey Moon to normal life, and finally ready to put my hands on the docs. I will start by tomorrow Thursday, and I will show you a draft about the docs.

About the Quicklook plugin, I'm on a PC... which pretty much sums up why I can't use it.

Just one question again, where can I put the docs? I'm thinking to fork your repo and start right over it. Does it sounds right for you?

[Synchro]

Well my changes have been pulled, so you may as well fork the main repo.

[rmariuzzo]

Ok, thanks @Synchro.

[lukeapage]

Cool. Just do a pull req on to the main repro.. synchro will review and then
I'll pull. Then we will create a reference page or pull in the ms and it'll
be live.

[rmariuzzo]

Ok, thanks! I'll put everything in templates/pages/reference.md as @Synchro suggested.

[rmariuzzo]

Just to let everybody know that yesterday I started with the documentation of the blending modes, in a few days I will be pushing my changes.

[rmariuzzo]

I already push into my fork a poor draft. Later I will be adding more information related to parameter description and examples.

@Synchro since we cannot conquer the world by putting colors in MarkDown, I'm planning to write some intuitive examples using images. I know is a little bit annoying, but it's still better than just write code. And it will be very handy to visual see the effect of each blend modes.

[rmariuzzo]

Already in my fork I added input parameters description, return types and usage examples. I'm just trying to follow the same guideline of the existing reference.

Later, I will be double checking the grammar (yes, english is not my natural language), adding the images to improve the examples and adding more user and geek information to the description of each blend modes.

[jrvidal]

@rmariuzzo I see a lot of progress in your fork. Is there anything to do yet?

[rmariuzzo]

@jrvidal thanks for your comment. I will finish this weekend with the docs. I have to produce some images to well explain those blending effect. Will be good to wait til tomorrow?

[Synchro]

Instead of producing custom images manually for colour samples, how about using a service that can generate them dynamically? Take a look at something like http://placehold.it/ I can see that working well in the docs.

[lukeapage]

Why use images at all?

[Synchro]

Because markdown doesn't let you set colours, nor can we use CSS in that context. The alternative would be to not use markdown of course.

[lukeapage]

Ok, well your suggestion sounds better than generating by hand...

[rmariuzzo]

So, do you guys prefer to use a service like placeholder.it instead of
using images?

Rubens Mariuzzo
On Nov 24, 2012 7:17 PM, "Marcus Bointon" notifications@github.com wrote:

Because markdown doesn't let you set colours, nor can we use CSS in that
context. The alternative would be to not use markdown of course.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/26#issuecomment-10685043.

[Synchro]

Well I don't know where custom images would live if you did use them, and just being able to enter a URL and get seems easier than having to make/upload/host the images. The exact syntax is:

![#ff00ff](http://placehold.it/32.png/ff00ff/ff00ff)

In theory markdown also allows HTML markup, but it doesn't seem to work for me; for example:

<div style="width:32px;height:32px:background-color:#ff00ff">x</div>

Just results in:

x

[rmariuzzo]

Ok. Those days I have been in a hurry because of a convention I will attend
this weekends.

This night I will definitively push my commits. Sorry for this big delay.

Rubens Mariuzzo
On Nov 25, 2012 5:12 AM, "Marcus Bointon" notifications@github.com wrote:

Well I don't know where custom images would live if you did use them, and
just being able to enter a URL and get [image: #ff00ff]https://a248.e.akamai.net/camo.github.com/8f72332ee0cf3f63187988bd8400b516a6e6b230/687474703a2f2f706c616365686f6c642e69742f33322e706e672f6666303066662f666630306666seems easier than having to make/upload/host the images. The exact syntax
is:

In theory markdown also allows HTML markup, but it doesn't seem to work
for me; for example:

x

Just results in:
x

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/26#issuecomment-10691649.

[lukeapage]

thanks @rmariuzzo

[rmariuzzo]

Just lo let you know that I'm on it.

[rmariuzzo]

Ok, I just pushed my latest commit into my fork. Instead of using images I follow your suggestions and I used the placehold.it service. I hope you will like the results, and the whole world find it useful.

Please go check the results at my fork: https://github.com/rmariuzzo/lesscss.org/blob/master/templates/pages/reference.md#color-blending

Any suggestion or corrections will be appreciated.

If everything is ok, please let me know so I can create a pull requests back to cloudhead.

[Synchro]

Looks great - my only thought is that there may be too many examples!
Interesting to see that github serves all the images through akamai.
The examples show the input text and the images show the result, but it would be nice to show the text of the result too, something like:

difference(#ff6600, #cccccc) => #3366cc

I've spotted a mistake: screen(#ff6600, #00ff00); shows a grey box for the second value instead of green.
Extra points for the use of 'subtrahend'!
I need to update the other color operations docs to use the same format.

[Synchro]

Is there some common convention for the operators (+*/? etc) you use in the examples? I've not seen that before and it seems unnecessary if it's not common.

[rmariuzzo]

Thanks @Synchro for pointing out those suggestions, I agree with both, I will put less examples and I will suppress those operators (I just putted for fun).

A question concerning the format of the examples, how do you prefer them?

Suggestion # 1

Suggestion # 2

Suggestion # 3

Another suggestion? I will really appreciate it.

Note: with PlaceHold.it I can't pass some special symbols like #, + or = and the caracter ) will not render. I also tried escaping with Percentage Encoding such as %28 and doesn't render too.

[Synchro]

I prefer suggestion 2, but maybe lose the word 'result' and just have the colour reference?

[rmariuzzo]

Ok, I will do it as you said.

Rubens Mariuzzo
On Dec 5, 2012 2:33 PM, "Marcus Bointon" notifications@github.com wrote:

I prefer suggestion 2, but maybe lose the word 'result' and just have the
colour reference?

—
Reply to this email directly or view it on GitHub.

[lukeapage]

@rmariuzzo I would like to get this pulled.. is it just getting rid of the "result" that needs to be done? If your busy I can take your branch, make the final change and commit it?

[rmariuzzo]

Sorry, I will push my changes in a few minutes.
On Dec 30, 2012 6:06 AM, "Luke Page" notifications@github.com wrote:

@rmariuzzo https://github.com/rmariuzzo I would like to get this
pulled.. is it just getting rid of the "result" that needs to be done? If
your busy I can take your branch, make the final change and commit it?

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/26#issuecomment-11763144.

[rmariuzzo]

I'm on it.

[rmariuzzo]

@agatronic @Synchro I just committed and push all my changes related to the documentation for Color Blending modes. My latest commit is: rmariuzzo@03dd4c6

[lukeapage]

Many thanks, I've pushed this to the live site.

I think overall its a big improvement on the function reference.. I would like to hide sections not being displayed now though as the page has doubled in length...

[rmariuzzo]

Thanks to all for your patience and confidence.
On Jan 1, 2013 9:01 AM, "Luke Page" notifications@github.com wrote:

Many thanks, I've pushed this to the live site.

I think overall its a big improvement on the function reference.. I would
like to hide sections not being displayed now though as the page has
doubled in length...

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/26#issuecomment-11789230.