Rebuild Page

[jaredmorgs]

I actually followed the currently staged version on http://asciidoctor.org/docs/install-and-use-revealjs-backend/ and got it working, but I noticed when I went here to report an unrelated issue, the README was definitely different.

I would recommend rebuilding all Asciidoctor pages to ensure the latest data is live.

[mojavelinux]

@jaredmorgs This relates to the problem I mentioned in your last pull request to asciidoctor.org. The plan was to have these pages synced automatically (the website sourcing from the README in the repository). However, we didn't get around to it and now the files have diverged. This issue is covered in part by asciidoctor/asciidoctor.org#366.

Of course, we could do a manual sync in the meantime just so that the information is more updated...but that doesn't solve the problem long term.

[mojavelinux]

I would recommend rebuilding all Asciidoctor pages to ensure the latest data is live.

Since several of the files have diverged, we have to handle this very carefully. We are learning our lesson the hard way, unfortunately. Automation is not to be put off.

[jaredmorgs]

To fix the issue, would we need to do a diff on each readme vs live page and take the README as canonical?

Then see if @johncarl81 could suggest some ways of using JAQ to automate builds. I'm not sure if that rake task currently implemented in the JAQ is compatible with Awestruct.

Out of scope for this bug, but I'd love to work out how to use JAQ to automate other things as well. I'd need to read up more about how @jirutka made the rake task, and how it could be customized (if it even needs to be customized).

[jaredmorgs]

@mojavelinux So how would we handle the re-merge?

I think that while having a strategy for better synchronized documentation in the short to medium term is important, what's even more important is to sync the public-facing docs with reality (that is, what is in the READMEs)

I think another thing to do is to code the EDIT button to redirect back to the README. I think if it did that, much of the issue with file synchronization would be alleviated because the README PRs would be a reminder to rebuild, until we could implement a CI strategy.

[obilodeau]

Just submitted this PR asciidoctor/asciidoctor.org#620 which is related to this issue.

[obilodeau]

Because of the creation of http://asciidoctor.org/docs/asciidoctor-revealjs/ I think this has been resolved to anyone's satisfaction. If not please re-open.

As a side note, I just sent PR asciidoctor/asciidoctor.org#718 and I'll update my release notes not to forget in the future. So this stalled issue has been beneficial 😄

[mojavelinux]

Updated!

http://asciidoctor.org/docs/asciidoctor-revealjs/