I haven't added this to the docs yet. As an update to #1, even `__` will render as a nested emphasis if there is a following `__` in the same paragraph, i.e. sentences touching, not separated by 2 or more newlines. For example, http://tinkerpop.apache.org/docs/current/reference/
The source is: NOTE: The `AnonymousTraversal` class above is just an alias for `__` as in `from gremlin_python.process.graph_traversal import __ as AnonymousTraversal` Renders as: The AnonymousTraversal class above is just an alias for *as infrom gremlin_python.process.graph_traversal import *as AnonymousTraversal Should be: The AnonymousTraversal class above is just an alias for __ as in from gremlin_python.process.graph_traversal import __ as AnonymousTraversal This is fixed by the same method: `+__+`. Source fixed: NOTE: The `AnonymousTraversal` class above is just an alias for `+__+` as in `+from gremlin_python.process.graph_traversal import __ as AnonymousTraversal+` Robert Dale On Tue, Apr 2, 2019 at 1:59 PM Stephen Mallette <spmalle...@gmail.com> wrote: > eh...looks like those two sections could be better handled. the intent for > "Writing Documentation" was to give new contributors some basic > instructions as to what was involved in doing that. the "Documentation" > section is supposed to be for existing committers. maybe just push the > details of of "Writing Documentation" down to "Documentation" and then add > your new tips there? just leave enough in "Writing Documentation" to > introduce new contributors to it and then add a link to "Documentation"? i > don't have really strong feelings about how to organize it. if you think > there is a better way to make that clean, feel free to propose something or > just leave it as it is and add your stuff where you feel it best fits. > > On Tue, Apr 2, 2019 at 1:28 PM Robert Dale <robd...@gmail.com> wrote: > > > 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 > > > > > > > > > >
