Convert to AsciiDoc

[pirj]

Fixes #95

The conversion went quite well, there's no visual difference between the old and the new, except for increased vertical whitespace in lists, you can notice it by looking at ToC.

I'm not too happy about one thing. The recommendations were using bulleted list, and it seems that in AsciiDoc multi-line text in lists are done by adding a + (line break?) to the beginning of the line, which doesn't make it more readable in the editor.

Tried using sections, to add §, however GitHub seems to add it to the sections anyway, with an id auto-generated from the title itself. Tried all possible combinations of :sectids: / :sectanchors: / :sectlinks: to no avail.

Another option would be to insert a Unicode bullet symbol to beginning of recommendations, and added horizontal rules between recommendations. Added it to a couple of recommendations in the in the beginning of the guide. Please take a look and let me know what you think.

[bbatsov]

I'm not too happy about one thing. The recommendations were using bulleted list, and it seems that in AsciiDoc multi-line text in lists are done by adding a + (line break?) to the beginning of the line, which doesn't make it more readable in the editor.

Yeah, just saw what you mean here https://github.com/powerman/asciidoc-cheatsheet/blob/master/README.adoc Seems like a GitHub issue though, but it's definitely lame.

Another option would be to insert a Unicode bullet symbol to beginning of recommendations, and added horizontal rules between recommendations. Added it to a couple of recommendations in the in the beginning of the guide. Please take a look and let me know what you think.

That's fine, but it's a bit annoying to type. I wonder if there's a way to circumvent GitHub's default behaviour somehow. @mojavelinux might know some tricks, so I'll ping him.

[bbatsov]

Btw, here are few useful tips about AsciiDoc on GitHub https://gist.github.com/dcode/0cfbf2699a1fe9b46ff04c41721dda74

[bbatsov]

Have you seen this issue https://github.com/asciidoctor/asciidoctor/issues/1087 ? Seems exactly like the problem we're trying to solve here.

[mojavelinux]

The recommendations were using bulleted list, and it seems that in AsciiDoc multi-line text in lists are done by adding a + (line break?) to the beginning of the line, which doesn't make it more readable in the editor.

The + is a list continuation. (See https://asciidoctor.org/docs/user-manual/#list-continuation) It allows you to attach additional blocks to a list item. It has nothing to do with multi-line text. You can have as many lines in the text of a list item as you want. It's about multiple blocks. If you want to attach a separate block, such as a paragraph or code block, then you need a list continuation. And this is not specific to GitHub. It's how AsciiDoc has always been (dating back almost 20 years).

If you are going to attach more than one block to a list item, I recommend enclosing the content in an open block, which saves you from having to use more than one list continuation per list item. In other words:

* item text
+
--
paragraph

[,ruby]
----
puts 1
----

another paragraph
--

[mojavelinux]

Another option would be to insert a Unicode bullet symbol to beginning of recommendations, and added horizontal rules between recommendations.

I strongly discourage sacrificing semantics for presentation. That goes against what AsciiDoc is about. If you don't like having to attach blocks to a list item, then I would recommend switching to sections. The benefit is that the section title (aka heading) is linkable.

[mojavelinux]

Using passthroughs (triple plus) is very bad practice. In all cases, they are being used to define an anchor, which is already supported in AsciiDoc (e.g., [[anchor]]).

[mojavelinux]

Have you seen this issue asciidoctor/asciidoctor#1087 ? Seems exactly like the problem we're trying to solve here.

GitHub could add styles to their stylesheet to reduce the space between list items. However, thus far they have not showed a willingness to do so. The proposal for Asciidoctor is to change the default HTML converter to wrap the primary text of list items using a "span" instead of a "p". That would make the problem go away.

[mojavelinux]

May I ask you for a tip on how to structure this document using sections?

You'd need to assign each rule a name. But since you already have IDs for each rule, you can simply reverse engineer a heading that would produce that ID. Then, you knock out a whole bunch of problems at once (backwards compatible IDs, floating anchors, automatic TOC, no need for list continuations). And it's just going to make the whole document easier to navigate.

Here's an example:

=== Empty Lines After Describe

Do not leave empty lines after `feature`, `context` or `describe` descriptions.
It doesn't make the code more readable and lowers the value of logical chunks.

that diverges from just the primary id link that we'd love to be the only one to avoid the confusion of having two differently named anchors for the same section. Is there a way around this?

Simply reverse engineer the section heading to produce the same ID. (This may require some trial and error). Unfortunately, GitHub doesn't let you specify an explicit ID, even though this is a core feature of AsciiDoc.

[pirj]

@mojavelinux Thanks for providing precious information on how to better structure the guide. Followed your recommendations, everything worked like a charm.

I was a bit sceptic regarding moving to AsciiDoc, now I don't have a single doubt that the guide's look and internal representation have improved.

@bbatsov @andyw8 Appreciate if you take a look.

Each recommendation has a title and is represented by an anchorable section. The old anchors for external resources linking to the guide. Since the guide had some _NOTE_, they became admonitions.

[mojavelinux]

@pirj I'm so happy to hear that. I was glad to help you on your journey.

The old anchors for external resources linking to the guide.

Ah, now I see why some sections have an inline ID. In that case, I agree it's the right way to add a secondary ID for legacy purposes. :+1:

Since the guide had some NOTE, they became admonitions.

That's the beauty of AsciiDoc right there. Semantics FTW!

[mojavelinux]

Ah, now I see why some sections have an inline ID. In that case, I agree it's the right way to add a secondary ID for legacy purposes.

I'll reiterate that I'm particularly excited to learn that GitHub now honors AsciiDoc anchors (e.g., [[anchor]]), so you're free to sprinkle them wherever you need them.

[mojavelinux]

And btw, it looks really great!

[bbatsov]

@pirj Looks good to me too! Only the TOC's heading is a bit weird - its actually smaller than the elements in the TOC.

Now I guess we'll have to follow suit with the other guides and afterwards we can also publish them on some simple site using git submodules or something like that.

[mojavelinux]

Only the TOC's heading is a bit weird - its actually smaller than the elements in the TOC.

You can fine tune this using the toc-title attribute. You can either disable it:

:!toc-title:

or make it big and bold:

:toc-title: pass:[<h3>Table of Contents</h3>]

[pirj]

Thanks a lot for the help guys!