From 27a021c55a9db0b2c6f617e47ab1e6acbace89a1 Mon Sep 17 00:00:00 2001 From: Luke Page Date: Sun, 12 Oct 2014 08:01:50 +0100 Subject: [PATCH 1/8] Add plugins description --- content/usage/plugins.md | 78 ++++++++++++++++++++++++++++++++++++++-- 1 file changed, 76 insertions(+), 2 deletions(-) diff --git a/content/usage/plugins.md b/content/usage/plugins.md index 326bdbf3..e16a182d 100644 --- a/content/usage/plugins.md +++ b/content/usage/plugins.md @@ -1,5 +1,79 @@ --- title: Plugins -published: false --- -> TODO + +Plugins +---------- + +How do I use a plugin ? + +Lessc + +If you are using lessc, the first thing you need to do is install that plugin. We reccommend the plugin starts "less-plugin" though that isn't required. For the clean css plugin you would install `npm install less-plugin-clean-css`. + +To use the plugin, if you specify a unrecognised option, we attempt to load that, for example +``` +lessc --clean-css="advanced" +``` + +Will use the plugin you just installed. You can also be more direct, for example + +``` +lessc --plugin=path_to_plugin=options +``` + +In Code +----------- + +In Node, require the plugin and pass it to less in an array as an option plugins. E.g. + +``` +var myPlugin = require("my-plugin"); +less.render(myCSS, { plugins: [myPlugin] }) + .then(function(css) { + }, + function(error) { + }); +``` + +In the browser +------------------- + +Plugin authors should provide a javascript file, just include that in the page *before* the less.js script. + +For Plugin Authors +-------------------------- + +Less supports some entry points that allow an author to integrate with less. We may add some more in the future. + +The plugin itself has a very simple signtaure, like this +``` +{ + install: function(less, pluginManager) { + }, + minVersion: [2, 0, 0] /* optional */ +} +``` +So, the plugin gets the less object, which in v2 has more classes on it (making it easy to extend), a plugin manager which provides some hooks to add visitors, file managers and post processors. + +If your plugin supports lessc, there are a few more details and the signature looks like this + +``` +{ + install: function(less, pluginManager) { + }, + setOptions: function(argumentString) { /* optional */ + }, + printUsage: function() { /* optional */ + }, + minVersion: [2, 0, 0] /* optional */ +} +``` +The additions are the setOptions function which passes the string the user enters when specifying your plugin and also the printUsage function which you should use to explain your options and how the plugin works. + +Here are some example repos showing the different plugin types +post-processor: https://github.com/less/less-plugin-clean-css +visitor: https://github.com/less/less-plugin-inline-urls +file-manager: https://github.com/less/less-plugin-npm-import + +Note: Plugins are different from creating a version of less for a different environment but they do have similarities, for example node provides 2 file managers by default and browser provides one and that is the main step in getting less to run within a specific environment. The plugin allows you to add file managers. From 7e1fc9144738a1d419d490e17dc82cb2c18b8720 Mon Sep 17 00:00:00 2001 From: Luke Page Date: Sun, 12 Oct 2014 08:18:49 +0100 Subject: [PATCH 2/8] update plugins into the site --- content/usage/plugins.md | 11 +++++------ data/usage.yml | 6 +++++- 2 files changed, 10 insertions(+), 7 deletions(-) diff --git a/content/usage/plugins.md b/content/usage/plugins.md index e16a182d..620da863 100644 --- a/content/usage/plugins.md +++ b/content/usage/plugins.md @@ -5,9 +5,8 @@ title: Plugins Plugins ---------- -How do I use a plugin ? - -Lessc +How do I use a plugin ? - command line +-------------------------------------- If you are using lessc, the first thing you need to do is install that plugin. We reccommend the plugin starts "less-plugin" though that isn't required. For the clean css plugin you would install `npm install less-plugin-clean-css`. @@ -22,8 +21,8 @@ Will use the plugin you just installed. You can also be more direct, for example lessc --plugin=path_to_plugin=options ``` -In Code ------------ +Using a plugin in code +---------------------- In Node, require the plugin and pass it to less in an array as an option plugins. E.g. @@ -41,7 +40,7 @@ In the browser Plugin authors should provide a javascript file, just include that in the page *before* the less.js script. -For Plugin Authors +For plugin authors -------------------------- Less supports some entry points that allow an author to integrate with less. We may add some more in the future. diff --git a/data/usage.yml b/data/usage.yml index 2866a795..b5ff3fbe 100644 --- a/data/usage.yml +++ b/data/usage.yml @@ -22,6 +22,10 @@ published: title: Browser Support files: <%= usage.base %>/browser-support.md + plugins: + title: Plugins + files: <%= usage.base %>/plugins.md + online-less-compilers: title: Online Less Compilers files: <%= usage.base %>/online-less-compilers.md @@ -60,4 +64,4 @@ unpublished: plugins: published: false title: Plugins - files: <%= usage.base %>/plugins.md \ No newline at end of file + files: <%= usage.base %>/plugins.md From 7b5f450abf12a0073fd1b6bdb7e1829b18fb4938 Mon Sep 17 00:00:00 2001 From: Luke Page Date: Sun, 12 Oct 2014 08:51:49 +0100 Subject: [PATCH 3/8] Updates for v2 and some tidying up --- content/home/using-less.md | 39 ++++----- content/usage/command-line-usage.md | 94 +++++++++++----------- content/usage/plugins.md | 3 - content/usage/using-less-in-the-browser.md | 53 ++++++++---- 4 files changed, 99 insertions(+), 90 deletions(-) diff --git a/content/home/using-less.md b/content/home/using-less.md index 7168fb79..0f580c95 100644 --- a/content/home/using-less.md +++ b/content/home/using-less.md @@ -29,9 +29,9 @@ $ lessc styles.less > styles.css To output minified CSS, simply pass the `-x` option. If you would like more involved minification, the [Clean CSS](https://github.com/GoalSmashers/clean-css) is also available with -the `--clean-css` option. +the `--clean-css` [plugin](https://github.com/less/less-plugin-clean-css). -To see all the command line options run lessc without parameters. +To see all the command line options run lessc without parameters or see [Usage]({{resolve 'usage'}}). ## Usage in Code @@ -53,37 +53,26 @@ which will output } ``` -you may also manually invoke the parser and compiler: - -```js -var parser = new(less.Parser); - -parser.parse('.class { width: (1 + 1) }', function (err, tree) { - if (err) { - return console.error(err) - } - console.log(tree.toCSS()); -}); -``` - ## Configuration You may pass some options to the compiler: ```js -var parser = new(less.Parser)({ - paths: ['.', './lib'], // Specify search paths for @import directives - filename: 'style.less' // Specify a filename, for better error messages -}); +var less = require('less'); -parser.parse('.class { width: (1 + 1) }', function (e, tree) { - tree.toCSS({ - // Minify CSS output - compress: true - }); -}); +less.render('.class { width: (1 + 1) }', + { + paths: ['.', './lib'], // Specify search paths for @import directives + filename: 'style.less', // Specify a filename, for better error messages + compress: true // Minify CSS output + }, + function (e, css) { + console.log(css); + }); ``` +See [Usage]({{resolve 'usage'}}) for more information. + ## Third party tools See the [Usage]({{resolve 'usage'}}) section for details of other tools. diff --git a/content/usage/command-line-usage.md b/content/usage/command-line-usage.md index 705855a8..998c5d65 100644 --- a/content/usage/command-line-usage.md +++ b/content/usage/command-line-usage.md @@ -30,9 +30,9 @@ Note that a [tilde version range][] will be automatically specified in `package. #### Beta releases of lessc -Periodically, as new functionality is being developed, lessc builds will be published to npm, tagged as. These builds will _not_ be published as a `@latest` official release, and will typically have a build number or alpha/beta/release candidate designation. +Periodically, as new functionality is being developed, lessc builds will be published to npm, tagged as beta. These builds will _not_ be published as a `@latest` official release, and will typically have beta in the version (use `lessc -v` to get current version). -Since patch releases are non-breaking we will publish patch releases immediately and alpha/beta/candidate versions will be published as minor or major version upgrades (we endevour since 1.4.0 to follow [semantic versioning](http://semver.org/)). +Since patch releases are non-breaking we will publish patch releases immediately and alpha/beta/candidate versions will be published as minor or major version upgrades (we endeavour since 1.4.0 to follow [semantic versioning](http://semver.org/)). #### Installing an unpublished development version of lessc @@ -68,7 +68,9 @@ $ lessc bootstrap.less bootstrap.css $ lessc -x bootstrap.less bootstrap.css ``` -### Help +### Options + +#### Help ```bash lessc --help @@ -77,7 +79,7 @@ lessc --h Prints a help message with available options and exits. -### Include paths +#### Include paths ```bash lessc --include-path=PATH1;PATH2 @@ -92,20 +94,20 @@ In node, set a paths option { paths: ['PATH1', 'PATH2'] } ``` -### Makefile +#### Makefile ```bash lessc -M lessc --depends ``` -### No Color +#### No Color ```bash lessc --no-color ``` -### No IE Compatability +#### No IE Compatability ```bash lessc --no-ie-compat @@ -113,13 +115,13 @@ lessc --no-ie-compat Currently only used for the data-uri function to ensure that images aren't created that are too large for the browser to handle. -### Disable JavaScript +#### Disable JavaScript ```bash lessc --no-js ``` -### Lint +#### Lint ```bash lessc --lint @@ -128,33 +130,35 @@ lessc --l Runs the less parser and just reports errors without any output. -### Silent +#### Silent ```bash lessc -s lessc --silent ``` -### Strict Imports +Stops any warnings from being shown. + +#### Strict Imports ```bash lessc --strict-imports ``` -### Allow imports from insecure https hosts +#### Allow imports from insecure https hosts ```bash lessc --insecure ``` -### Version +#### Version ```bash lessc -v lessc --version ``` -### Compress +#### Compress ```bash lessc -x @@ -163,25 +167,11 @@ lessc --compress Compress using less built-in compression. This does an okay job but does not utilise all the tricks of dedicated css compression. Please feel free to improve our compressed output with a pull request. -### Clean CSS - -```bash -lessc --clean-css -``` - -Clean CSS is our minifer of choice if you want to get the most minified you can. This option switches it on. - -Note - it does not yet support sourcemaps, for that you can only use our own compression. - -### Clean CSS Options +#### Clean CSS -```bash -lessc --clean-css --clean-option=--selectors-merge-mode:ie8 --clean-option=--advanced -``` - -Use this to pass options to clean css. The default options are the safest, so are IE8 compatible. +In v2 of less, Clean CSS is no longer included as a direct dependency. To use clean css with lessc, use the [clean css plugin](https://github.com/less/less-plugin-clean-css). -### Source Map Output Filename +#### Source Map Output Filename ```bash lessc --source-map @@ -190,7 +180,7 @@ lessc --source-map=file.map Tells less to generate a sourcemap. If you have the sourcemap option without a filename it will use the source less file name but with the extension map. -### Source Map Rootpath +#### Source Map Rootpath ```bash lessc --source-map-rootpath=dev-files/ @@ -206,7 +196,7 @@ dev-files/output.map dev-files/main.less ``` -### Source Map Basepath +#### Source Map Basepath ```bash lessc --source-map-basepath=less-files/ @@ -214,7 +204,7 @@ lessc --source-map-basepath=less-files/ This is the opposite of the rootpath option, it specifies a path which should be removed from the output paths. For instance if you are compiling a file in the less-files directory but the source files will be available on your web server in the root or current directory, you can specify this to remove the additional `less-files` part of the path -### Source Map Less Inline +#### Source Map Less Inline ```bash lessc --source-map-less-inline @@ -224,7 +214,7 @@ This option specifies that we should include all of the Less files in to the sou This can be used in conjunction with the map inline option so that you do not need to have any additional external files at all. -### Source Map Map Inline +#### Source Map Map Inline ```bash lessc --source-map-map-inline @@ -232,7 +222,7 @@ lessc --source-map-map-inline This option specifies that the map file should be inline in the output CSS. This is not recommended for production, but for development it allows the compiler to produce a single output file which in browsers that support it, use the compiled css but show you the non-compiled less source. -### Source Map URL +#### Source Map URL ```bash lessc --source-map-url=../my-map.json @@ -240,7 +230,7 @@ lessc --source-map-url=../my-map.json Allows you to override the URL in the css that points at the map file. This is for cases when the rootpath and basepath options are not producing exactly what you need. -### Rootpath +#### Rootpath ```bash lessc -rp=resources/ @@ -251,7 +241,7 @@ Allows you to add a path to every generated import and url in your css. This doe For instance, if all the images the css use are in a folder called resources, you can use this option to add this on to the URL's and then have the name of that folder configurable. -### Relative URLs +#### Relative URLs ```bash lessc -ru @@ -287,14 +277,14 @@ but with this option on it will instead output You may also want to consider using the data-uri function instead of this option, which will embed images into the css. -### Strict Math +#### Strict Math ```bash lessc -sm=on lessc --strict-math=on ``` -Defaults to Off. +Defaults to Off. Without this option on Less will try and process all maths in your css e.g. @@ -326,7 +316,7 @@ With strict math on, only maths that is inside un-necessary parenthesis will be We originally planned to default this to true in the future, but it has been a contraversial option and we are considering whether we have solved the problem in the right way, or whether less should just have exceptions for instances where `/` is valid or calc is used. -### Strict Units +#### Strict Units ```bash lessc -su=on @@ -347,7 +337,7 @@ In this case, things are clearly not right - a length multiplied by a length giv With strict units on, we assume this is a bug in the calculation and throw an error. -### Global Variable +#### Global Variable ```bash lessc --global-var="my-background=red" @@ -355,7 +345,7 @@ lessc --global-var="my-background=red" This option defines a variable that can be referenced by the file. Effectively the declaration is put at the top of your base Less file, meaning it can be used but it also can be overridden if this variable is defined in the file. -### Modify Variable +#### Modify Variable ```bash lessc --modify-var="my-background=red" @@ -363,7 +353,7 @@ lessc --modify-var="my-background=red" As opposed to the global variable option, this puts the declaration at the end of your base file, meaning it will override anything defined in your Less file. -### URL Arguments +#### URL Arguments ```bash lessc --url-args="cache726357" @@ -371,7 +361,7 @@ lessc --url-args="cache726357" This option allows you to specify a argument to go on to every URL. This may be used for cache-busting for instance. -### Line Numbers +#### Line Numbers ```bash lessc --line-numbers=comments @@ -380,3 +370,17 @@ lessc --line-numbers=all ``` Generates inline source-mapping. This was the only option before browsers started supporting sourcemaps. We are consider deprecating, so please get in touch if you want this option to stick around. + +#### Plugin + +```bash +lessc --clean-css +lessc --plugin=clean-css="advanced" +``` + +--plugin Loads a plugin. You can also omit the --plugin= if the plugin begins +less-plugin. E.g. the clean css plugin is called less-plugin-clean-css +once installed (npm install less-plugin-clean-css), use either with +--plugin=less-plugin-clean-css or just --clean-css +specify options afterwards e.g. --plugin=less-plugin-clean-css="advanced" +or --clean-css="advanced" diff --git a/content/usage/plugins.md b/content/usage/plugins.md index 620da863..9087584b 100644 --- a/content/usage/plugins.md +++ b/content/usage/plugins.md @@ -2,9 +2,6 @@ title: Plugins --- -Plugins ----------- - How do I use a plugin ? - command line -------------------------------------- diff --git a/content/usage/using-less-in-the-browser.md b/content/usage/using-less-in-the-browser.md index 84e21cb0..5d76d9e3 100644 --- a/content/usage/using-less-in-the-browser.md +++ b/content/usage/using-less-in-the-browser.md @@ -2,10 +2,31 @@ title: Using Less in the Browser --- +We recommend using less in the browser only for development or when you need to dynamically compile less and cannot do it serverside. +This is because less is a large javascript file and compiling less before the user can see the page means a delay for the user. In addition, +consider that mobile devices will compile slower. For development consider if using a watcher and live reload (e.g. with grunt or gulp) would +be better suited. + +To use less in the browser, you firstly need to include the less script. + +```html + + +``` + +This will find any less style tags on the page + +```html + +``` + +and create style tags with the compiled css synchronously. + ### Watch mode To enable Watch mode, option `env` must be set to `development`. Then AFTER the less.js file is included, call `less.watch()`, like this: ```html + ``` @@ -29,7 +50,7 @@ Either specify the option `dumpLineNumbers` as above or add `!dumpLineNumbers:me You can use the `comments` option with [FireLESS](https://addons.mozilla.org/en-us/firefox/addon/fireless/) and the `mediaquery` option with FireBug/Chrome dev tools (it is identical to the SCSS media query debugging format). -## Client-side Usage +### Options Set options in a global `less` object **before** loading the less.js script: @@ -55,16 +76,14 @@ Set options in a global `less` object **before** loading the less.js script: ``` -## Client side options - -### async +#### async Type: `Boolean` Default: `false` Whether to request the import files with the async option or not. See [fileAsync](#using-less-in-the-browser-fileasync). -### dumpLineNumbers +#### dumpLineNumbers Type: `String` Options: `''`| `'comments'`|`'mediaquery'`|`'all'` Default: `''` @@ -75,7 +94,7 @@ The `comments` option is used for outputting user-understandable content, whilst In the future we hope this option to be superseded by sourcemaps. -### env +#### env Type: `String` Default: depends on page URL @@ -90,7 +109,7 @@ e.g. less = { env: 'production' }; ``` -### errorReporting +#### errorReporting Type: `String` Options: `html`|`console`|`function` @@ -99,23 +118,23 @@ Default: `html` Set the method of error reporting when compilation fails. -### fileAsync +#### fileAsync Type: `Boolean` Default: `false` Whether to request the import asynchronously when in a page with a file protocol. -### functions +#### functions Type: `object` User functions, keyed by name. e.g. ```js -less = { - functions: { - myfunc: function() { +less = { + functions: { + myfunc: function() { return new(less.tree.Dimension)(1); } } @@ -130,7 +149,7 @@ and it can be used like a native Less function e.g. } ``` -### logLevel +#### logLevel Type: `Number` Default: 2 @@ -143,7 +162,7 @@ The amount of logging in the javascript console. Note: If you are in the `produc 0 - Nothing ``` -### poll +#### poll Type: `Integer` Default: `1000` @@ -157,7 +176,7 @@ Default: `false` Optionally adjust URLs to be relative. When false, URLs are already relative to the entry less file. -### globalVars +#### globalVars Type: `Object` Default: `undefined` @@ -172,7 +191,7 @@ less.globalVars = { myvar: "#ddffee", mystr: "\"quoted\"" }; This option defines a variable that can be referenced by the file. Effectively the declaration is put at the top of your base Less file, meaning it can be used but it also can be overridden if this variable is defined in the file. -### modifyVars +#### modifyVars Type: `Object` Default: `undefined` @@ -181,7 +200,7 @@ Same format as [globalVars](#using-less-in-the-browser-globalvars). As opposed to the [globalVars](#using-less-in-the-browser-globalvars) option, this puts the declaration at the end of your base file, meaning it will override anything defined in your Less file. -### rootpath +#### rootpath Type: `String` Default: `false` From 0ed50318dfab25fc596e17c0c08d65d57eda872a Mon Sep 17 00:00:00 2001 From: Luke Page Date: Sun, 12 Oct 2014 08:56:53 +0100 Subject: [PATCH 4/8] add list of plugins --- content/usage/plugins.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/content/usage/plugins.md b/content/usage/plugins.md index 9087584b..803980e9 100644 --- a/content/usage/plugins.md +++ b/content/usage/plugins.md @@ -37,6 +37,15 @@ In the browser Plugin authors should provide a javascript file, just include that in the page *before* the less.js script. +List of less plugins +-------------------- + + - [Clean CSS plugin to compress less](https://github.com/less/less-plugin-clean-css) + - [Autoprefixer plugin to add backwards compatibility to your css](https://github.com/less/less-plugin-autoprefix) + - [Inline urls - converts `url()` to a call to `data-uri()`](https://github.com/less/less-plugin-inline-urls) + - [Npm Import - import from a sub npm repository](https://github.com/less/less-plugin-npm-import) + + For plugin authors -------------------------- From 044b66caae834a347fca3463fea031a1c5924000 Mon Sep 17 00:00:00 2001 From: Luke Page Date: Sun, 12 Oct 2014 09:09:30 +0100 Subject: [PATCH 5/8] more info on programmatic usage --- content/usage/programmatic-usage.md | 24 ++++++++++++++++++++++++ data/usage.yml | 4 ++++ 2 files changed, 28 insertions(+) create mode 100644 content/usage/programmatic-usage.md diff --git a/content/usage/programmatic-usage.md b/content/usage/programmatic-usage.md new file mode 100644 index 00000000..5ee513a6 --- /dev/null +++ b/content/usage/programmatic-usage.md @@ -0,0 +1,24 @@ +--- +title: Programmatic usage +--- + +The main entry point into less is the less.render function. This takes the following format + +``` +less.render(css, options) + .then(function(css) { + }, + function(error) { + }); + +// or... + +less.render(css, options, function(error, css) {}) +``` + +The options argument is optional. If you specify a callback then a promise will not be returned, where as if you do not specify a callback a promise will be given. +Under the hood, if a callback is given it runs itself again to get a promise and then calls the callback in the 2 promise states - so we recommend using the promise version. + +Previously we also recommended creating a less.Parser and then calling toCSS on the result. However this had 2 serious drawbacks - it meant that our parser was in fact tied to all of less and 2nd it meant that the toCSS call had to be synchronous. + +You can still get the less parse tree, but it requires more steps. You can see how this is done [in the render function](https://github.com/less/less.js/blob/master/lib/less/render.js) but we *do not* support using less in this way and may change this function in a minor release version bump (we will not break it in a patch release). diff --git a/data/usage.yml b/data/usage.yml index b5ff3fbe..e8b61784 100644 --- a/data/usage.yml +++ b/data/usage.yml @@ -26,6 +26,10 @@ published: title: Plugins files: <%= usage.base %>/plugins.md + programmatic-usage: + title: Programmatic Usage + files: <%= usage.base %>/programmatic-usage.md + online-less-compilers: title: Online Less Compilers files: <%= usage.base %>/online-less-compilers.md From 1e9cad6868154461dd55c0754af19723508a9a73 Mon Sep 17 00:00:00 2001 From: Luke Page Date: Sun, 12 Oct 2014 11:38:39 +0100 Subject: [PATCH 6/8] V2 Upgrade Guide --- content/usage/programmatic-usage.md | 19 +++++++++++++++ content/usage/v2-upgrade.md | 38 +++++++++++++++++++++++++++++ data/usage.yml | 4 +++ 3 files changed, 61 insertions(+) create mode 100644 content/usage/v2-upgrade.md diff --git a/content/usage/programmatic-usage.md b/content/usage/programmatic-usage.md index 5ee513a6..85cffbdc 100644 --- a/content/usage/programmatic-usage.md +++ b/content/usage/programmatic-usage.md @@ -22,3 +22,22 @@ Under the hood, if a callback is given it runs itself again to get a promise and Previously we also recommended creating a less.Parser and then calling toCSS on the result. However this had 2 serious drawbacks - it meant that our parser was in fact tied to all of less and 2nd it meant that the toCSS call had to be synchronous. You can still get the less parse tree, but it requires more steps. You can see how this is done [in the render function](https://github.com/less/less.js/blob/master/lib/less/render.js) but we *do not* support using less in this way and may change this function in a minor release version bump (we will not break it in a patch release). + +### Getting access to the log + +You can add a log listener with the following code + +``` +less.logger.addListener({ + debug: function(msg) { + }, + info: function(msg) { + }, + warn: function(msg) { + }, + error: function(msg) { + } +}); +``` + +Note: all functions are optional. An error will not be logged, but instead is passed back to the callback or promise in less.render diff --git a/content/usage/v2-upgrade.md b/content/usage/v2-upgrade.md new file mode 100644 index 00000000..8c0ca66c --- /dev/null +++ b/content/usage/v2-upgrade.md @@ -0,0 +1,38 @@ +--- +title: V2 Upgrade Guide +--- + +Command line usage +------------------ + +### Clean Css + +We have removed the dependency on clean css and moved it to a [plugin](https://github.com/less/less-plugin-clean-css). +This allows us to 1. update the dependency and integration without a less release 2. Does not tie people who do not use clean css into having it downloaded by npm. + +The usage is similar, just install the plugin (`npm install -g less-plugin-clean-css`) then tell less to use it by using the +`--clean-css` argument. + +```bash +# old +lessc --clean-css --clean-option=--compatibility:ie8 --clean-option=--advanced +# new +lessc --clean-css="--compatibility=ie8 --advanced" +``` + +### Sourcemaps + +We have improved the source map options and path generation so the sourcemap should be generated at the correct path without specifying any options. + +Programmatic Usage +------------------ + +We have deprecated the use of less.Parser and toCss to generate the css. Instead we require you to use the `less.render` shorthand. +See (Programmatic Usage)[#programmatic-usage] for more information. + +If you already use `less.render` you should not require any changes. + +Browser usage +------------- + +The browser usage has not changed. diff --git a/data/usage.yml b/data/usage.yml index e8b61784..c5646d35 100644 --- a/data/usage.yml +++ b/data/usage.yml @@ -10,6 +10,10 @@ base: content/usage published: + v2-upgrade-guide: + title: V2 Upgrade Guide + files: <%= usage.base %>/v2-upgrade.md + command-line-usage: title: Command Line Usage files: <%= usage.base %>/command-line-usage.md From bc959a80d827fb5843eeadd4d90722b9f877c650 Mon Sep 17 00:00:00 2001 From: Luke Page Date: Sun, 12 Oct 2014 16:55:26 +0100 Subject: [PATCH 7/8] add a couple of paragraphs about running in other environments --- content/usage/developing-less.md | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/content/usage/developing-less.md b/content/usage/developing-less.md index 0b6daf86..6d5d3b1d 100644 --- a/content/usage/developing-less.md +++ b/content/usage/developing-less.md @@ -31,9 +31,27 @@ Other grunt commands * `grunt stable` to create a new release * `grunt readme` to generate a new readme.md in the root directory (after each release) +## How to run less in other environments + +If you look in the libs folder you will see `less`, `less-node`, `less-browser`. The less folder is pure javascript with no environment +specifics. if you require `less/libs/less`, you get a function that takes an environment object and an array of file managers. The file +managers are the same file managers that can also be written as a plugin. + +```js +var createLess = require("less/libs/less"), + myLess = createLess(environment, [myFileManager]); +``` + +The environment api is specified in [less/libs/less/environment/environment-api.js](https://github.com/less/less.js/blob/master/lib/less/environment/environment-api.js) +and the file manager api is specified in [less/libs/less/environment/file-manager-api.js](https://github.com/less/less.js/blob/master/lib/less/environment/file-manager-api.js). + +For file managers we highly recommend setting the prototype as a new AbstractFileManager - this allows you to override what is needed and allows us +to implement new functions without breaking existing file managers. For an example of file managers, see the 2 node implementations, the browser implementation or +the npm import plugin implementation. + ## Guide -If you look at [http://www.gliffy.com/go/publish/4784259](http://www.gliffy.com/go/publish/4784259), This is an overview diagram of how less works. +If you look at [http://www.gliffy.com/go/publish/4784259](http://www.gliffy.com/go/publish/4784259), This is an overview diagram of how less works. Warning! It needs updating with v2 changes. ## Books From 8001974cbf493ca47bd14fcf7c906fa642eaefee Mon Sep 17 00:00:00 2001 From: Luke Page Date: Sun, 19 Oct 2014 19:30:30 +0100 Subject: [PATCH 8/8] update some sourcemap options --- content/usage/command-line-usage.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/content/usage/command-line-usage.md b/content/usage/command-line-usage.md index 998c5d65..b0cfded1 100644 --- a/content/usage/command-line-usage.md +++ b/content/usage/command-line-usage.md @@ -188,6 +188,8 @@ lessc --source-map-rootpath=dev-files/ Specifies a rootpath that should be prepended to each of the less file paths inside the sourcemap and also to the path to the map file specified in your output css. +Because the basepath defaults to the directory of the input less file, the rootpath defaults to the path from the sourcemap output file to the base directory of the input less file. + Use this option if for instance you have a css file generated in the root on your web server but have your source less/css/map files in a different folder. So for the option above you might have ```bash @@ -202,7 +204,9 @@ dev-files/main.less lessc --source-map-basepath=less-files/ ``` -This is the opposite of the rootpath option, it specifies a path which should be removed from the output paths. For instance if you are compiling a file in the less-files directory but the source files will be available on your web server in the root or current directory, you can specify this to remove the additional `less-files` part of the path +This is the opposite of the rootpath option, it specifies a path which should be removed from the output paths. For instance if you are compiling a file in the less-files directory but the source files will be available on your web server in the root or current directory, you can specify this to remove the additional `less-files` part of the path. + +It defaults to the path to the input less file. #### Source Map Less Inline