number is ignored/replaced by 1 if it is followed by a dot

[madmas]

The result of a document like

= Index page
:toclevels: 1
:numbered:

=== Sprint 2015/16

14 - 27.8.2015

=== Sprint 2015/16

14. - 27.8.2015

is

Note the missing 4 in the second part where the 14 should be followed by a dot.

My assumption is that the parser interprets this as the beginning of a new list and ignores the characters before the dot while the intention is completely different ;-)

I reproduced this with a plain asciidoc based on the current lazybones template, which then uses these dependencies:

         'org.asciidoctor:asciidoctor-gradle-plugin:1.5.2'
         'org.asciidoctor:asciidoctorj-pdf:1.5.0-alpha.6'
         'com.github.ben-manes:gradle-versions-plugin:0.8'
         'com.bluepapa32:gradle-watch-plugin:0.1.5'

[AlanDaniels101]

This seems to be because of the ordered list regex. If you have one letter or any number of digits followed by a dot and another character, it treats it as an ordered list.

There's another issue in that the list always starts at the first number/letter, regardless of what you begin the list at. This contradicts the documentation: http://asciidoctor.org/docs/user-manual/#ordered-lists. Using [start] works though. More on this, the roman numerals are a subset of [a-z,A-Z], and they get detected as alpha, not roman. Finally, multiple roman numerals aren't detected, such as ii..

I would be happy to look at this, but I don't know what the intended behavior is.

Option 1 - Only accept ., a., or 1. (etc) as the start of an ordered list.

Option 2 - Correctly keep track of the starting digit/letter.

[mojavelinux]

This happens to the expected behavior assuming the goal is alignment with AsciiDoc Python. (Unexpected, perhaps, but still compliant). @AlanDaniels101 correctly points out that an ordered list is detected if the line begins with a letter or number followed by a dot followed by a space (except you missed roman numerals).

One workaround you can use today is to put a blank placeholder in front of the number to hide it from the parser:

{empty}14. this is just a number

or

:dot: .

14{dot} this is just a number

It works, but it's not pretty.

@AlanDaniels101 thanks for pointing out that the documentation is wrong. You have identified the alternate options that we have perfectly. Keep in mind that Option 0 is to keep the current behavior and document it.

Since AsciiDoc doesn't currently allow the start of the list to be set by the first number used (counter to what the documentation says), it makes sense that we would choose Option 1. However, Option 2 is certainly tempting because it could be a nice time saver when you often need to set the start number of a list. One the other hand, Option 2 doesn't solve the problem at hand.

If we think about the problem at hand, should we allow the period to be escaped?

14\. this is just a number

Any other ideas?

[AlanDaniels101]

There should be some way to escape making a list. Escaping the period would be good, but it's not intuitive that you would need to do it. Is there an equivalent to [literal] without the formatting?

Even with Option 0, there are still some bugs. Take this as an example:

2. List

ii. Not list

i. Alpha list

I think Option 1 is good because the useful functionality does not change, it is more intuitive, and it should be a simple change. Escaping the period is still another task on top of this.

[mojavelinux]

Ah, of course! We could make a normal paragraph explicitly by using:

[normal]
14. is just a number

We don't currently do that, but it makes total sense that we could. I think that's another reasonable step forward here. In fact, we probably want to recognize all built-in (and perhaps even registered) block names to suppress launching into a list.

[AlanDaniels101]

Moving forward,

1. Implementing [normal].
2. Would you like to go with Option 1? If not, fixing the detection of ii, vi, etc?

[mojavelinux]

Implementing [normal] makes a lot of sense. I'd like to dig into the code and see how difficult that's going to be. That will determine what extent we want to try this. Here's my general thoughts:

In places that look for a list, once you find a list, check the style. If the style is "normal" (or another built-in block name), then veto the match. It's not a list.

If we decide to enforce an ordered list start with 1, a, A or I, then the regexp that needs to be modified is AnyListRx. Once that passes, you don't need to worry about checking in the OrderedListRx because you know you are now at a list. In other words, AnyListRx is the main test.

I'm still undecided whether we should allow the start to be defined by the first entry in the list. Intuition tells me it should be allowed, especially since we're already catching it...so it's not like the parser is really changing here. I think we should move forward with it.

In other words,

5. five
. six

is equivalent to

[start=5]
. five
. six

The first step would be to write a failing test, then we can go in there and start getting the code sorted out.

[mojavelinux]

...I have to say, that's pretty enticing :)

[AlanDaniels101]

This is somewhat tangential. I'm new to asciidoctor, so I was wondering if there was a way to build asciidoctor locally. If I use asciidoctor myfile.adoc it uses the ruby gem. It seems like it would be convenient to be able to replace asciidoctor with a version that has changes. asciidoctor_local myfile.adoc or asciidoctor_test myfile.adoc for instance.

[mojavelinux]

Indeed. Asciidoctor is designed so that you can run the script directly out of the cloned repository. Just run:

$ ./bin/asciidoctor README.adoc

(or whatever the relative path is to the bin folder).

I have the following alias setup on my machine so that I can run asciidoctor-local from anywhere:

alias asciidoctor-local="$HOME/projects/asciidoctor/bin/asciidoctor"

This is something we need to include in the contributing guide.

[mojavelinux]

I added a section to the CONTRIBUTING file to cover this. See https://github.com/asciidoctor/asciidoctor/blob/master/CONTRIBUTING.adoc#running-asciidoctor-in-development-mode

[AlanDaniels101]

Thanks. I think I was able to run the local version. But I'm still unsure of (or having difficulties with) building asciidoctor. Say I want to make regex changes and see what affect it has.

[mojavelinux]

Say I want to make regex changes and see what affect it has.

You should run the tests, which you can do using ./run-tests.sh.

You should never have to "build" asciidoctor. The only time that's needed is if you are publishing the gem. Otherwise, you just run the tests are run asciidoctor-local.

You can check your version of asciidoctor-local using

$ asciidoctor-local -v

It should say 1.5.3.dev.

[AlanDaniels101]

Can I modify the behavior of asciidoctor-local? I.e. change the result of $ ./bin/asciidoctor README.adoc

[mojavelinux]

Indeed. Simply change the code in the cloned repository and run asciidoctor-local again. The quickest way to see the effect of your changes is to break the code and make sure that the command breaks.

If you have other general questions about how to develop Asciidoctor, I recommend asking on the mailing list at http://discuss.asciidoctor.org. That way, you can get help from more people in the community.

[AlanDaniels101]

Thanks! I think I'm on top of it now. I'm actually using Windows (sorry), and that has brought up some problems. Although my Command Prompt accepts Unix commands, something like ./bin/asciidoctor README.adoc still doesn't work. It's not too convenient, but I can do it in Cygwin.

[AlanDaniels101]

Back to the problems at hand. One thing is that roman numerals are detected, but only with a parenthesis at the end. For example, ii) goes to i. but ii. is not detected as an ordered list. Should the regex be changed to take . instead of ), or should roman numerals use )?

[mojavelinux]

something like ./bin/asciidoctor README.adoc still doesn't work

I think on Windows you need to use:

ruby bin/asciidoctor README.adoc

I haven't tried it though.

One thing is that roman numerals are detected, but only with a parenthesis at the end.

That just seems to be the way that the AsciiDoc syntax was designed. I think this was done so that i. is not confused with a Roman numeral. I think it's fine this way (though I've never seen anyone use Roman numerals for lists).

[AlanDaniels101]

I have a simple change that does

5. five
6. six

equals

[start=5]
. five
. six

but

5. five
. six

does not work. That's a different issue because

5. five
. six

gives

1. five
  1. six

not

1. five
2. six

without my change.

See #1509

[AlanDaniels101]

[normal]
14. is just a number

Looks like this exists already, with [pass] or +++.

[mojavelinux]

I'd like to point out that we have the same problem with letters. For example, the following is interpreted as a list:

J. B. Rainsberger states something very similar to the above...

as reported here: http://discuss.asciidoctor.org/weird-translation-td3381.html

One proposed solution is to change the syntax for starting a list with a letter from J. to .J. (notice the leading dot). However, the solutions we've discussed in this issue might turn out to be more viable and compatible.

[mojavelinux]

Here's another workaround, for those looking for a solution today:

14.{sp}this is just a number

[mojavelinux]

Since we've veered off from the original issue, I've opened another issue to track this improvement. Let's continue the discussion in #2218.

[mojavelinux]

To be clear, I'm moving the discussion related to explicit numbering affecting the start value. This issue can continue on regarding how to escape lists.

[mojavelinux]

One way to write this is:

[pass,subs=normal]
++++
14. is just a number
++++

That's not pretty, but it does work.

[mojavelinux]

I still like the idea of using [normal] over a paragraph, though I think what makes the most sense is to support a backslash escape.

Commonmark defines the following escape for ordered lists*:

1\. not a list item

Here's how we could build on that citing the examples above:

14\. is just a number

J\. B. Rainsberger states something very similar to the above

That's easy to remember.

* Commonmark has a similar escape for unordered lists:

\* not a list item