interesting - thanks for digging into this. do you mind doing a copy/paste/format of these tips to the dev docs so that they aren't lost in the mailing list:
http://tinkerpop.apache.org/docs/current/dev/developer/#documentation On Wed, Mar 27, 2019 at 6:23 AM Robert Dale <[email protected]> wrote: > 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 >
