You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tinkerpop.apache.org by Robert Dale <ro...@gmail.com> on 2019/04/02 17:28:29 UTC
Re: Some Asciidoc Tips and Fixes
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 <sp...@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 <ro...@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
> >
>
Re: Some Asciidoc Tips and Fixes
Posted by Robert Dale <ro...@gmail.com>.
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 <sp...@gmail.com>
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 <ro...@gmail.com> 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 <sp...@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 <ro...@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 <
> spmallette@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 <ro...@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
> > > > > >
> > > > >
> > > >
> > >
> >
>
Re: Some Asciidoc Tips and Fixes
Posted by Stephen Mallette <sp...@gmail.com>.
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 <ro...@gmail.com> 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 <sp...@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 <ro...@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 <spmallette@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 <ro...@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
> > > > >
> > > >
> > >
> >
>
Re: Some Asciidoc Tips and Fixes
Posted by Robert Dale <ro...@gmail.com>.
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 <sp...@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 <ro...@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 <sp...@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 <ro...@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
> > > >
> > >
> >
>
Re: Some Asciidoc Tips and Fixes
Posted by Stephen Mallette <sp...@gmail.com>.
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 <ro...@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 <sp...@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 <ro...@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
> > >
> >
>