Should it be there <http://tinkerpop.apache.org/docs/current/dev/developer/#documentation> or here http://tinkerpop.apache.org/docs/3.4.1/dev/developer/#_writing_documentation ?
Robert Dale On Sat, Mar 30, 2019 at 9:35 AM Stephen Mallette <spmalle...@gmail.com> wrote: > 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 <robd...@gmail.com> 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 > > >
