tinkerpop-dev mailing list archives

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