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 Fri, 14 Jun 2019 11:39:36 GMT
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 <robdale@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 <spmallette@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 <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