Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Convert to AsciiDoc #97

Merged
merged 3 commits into from May 7, 2019

Conversation

@pirj
Copy link
Member

commented May 2, 2019

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.

@pirj pirj self-assigned this May 2, 2019

@pirj pirj force-pushed the convert-to-asciidoc branch from 3bd91b7 to 33a154c May 2, 2019

@pirj pirj requested review from bbatsov and andyw8 May 3, 2019

@bbatsov

This comment has been minimized.

Copy link
Contributor

commented May 3, 2019

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

This comment has been minimized.

Copy link
Contributor

commented May 3, 2019

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

@bbatsov

This comment has been minimized.

Copy link
Contributor

commented May 3, 2019

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

@mojavelinux

This comment has been minimized.

Copy link

commented May 3, 2019

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

This comment has been minimized.

Copy link

commented May 3, 2019

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.

README.adoc Outdated Show resolved Hide resolved
README.adoc Outdated Show resolved Hide resolved
README.adoc Outdated Show resolved Hide resolved
README.adoc Show resolved Hide resolved
README.adoc Outdated Show resolved Hide resolved
@mojavelinux

This comment was marked as outdated.

Copy link

commented May 3, 2019

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

This comment has been minimized.

Copy link

commented May 3, 2019

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.

@pirj
Copy link
Member Author

left a comment

@mojavelinux thanks for the review!

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

What we're struggling with is a primary section ids that we'd love to keep for historical reasons, some may have referenced it. On the other hand, the section titles won't necessarily match, and, as a matter of fact, we don't have section titles at the moment, we go straight to the contents.

GitHub combines the title and the primary id I specify, and uses that for the § link, and 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?

README.adoc Outdated Show resolved Hide resolved
README.adoc Outdated Show resolved Hide resolved
README.adoc Show resolved Hide resolved
README.adoc Outdated Show resolved Hide resolved
README.adoc Outdated Show resolved Hide resolved
README.adoc Outdated Show resolved Hide resolved
@mojavelinux

This comment has been minimized.

Copy link

commented May 5, 2019

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.

README.adoc Show resolved Hide resolved
@pirj

This comment has been minimized.

Copy link
Member Author

commented May 6, 2019

@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

This comment has been minimized.

Copy link

commented May 6, 2019

@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. 👍

Since the guide had some NOTE, they became admonitions.

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

@mojavelinux

This comment has been minimized.

Copy link

commented May 6, 2019

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

This comment has been minimized.

Copy link

commented May 6, 2019

And btw, it looks really great!

@andyw8

andyw8 approved these changes May 7, 2019

Copy link
Member

left a comment

Nice work, looks great.

@bbatsov

This comment has been minimized.

Copy link
Contributor

commented May 7, 2019

@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.

@bbatsov

bbatsov approved these changes May 7, 2019

@mojavelinux

This comment has been minimized.

Copy link

commented May 7, 2019

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 pirj force-pushed the convert-to-asciidoc branch 2 times, most recently from efb891e to 2dda387 May 7, 2019

@pirj pirj force-pushed the convert-to-asciidoc branch 3 times, most recently from 2a1846e to 911fafe May 7, 2019

pirj added some commits May 2, 2019

Convert to AsciiDoc
AsciiDoc allows for admonitions, footnotes, sane nesting of list items,
and easily export in various formats.

Fixes #95

@pirj pirj force-pushed the convert-to-asciidoc branch from 911fafe to 8ded708 May 7, 2019

@pirj pirj merged commit a7115b5 into master May 7, 2019

@pirj pirj deleted the convert-to-asciidoc branch May 7, 2019

@pirj

This comment has been minimized.

Copy link
Member Author

commented May 7, 2019

Thanks a lot for the help guys!

@pirj pirj referenced this pull request Jun 1, 2019

pirj added a commit to rubocop-hq/rails-style-guide that referenced this pull request Jun 1, 2019

Initial conversion by kramdown-asciidoc
AsciiDoc allows us to have native admonitions, footnotes, sane nesting
of list items, etc and to easily export the guide in various formats.
That would also make it trivial to publish a simple site from the guide
down the road if we want to.

A longer term plan is to convert all guides to AsciiDoc and maybe even
RuboCop's own documentation.  RSpec style guide [has been recently
converted](rubocop-hq/rspec-style-guide#97).

bbatsov added a commit to rubocop-hq/rails-style-guide that referenced this pull request Jun 2, 2019

Convert the guide to AsciiDoc (#250)
AsciiDoc allows us to have native admonitions, footnotes, sane nesting
of list items, etc and to easily export the guide in various formats.
That would also make it trivial to publish a simple site from the guide
down the road if we want to.

A longer term plan is to convert all guides to AsciiDoc and maybe even
RuboCop's own documentation.  RSpec style guide [has been recently
converted](rubocop-hq/rspec-style-guide#97).

pirj added a commit to rubocop-hq/ruby-style-guide that referenced this pull request Jun 3, 2019

Convert to AsciiDoc
AsciiDoc allows us to have native admonitions, footnotes, sane nesting
of list items, etc and to easily export the guide in various formats.
That would also make it trivial to publish a simple site from the guide
down the road if we want to.

A longer term plan is to convert all guides to AsciiDoc and maybe even
RuboCop's own documentation. RSpec and Rails style guides have been recently
converted:
  - rubocop-hq/rspec-style-guide#97
  - rubocop-hq/rails-style-guide#250
@pirj pirj referenced this pull request Jun 3, 2019

bbatsov added a commit to rubocop-hq/ruby-style-guide that referenced this pull request Jun 3, 2019

Convert to AsciiDoc
AsciiDoc allows us to have native admonitions, footnotes, sane nesting
of list items, etc and to easily export the guide in various formats.
That would also make it trivial to publish a simple site from the guide
down the road if we want to.

A longer term plan is to convert all guides to AsciiDoc and maybe even
RuboCop's own documentation. RSpec and Rails style guides have been recently
converted:
  - rubocop-hq/rspec-style-guide#97
  - rubocop-hq/rails-style-guide#250
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
4 participants
You can’t perform that action at this time.