0. Asciidoctor is not Asciidoc (applications) This was not immediately obvious to me when I started. I have found that Asciidoc renders the following scenarios correctly. However, our maven build uses Asciidoctor which rendered incorrectly. So if you write asciidoc and use some tool to preview content and it looks good, verify which tech it is using underneath. If it's not asciidoctor or you're not sure, it would be a good idea to use the command-line asciidoctor tool or even better to use the maven build.
1. Two anonymous traversals (__) in inline code This will cause the content between the two __ to become emphasized (italicized) E.g. http://tinkerpop.apache.org/docs/current/reference/#graph-traversal-steps To reduce the verbosity of the expression, it is good toimport static org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.*.***. This way, instead of doing *.inE() for an anonymous traversal, it is possible to simply write inE(). Be aware of language-specific reserved keywords when using anonymous traversals. For example, in and as are reserved keywords in Groovy, therefore you must use the verbose syntax *.in()** and *.as() to avoid collisions. Cause: Asciidoctor doesn't always do literal pass-through. Appears to be a limitation of their parser. https://github.com/asciidoctor/asciidoctor/issues/1717 https://github.com/asciidoctor/asciidoctor/issues/1066 Solution: Instead of: `from __ gremlin_python.process.graph_traversal import __ as AnonymousTraversal` Use plus: `+from __ gremlin_python.process.graph_traversal import __ as AnonymousTraversal+` Or, use pass: `pass:[from __ gremlin_python.process.graph_traversal import __ as AnonymousTraversal]` 2. Content immediately following backtick doesn't render correctly There appear to be some exceptions. E.g. https://github.com/apache/tinkerpop/blob/3.4.1/CHANGELOG.asciidoc#tinkerpop-312-release-date-april-8-2016 Deprecated ScriptElementFactory and made the local StarGraph globally available for ScriptInputFormat’s `parse() method. Cause: Parsing limitation. https://github.com/asciidoctor/asciidoctor/issues/1514 Solution: Use double backtick if there is non-whitespace immediately following the trailing backtick. Original: [...] globally available for `ScriptInputFormat`'s `parse()` method. Fixed: [...] globally available for ``ScriptInputFormat``'s `parse()` method. Robert Dale
