Update new features into AsciiDoc Syntax Reference

[lordofthejars]

There are some amazing aspects released on Asciidoctor 0.1.3 that are documented in news section but not in AsciiDoc Syntax Quick Reference. I think would be good have all features documented in a single document so anyone new can learn all features without having to read more than one document.

[mojavelinux]

+1

[lordofthejars]

Apart from new features, I think it could be interesting to document issue asciidoctor/asciidoctor#116 because I think it is really interesting feature. I will try to update AsciiDoc Syntax Quick Reference document with all these features when I had some time.

[graphitefriction]

I had to look up what a docinfo file was. If I understand it correctly, it is a file that can contain document header attributes, JavaScript scripts, and CSS styles (when applied to the html5 backend)?

I'm also assuming that it is defined when :docinfo: is added to the document's header?

1. How does it know where to find the docinfo file?
2. What is the structure and applicable syntax in the docinfo file?
3. Is anyone using one that we could use as an example?
4. Are there different rules and constraints when using the DocBook backend?

Next, this issue (Update new features into AsciiDoc Syntax Reference) is indicative of a larger documentation conundrum 💔

Asciidoctor now has so many features (new, compliance, integrations, backends, and implementations) that the Quick Reference Guide is no longer a quick read because it is growing into a guide to all the Asciidoctor features. And it is growing into the complete reference guide because we haven't created a complete reference guide 🙀

For now, I have updated the Quick Reference Guide with most of the new syntax and features from 0.1.3 (I'll commit it by the end of the day today MDT).

However, this is just a stop gap. A complete reference guide of all the Asciidoctor features is needed and is in the works. First though, we need to decouple the docs from the website (See asciidoctor/asciidoctor#541).

[lordofthejars]

Hi,
well you can see an example in Dan's deck repository https://github.com/mojavelinux/decks/tree/master/discover-zen-writing-asciidoc which is used for setting some css attributes in slides.

Also you can watch this issue (asciidoctor/asciidoctor#116) which is the original implementation of docinfo support and contains the documentation of AsciiDoc original guide explaining the attributes. As you will read on that document you will see that there are three possible attributes docinfo, docinfo2 and docinfo3. The first one includes a document with next file format Include -docinfo., the second one docinfo. and the third one both formats. Also keep in mind that in case of html output a extension of that file is html, and in case of docbook it is an xml extension.

Also it is important to note that you can still resolve attribute values into that files, here you can see an example, basically you can get attribute values defined in adoc files.
asciidoctor/asciidoctor#403

And finally if you inspect issue asciidoctor/asciidoctor#486, for 0.1.4 version this files would be possible to be included in footer instead of header.

About documentation I agree with you that quick reference is becoming to a full documentation. In my opinion, I think that this documentation should add next big chapters:

• how to install / render a document
• reference
• customizing (templates, stylesheets, ..)
• Working with Ruby (which includes how to write filters, extensions, extensions, ...)
• Toolchain (Java, Maven, Gradle, Asciidoctor.js, ...)

Also when all documentation will be written, I will translate it to Spanish, so I think we must think about an structure which allows us writing in different languages.

[graphitefriction]

@lordofthejars I've moved your chapter recommendations over to the Docs wiki in preparation for this issue being closed once the pull requests are reviewed.

Thank you for your input about the documentation and for pulling together the information sources regarding the docinfo files. ✨

[lordofthejars]

A pleasure to help you.