Publish asciidoc mode for codemirror

[jamroks]

Hi ,

First i wanna thank you for this useful mode, i'll be using it in ghost, i was wandering if you could publish it as an npm module. As i've been informed it has been also successfully used in hubpress.io ( an application to build a blog on github ). So making it available in npm or bower etc... could be useful to more people.

It would be great to have it referenced also in the codemirror website among other language syntax mode. Thanks you

[nerk]

Agreed, this is useful for other people as well. However, this mode is the great work of Thadee Tyl from this https://github.com/espadrine/ace2cm project.

Would you mind asking the original author about publishing? I already mentioned his name at the bottom of the README, but will also add a link to his project.

[mojavelinux]

@nerk, as I understand it, you used his tool (ace2cm/convert.js) to transform the Ace mode into a CodeMirror mode, correct? If that's the case, then I think we have full rights to the output. The license of Ace is BSD. In the header of the generated file, we should of course credit Ace as the origin of the mode and Thadee for creating the converter.

Ideally, we should try to get AsciiDoc support in CodeMirror. Perhaps the first step is to try to contribute it upstream. If that doesn't work out, we can create a separate project in asciidoctor.

Thomas, would you be willing to submit a pull request to CodeMirror? https://github.com/codemirror/CodeMirror

[nerk]

@mojavelinux @espadrine Yes, I used this tool to generate the file and manually changed/fixed two or three things, like adding asciidoctor specific support for an additional header level.

Getting this into CodeMirror would be the preferred way to go, I agree. I'll take care of the pull request.

[espadrine]

Here is what @marijnh told me when I offered to contribute it to CodeMirror: https://twitter.com/marijnjh/status/465903643095752704.

If there is a way out, I believe it would require a change in the converter. It currently includes code from Ace for compatibility reasons (rewriting the code from scratch so that it keeps the same behaviour, quirks included, is hard).

At any rate, it would help if we included someone from Ace in the conversation. @nightwing, do you know who to contact on the subject of licensing from Ajax.org?

[nerk]

That even sounds as if I would need to change the license of the Brackets plugin to BSD if I want this file being part of it... :-(

[mojavelinux]

There's a persistent misunderstanding (aka fear) about licenses that may never be eradicated. It's perfectly fine to include the source code from another project that is BSD into your MIT-licensed project, so long as you mark the original code with the original license (i.e., meet the requirements). You just can't change the BSD license on that file without the author's permission. That file will always be under that license, but it doesn't taint the source code of your whole project.

[mojavelinux]

It seems to me like the author of CodeMirror doesn't want to include a mode that came from Ace. That gives us reason to create our own repository. Eventually, when we rewrite the CodeMirror mode from scratch (as we will probably do eventually to get more accuracy), then we can contribute it to CodeMirror as original work. Given that I've written a parser for AsciiDoc, I'm pretty sure I can manage to make a CodeMirror mode :)

[nightwing]

@espadrine you can contact support@c9.io. I think sharing language modes between Ace and CodeMirror would benefit both editors.

If there is a way out, I believe it would require a change in the converter. It currently includes code from Ace for compatibility reasons (rewriting the code from scratch so that it keeps the same behaviour, quirks included, is hard).

Codemirrors simplemode seems to be compatible with ace modes.

[nerk]

@mojavelinux What you are saying regarding BSD licensing makes perfect sense. If it would be any different, why would it be allowed to integrate BSD licensed stuff into proprietary commercial applications? I will just mention the appropriate BSD license in the README.

Having a nice, more accurate mode we can share and contribute to CodeMirror would be great. We just need to find somebody to do it. I actually don't want to take ownership of this - so much other cool things I am interested in, so little time. ;-)

[mojavelinux]

If it would be any different, why would it be allowed to integrate BSD licensed stuff into proprietary commercial applications?

The fact that the code for our project is always available means that we satisfy the basic requirements of most open source licenses, in this case BSD. (We provide copyright and license information). If someone were using this project in a proprietary application, it is they who would have to deal with the requirements of files that have a different license from the project.

Having said that, both MIT and BSD-licensed source can be stuffed into proprietary commercial applications as that's sort of the premise of the licenses (very liberal freedom). See https://tldrlegal.com/license/bsd-2-clause-license-(freebsd).

[mojavelinux]

I actually don't want to take ownership of this

I tend to agree that the best person to work on these matchers is someone who is working on the parser. At the moment, that puts me in the hot seat, but I am working to get more people deeply familiar with the grammar rules so that we have more help.

[mojavelinux]

It seems to me the next step is to setup our own repo for the CodeMirror mode so that, at the very least, we can share the files within our own ecosystem of projects. Once the code is there, we can continue to pursue getting it accepted upstream as a longer-term goal (perhaps because we decide to rewrite it...or perhaps we find another path).

@nerk @anthonny @espadrine Sound like a good plan?

[mojavelinux]

we can share the files within our own ecosystem of projects

We can also track changes to it, file issues, all that good open source stuff.

[nerk]

@mojavelinux Sounds good to me. Does it even make sense to set up one single common project (or organization?) for the mode stuff of all relevant environments like IntelliJ, Eclipse, Netbeans, Ace, CodeMirror, Sublime, etc. ? Such a project would have to deal with different languages and build environments, though.

[mojavelinux]

I've found that when working on GitHub, discrete repositories always works out better. The issue tracker isn't sophisticated enough to deal with multiple components.

[SamyPesse]

Any news about publishing it as a separate module ?

[mojavelinux]

I think we should go ahead and split it out and let requirements drive how it evolves. We should set the license of that repo to BSD and credit the origin in a NOTICE file (Apache style).

Let's call the repository: asciidoctor/codemirror-asciidoc-mode

@nerk if I setup the repo and give you access, will you import the file?

@SamyPesse why repository layout would work best for you? A reference will do. (Here's a repository structure of a codemirror mode that we could mimic: https://github.com/eldargab/codemirror-markdown-mode)

[SamyPesse]

I think It'd be better to make a Node.js/Browserify package, and publish it on NPM (CodeMirror itself works really well with Browserify and is distributed on NPM).

codemirror-markdown-mode is not a Node.js package (no package.json).

So basically:

- index.js // The mode itself
- package.json
- LICENSE
- README

with a package.json like this:

{
  "name": "codemirror-asciidoc-mode",
  "version": "1.0.0",
  "description": "Asciidoc mode for CodeMirror",
  "keywords": ["asciidco", "codemirror"],
  "main": "index.js",
  "license": "BSD"
}

[mojavelinux]

Here's the space: https://github.com/asciidoctor/codemirror-asciidoc-mode

[mojavelinux]

I think It'd be better to make a Node.js/Browserify package, and publish it on NPM (CodeMirror itself works really well with Browserify and is distributed on NPM).

+1

I'm familiar with all those tools, so I can definitely help guide us towards that goal.

[mojavelinux]

Let's go ahead and put the source file inside the lib directory and name it asciidoc.js. That makes it easier to pull out of the repository for those that want to consume it ad-hoc.

lib/asciidoc.js
package.json
LICENSE
README.adoc

Since we are publishing to npm, the README should use the Markdown syntax where Asciidoctor supports it (headings, etc).

[mojavelinux]

I'll go ahead and setup all the infrastructure files and @nerk can import the asciidoc.js source file. @nerk, go ahead and create an account on npm if you don't have one yet. When you publish the package the first time, it will create it and make you the admin.

[mojavelinux]

Should we just call the repository codemirror-asciidoc ? That seems to be how things are named on npm.

[SamyPesse]

Awesome!

@mojavelinux Agree, codemirror-asciidoc is better.

BTW, We need this for the next big release of our editor, there will be an awesome new WYSIWYG editor (display of image, links, etc). It currently works very well with Markdown, but there is still work needed on the Asciidoc support.

[mojavelinux]

Awesome!!!

@nerk We'll need to modify the asciidoc.js so that it loads using require. Right now, there is Brackets-specific code in the source file.

[mojavelinux]

Renamed: https://github.com/asciidoctor/codemirror-asciidoc

Basically, the "Usage" section needs to work (it's currently pseudo code), but I've never used CodeMirror so I don't exactly know what that should be.

[mojavelinux]

We need to decide how to fill in the authors section in package.json. I figure that crediting Ace, Thaddee Tyl and Thomas Kern makes the most sense.

[SamyPesse]

@mojavelinux I think the API should look like:

var CodeMirror = require('codemirror');

require('codemirror-asciidoc')(CodeMirror);

So that codemirror will not have to be a dependency of the module; and the mode will work with any codemirror version.

The module can look like:

(function(mod) {
  if (typeof exports == "object" && typeof module == "object") // CommonJS
    module.exports = mod;
  else if (typeof define == "function" && define.amd) // AMD
    define(["codemirror"], mod);
  else // Plain browser env
    mod(CodeMirror);
})(function(CodeMirror) {
  "use strict";

  CodeMirror.defineMode("asciidoc", ...);
});

(It'll also use for direct usage in the browser or AMD).

[mojavelinux]

Thanks @SamyPesse! That's super helpful. I'll do some experimenting and tests on my end so I'm ready to review the code.

[nerk]

@SamyPesse Would you like to take ownership of codemirror-asciidoc?

[nerk]

@mojavelinux @SamyPesse Since you are already at it, the easiest would be if you just grab the asciidoc.js and go ahead.

[mojavelinux]

I got a demo working, so I'm able to test that we got the code right.

@nerk I'll import the initial version as you, then update the code to at the CommonJS / AMD wrapper.

[mojavelinux]

I think we are ready to publish a first version to npm. @SamyPesse can you test the package by running npm pack then npm install to see if it works for your needs. I'll hold off publishing until you validate.

@nerk would you like to publish the mode to npm?

The next step will be to get the ace2cm running as part of the build so that we aren't attempting to modify generated code. I think it would be best if the gulp build started from the ace component and generated the lib/asciidoc.js file from there. I'll open an issue.

[SamyPesse]

@mojavelinux It's working perfectly for us :)

[nerk]

@mojavelinux Yes, I can publish it to npmjs.com. Never published anything before to that site, lets see... @SamyPesse I assume your pull request is OK? I'll merge that first.

[SamyPesse]

@nerk Yes, My PR is correct :) (I'm using the module using require('codemirror-asciidoc');)

[nerk]

@mojavelinux @SamyPesse It's published.

[mojavelinux]

Excellent!

@nerk can you tag the releases in the git repository? In my experience, this is a manual process in the npm world.

[mojavelinux]

I'll be excited to see this make its way into the brackets plugin as an external module.

[nerk]

@mojavelinux OK, I created a 1.0.1 release on github, if that's what you meant. (I previously published and unpublished 1.0.0 to npmjs for testing purposes, but npmjs still remembers that it had a 1.0.0 version and won't let me replace it. So 1.0.1 is the one and only release on npmjs)

[mojavelinux]

That's perfect!