search

asciidoctor / asciidoctor.org

:globe_with_meridians: Asciidoctor project site. Composed in AsciiDoc. Baked with Awestruct.
https://asciidoctor.org
Other
323 stars 803 forks source link

switch Asciidoctor.js guide to use README from upstream project #750

Closed mojavelinux closed 6 years ago

mojavelinux commented 6 years ago

@Mogztter This PR changes the Asciidoctor.js page on asciidoctor.org to use the README from the upstream project. This is a first step in the migration to Antora as it reconciles the two authorities.

There are two outstanding issues to be addressed before merging. First, the links to the contributing and license file are broken because the uri-rel-file-base from the README is overriding the value defined in the master file. The attribute entries needs to be changed to the following in the README:

ifndef::uri-rel-file-base[:uri-rel-file-base: link:]

Second, the two documents had different introductions. Is there anything from the old introduction you want to preserve?

Asciidoctor.js is a JavaScript port of Asciidoctor. With asciidoctor.js, the {asciidoc}[AsciiDoc] syntax can be used in the browser!

Introduction

The {asciidoctorjs-git}[asciidoctor.js project] is a direct port of Asciidoctor from Ruby to JavaScript using the {opal}[Opal] Ruby-to-JavaScript cross compiler. It consists of a Rake build script that executes the Opal compiler on the Asciidoctor source code to produce the asciidoctor.js script.

Opal parses the Ruby code and any required libraries, then rewrites the code into JavaScript under the Opal namespace. The resulting JavaScript can be executed within any JavaScript runtime environment (such as a browser).

To interact with the generated code, you either invoke the JavaScript APIs directly, or you can invoke native JavaScript objects from within the Ruby code prior to compilation.

ggrossetie commented 6 years ago

Thanks.

I think the old introduction is a bit too technical and should be moved to a "deep dive" section where we explain how Asciidoctor.js is generated.

Words like "cross compiler" can be intimidating and since Opal is hidden behind a public API we can talk about this implementation detail later.

What do you think ?

mojavelinux commented 6 years ago

Sounds reasonable to me. I just wanted to give you a chance to see what was being removed before taking it away. If you think it's not needed, then :hocho:.

mojavelinux commented 6 years ago

@Mogztter Can you change the uri-rel-file-base attribute in the upstream README?

I also noticed that the copyright year is behind. At this point, you might as well just set it to 2018.

ggrossetie commented 6 years ago

Can you change the uri-rel-file-base attribute in the upstream README?

Done!

At this point, you might as well just set it to 2018.

Too soon :laughing:

mojavelinux commented 6 years ago

And we're live!

Once a new release is out, we'll want to switch from using the master URL to the tag. Then, each time you make a release, you'll need to update the version number in this file (at least, in the short run).

ggrossetie commented 6 years ago

Yeah! :tada:

ggrossetie commented 6 years ago

@mojavelinux I get a 404 when I click on the licence or the user manual link. Did I miss something with the uri-rel-file-base attribute ?

mojavelinux commented 6 years ago

Oops, I forgot to switch it over to the README from the master branch. We can switch back to the release once the next release is out.