Sums it up nicely. Bonus, if you go to the '...' dropdown and select 'View file', it looks like everything is rendered correctly.
Robert Dale On Fri, Jun 14, 2019 at 7:39 AM Stephen Mallette <[email protected]> wrote: > I went ahead an added your tips to the dev docs: > > > https://github.com/apache/tinkerpop/commit/ddac926ca8f22239e83658ffee65ec2415b3b838 > > > hope that looks ok. > > On Thu, May 30, 2019 at 8:56 AM Robert Dale <[email protected]> wrote: > > > 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 <[email protected]> > > 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 <[email protected]> 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 < > [email protected] > > > > > > > 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 <[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 > > > > > > > > > > > > > > > > > > > > >
