Reformatted and improved Readme.md #2310
Conversation
| If you want to build or interface with LibSass, we recommend to check out the | ||
| documentation pages about [building LibSass](docs/build.md) and | ||
| the [C-API documentation](docs/api-doc.md). | ||
| Current LibSass 3.4 should be compatible with Sass 3.4. Please refer to the [sass compatibility |
There was a problem hiding this comment.
"3.4 branch" with a link?
There was a problem hiding this comment.
The 3.4 branch isn't an official thing. It was an implementation detail because I wasn't ready to drop some large changes into Node Sass. Node Sass now has the latest 3.5 betas on master.
There was a problem hiding this comment.
Additionally I believe http://sass-compatibility.github.io/ is no longer actively maintained. I did the last round of updates a long time ago.
We should just say that we aim to be compatible the latest Ruby Sass stable release. All known incompatibilities are in our issue tracker.
There was a problem hiding this comment.
Can you provide an alternative paragraph?
| ------- | ||
|
|
||
| Since LibSass is a pure library, tests are run through the [SassSpec](https://github.com/sass/sass-spec) project using the [SassC](http://github.com/sass/sassc) driver. | ||
| Since LibSass is a pure library, tests are run through the [Sass-Spec](https://github.com/sass/sass-spec) |
There was a problem hiding this comment.
Think "sass-spec" is always lowercase
There was a problem hiding this comment.
Sass Spec is fine. The "Sass" capitalization is part of the Sass branding.
|
|
||
| ### DEBUG builds | ||
| To build LibSass you need GCC 4.6+ or Clang/LLVM. If your OS is older, you may need to upgrade |
There was a problem hiding this comment.
Is there a minimum Clang/LLVM version too to call out?
There was a problem hiding this comment.
With clang it's hard to know. If you're on OSX (which is where clang is prevalent) it'll just work.
Readme.md
Outdated
| LibSass is a C++ port of the original Ruby Sass CSS compiler with a [C API](docs/api-doc.md). | ||
| We coded LibSass with portability and efficiency in mind. You can expect LibSass to be magnitudes | ||
| faster than Ruby Sass. We would even go as far and claim that it is the fastest CSS compiler | ||
| around, which should be the case given it's written in C++. |
There was a problem hiding this comment.
You can expect LibSass to be magnitudes faster than Ruby Sass. We would even go as far and claim that it is the fastest CSS compiler around, which should be the case given it's written in C++.
This bragging is unnecessary.
There was a problem hiding this comment.
Can you provide an alternative paragraph?
There was a problem hiding this comment.
Tried the rewrite it a little and be more "humble". I really would like to keep the emphasize on the speed, because that is IMO one of the core and key assets of libsass.
Readme.md
Outdated
|
|
||
| Developing | ||
| ---------- | ||
|
|
||
| As you may have noticed, the LibSass repo itself has | ||
| no executables and no tests. Oh noes! How can you develop??? | ||
| As noted above, the LibSass repository does not contain any binaries or other way to execute |
There was a problem hiding this comment.
I'm struggling to follow this paragraph. IMHO the original was good.
There was a problem hiding this comment.
Not sure what you mean exactly? IMO it adds a bit more information than the old wording. And I don't think the old wording was any less confusing? IMO the whole paragraph does not make much sense, but I've left it in since it already was there.
Readme.md
Outdated
| LibSass | ||
| ======= | ||
| LibSass - Sass compiler written in C++ | ||
| ====================================== | ||
|
|
||
| by Aaron Leung ([@akhleung]), Hampton Catlin ([@hcatlin]), Marcel Greter ([@mgreter]) and Michael Mifsud ([@xzyfer]) |
There was a problem hiding this comment.
It's worth distinguishing current maintainers. People still contact Hampton directly who then proxies messages on to me.
There was a problem hiding this comment.
Can you provide an alternative paragraph?
There was a problem hiding this comment.
I separated it into two lines with "current mainters" and "original creators"
|
Nice work on the update. I found the language a little hard to follow in some places. I've left comments. |
Readme.md
Outdated
| - https://github.com/sass/perl-libsass (Perl) | ||
| - https://github.com/wellington/go-libsass (Go) | ||
| - https://github.com/sass/sassc-ruby (Ruby) | ||
| - https://github.com/medialize/sass.js (JS) |
There was a problem hiding this comment.
https://github.com/sass/libsass-net is now under the Sass org also.
|
I've updated some parts a bit. Please provide alternative wording or paragraphs for the open things. Otherwise it's difficult to improve it without specific feedback. Thanks! |
|
I'll provide some copy this week. |
|
@xzyfer still not heard back from you on this one! |
|
Sorry I've been preoccupied with tracking that Alpine issues since it's blocked 3.5.0.beta.3. Feel free to ship this if you want and I'll PR fix later. My priority atm is figuring out what's causing the memory issues with Alpine. |
|
OK. Btw. I suspect a compiler (buggy toolchain) issue on alpine linux. I debugged it down to the heisenbug on the assembler level, but couldn't see why accessing a function jmp fails after the same jmp/function was called successfully before many times at the same memory location. I verified that the memory location is not overwritten. So for me this is a "wont fix" until we see similar issues on other platforms! |
|
FWIW. The only difference between node-sass and sassc is that node-sass seems to flag some memory pages as non-executable (as seen when running with strace), which could be a reason why the jmp could fail. But I wasn't able to really make a connection (the raw memory addressess don't seem to overlap). |
|
And in the end musl libc is a very young libc implementation (initial release is less than 5 years old, so chances are that it is simply a bug in said musl libc implementation) ... |
|
I suspect you're correct. However if there is something we can do to mitigate the issue I'd like to try. Alpine is becoming a very important tool within the containerisation realm. |
Our main readme was getting pretty dusty and was missing a few new documentation links.
Decided to reformatted the whole thing, fixed quite a few typos and also added a few paragraphs here and there. Feel free to nitpick my english and to add more corrections. I also added two new badges from http://isitmaintained.com/. IMO it looks and reads a lot better already.