Rework the README

[ggrossetie]

I think the sections are not in the right order:

1. About
2. Installation
3. Usage
4. Contribute/Build from sources

It could also be nice to create a more detailed documentation about the Javascript API: the Opal.hash2 is very confusing and there is a $ before method name.

Another idea is to show how to create an extension in Javascript. I look at the code generated by Opal and it's quite straightforward...

[mojavelinux]

I think the sections are not in the right order:

The problem I see is that the README is trying to be too many things right now. I think it would simplify things a lot to figure out which guides we should have and them write them individually. IMO, the README should focus on painting the broad vision of the project, where to get the distributed bits and how it works in general (meaning how to use the main API for converting documents). There should be a separate guide for developing Asciidoctor.js and another guide for using the Asciidoctor.js API. wdyt?

Another idea is to show how to create an extension in Javascript. I look at the code generated by Opal and it's quite straightforward...

:+1: This is very possible and would open a lot of doors.

[clojens]

Ok so I've been struggling with hash2 on and off the past week. Problem is I'm working on the very little documented LT editor from Cljs (UI connected, mind you different as two contexts in node-webkit) and my inexperience in Cljs having only used Clojure for the past 2 years may attribute to that. Besides the stuff which I needed to know and didn't find but had to go find would include: difference in backend/frontend ad.js (if any) and AsciidoctorJ (and other projects) perhaps (one needs to know why to choose one over the other in terms of functionality currently supported - I know AsciidoctorJ has render file and directory functionality and this kind of fso is problematic with JavaScript from a browser context. I therefor assume I have to craft my own HTML document, link stylesheet and then render body content - or I can use docbook and those would be the two supported currently(?). So yeah, as Dan said "it tries to do too many things" I agree. Really best would be a top level overview (big picture) and current status (differences between flavors available). And I must say, although correct one needs to know a fair deal Opal before use, I hardly think this should be wanted. Especially not for a single method to factor out a type, most of the stuff should be straight forward. But I recon this is also due to holy war turf (dollar, $) and everyone claiming those to their own.

---

In my case personally, the dreaded hash2 isn't much of Asciidoctor nor Opals fault I guess, but my lack of experience in writing ClojureScript, that has been a pain for the last week trying to finish the Light Table editor Asciidoctor.js plugin. I had one finished with macro'd Clojure and AsciidoctorJ but as less and less JDK will be used, thought it would be a smart move to already use the .js variant. A few things would have saved me time:

• learning if the examples showed in JavaScript is the only method relevant to us (hash2 and $convert): objects are simply too large to dive in completely every time and I hate wondering if I missed something
• for example: I still don't really know (but suspect) that the entire scope of the template/styleheet is in my ballpark and outside asciidoctor.js? If not, please include example as to instruct how one uses the library to create a full document, not just the inner html. If so, please make it clear from the beginning that there are e.g. 3 core functions a, b and c and the rest are helpers/opal objects not to be concerned with
• are there any real differences between frontend and backend asciidoctor.js besides the usual considerations, I mean is there a difference in supported features? Same goes for AsciidoctorJ besides the fact that I could make that multicore if I wanted (assuming it isn't) again, talking library functionality here (as someone asked if they could have Asciidoctor.js within AsciidoctorJ, I have to ask: why?)
• what output formats are available (doctype): only docbook, html5 and article?

For third party developers targeting Asciidoctor, I think, it might help a bit to get the overview (for me, big picture always works, before I can zoom in - else scope is potentially just too wide and I spend a lot of hours hashing through options, projects etc trying to find answers). I think the other comments in here are pretty good, stuff I covered is also in the corner of "Extension/developer guide".

P.s. personally I found documentation on (inline) macro's very lacking in explaining what/how its done. Later a few more examples were added and it became a bit clearer but it had me guessing for ages if I could define these inline, or if I had to write them in Ruby and what not.

Although, correctly, stated that one should probably learn Opal, I do not think this should be needed. There are countless of tools that interface components without the need for me to dive in to each of those immensely complex libraries/API's.

[mojavelinux]

Thanks for the input, @clojens.

I'll try to highlight some points you've made.

I've been struggling with hash2 on and off the past week.

Honestly, I don't understand why Opal doesn't accept a normal JSON object as a Hash. We could see if it's possible to hide these details behind the API...if we can't get that change in Opal itself. I agree it's a huge pain...and it's a terrible name too. Probably my biggest annoyance with Opal atm.

please include example as to instruct how one uses the library to create a full document, not just the inner html.

Agreed. This wasn't possible until Asciidoctor.js 1.5.0. Now that we're there, we should include an example on how to do it. It comes down to setting the header_footer option to true.

are there any real differences between frontend and backend asciidoctor.js besides the usual considerations, I mean is there a difference in supported features?

The goal is "no". We are still closing some gaps, but you can track those in the scheduled issues in Asciidoctor core (and related projects). There were a lot of gaps to close, now less so. Right now the focus is on getting the file I/O and extensions working flawlessly in Asciidoctor.js. Most other features should "just work".

what output formats are available (doctype): only docbook, html5 and article?

The doctype can be book, article, inline or manpage. This is mostly just about the framing around the main content...though there are some minor differences in syntax rules regarding section headings. It does not determine the output format (See http://asciidoctor.org/docs/user-manual/#document-types).

The output formats (backends) that are supported are html5 and docbook5. We'll add more as they become available. Currently, Asciidoctor.js does not support the template-based converter, so you don't have access to the additional backends in asciidoctor-backends like deck.js.

personally I found documentation on (inline) macro's very lacking in explaining what/how its done.

Documentation for extensions is very lacking in general. That's because we literally just got them working in recent releases and have yet to catch up with documentation. They're just emerging from beta...perhaps we can consider them still beta atm. Writing extensions in JavaScript is literally bleeding edge.

Although, correctly, stated that one should probably learn Opal, I do not think this should be needed.

Neither do I. I think we can successfully hide most, if not all, of the details of Opal behind the APIs.

[mojavelinux]

In regards to my last statement, that's what #92 is partially about.

[ggrossetie]

Very useful input thanks, we will do our best to clarify the README but I think we will need a more in-depth guide on the Asciidoctor website ? If you have some ideas for the API (to hide details about Opal) feel free to join us #92

[mojavelinux]

I'd like to move forward with the idea of each project having its own manual in addition to the README. We need room to grow. The README should be just that, essential information you need to know first with pointers to all the relevant information.

We can start with a docs folder. In that folder should be a file for major categories of content (using API, extending, setup, etc) as well as a master file. We'll then pull this content into the website in some automated way.

We can pursue creating a dedicated manual in a separate issue if you'd like.

[clojens]

@mojavelinux Thanks for taking the time to answer. I agree with, especially also the aesthetical objections you make, wrapping them would probably make sense but I'd like to stress it is mostly my own doings though. 1) new to Cljs (from Clj and imho that didn't help too much) 2) new LT 3) new to Opal 4) transpilers here and there 5) node-webkit double whammy context - it's no wonder it can get a bit confusing but its a good training day and I learn so very much this way .. I'm just saying, I'm not complaining :) JSON would have probably saved both of us some pain indeed, LT uses back and forth EDN/JSON and it works nice. But the augmented types provided by Opal are picked up and my troubles really are in the fact that I try to develop in the UI context now and I probably just need to work with callbacks. In Clojure, I would have syntax-quoted (again it didn't help thinking from that perspective mindset, need to think node-webkit event loops). Btw Opal.hash does work fine and generates a $Hash type from a seq of even string input to k/v. I don't really get why hash2 needs to have keys twice (once in the array which is extended I think) and once as actual keys of the second argument map. A bit superfluous but might be just that it destructures more easily this way. Anyway no real show stopper, and since I'm used to having to wrap stuff anyway and (sometimes ugly) special forms or sugar, also I can use normal JS dotted form as well use string object nested access. Most of the final editor stuff is abstracted away through Behavior Object Tag model from end-user anyway, so I can live with a few warts here and there.

I did take the time today to really study atom-asciidoctor-preview code and what it does. Which I should had done straight away also since it uses Node.js. It cleared up a lot of things and so I've got a good idea what I need to do in terms of plumbing on the LT plugin and Asciidoctor aspect. I'm more than fine with the way it is now in that respect, Asciidoctor doesn't get in your wheels or anything and limits to just the bare it needs to do. The rest is just hooking up attributes to controls and doing file system/stream operations. Piece of cake :) The only showstopper is really hash2 returning an empty map or one I can't use (yet) but on the defaults from empty map - I can still get 'article' output which is fine for now.

If I have any input to give or something, I'll gladly share if there's anything useful I've noticed. For now more tinkering though.

[mojavelinux]

I don't really get why hash2 needs to have keys twice (once in the array which is extended I think) and once as actual keys of the second argument map.

My thoughts exactly. I'd definitely like to see if we can get rid of the requirement to use that class, instead using a regular JSON object. I'll file a separate issue to track it.

[mojavelinux]

See https://github.com/asciidoctor/asciidoctor.js/issues/94.