tinkerpop-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Robert Dale <robd...@gmail.com>
Subject Re: Some Asciidoc Tips and Fixes
Date Tue, 02 Apr 2019 17:28:29 GMT
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 <robdale@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
> >
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message