Line numbering on a source block should be enabled via linenums option #1981

Open
mojavelinux opened this Issue Dec 30, 2016 · 3 comments

Projects

None yet

1 participant

@mojavelinux
Member

Since line numbering is a switch, to be consistent with the AsciiDoc syntax, it should be enabled via an option (linenums) instead of a positional attribute. We can continue to support the positional attribute for backwards compatibility, but the docs should be updated to use the option.

[source%linenums,java]
----
public @WebServlet("/ping") class PingServlet extends HttpServlet {
    @Override protected void doGet(HttpServletRequest req, HttpServletResponse res)
            throws ServletException, IOException {
        res.setStatus(200);
        res.setContentType("text/plain");
        res.setCharacterEncoding("UTF-8");
        res.getWriter().write("here");
    }
}
----

Alternately written as:

[source,java,opts=linenums]
@mojavelinux mojavelinux added this to the v1.5.6 milestone Dec 30, 2016
@mojavelinux mojavelinux self-assigned this Dec 30, 2016
@mojavelinux mojavelinux changed the title from Line numbering on a source block should be enabled via linenums options to Line numbering on a source block should be enabled via linenums option Dec 30, 2016
@mojavelinux mojavelinux added the next label Dec 30, 2016
@mojavelinux mojavelinux added a commit to mojavelinux/asciidoctor that referenced this issue Jan 1, 2017
@mojavelinux mojavelinux resolves #1981 allow use of option to enable line numbers on source b…
…lock
2887c56
@mojavelinux
Member

I'm not sure what name to use for the option. Here are possible candidates:

  • number
  • numbered
  • numbers
  • linenums
  • linenos

I'd like to narrow it down to 1 choice.

If we follow the pattern from videos, where options include "autoplay", "loop", or the existing options on verbatim blocks, "prewrap", then I think the option "number" makes the most sense.

[source%number,ruby]
----
puts "Hello, World!"
----

(We make the assumption that "number" refers to line numbers).

@mojavelinux
Member

Actually, I think I can define the rule. If the option is describing the semantics of the content, such as "reversed" for a list, then we want to use the adjective (past tense verb). The list is by its nature, reversed. If we are asking the processor to do something for us, such as "to number", then we should use the action (present tense verb).

In this case, the source listing is not already numbered. We are asking the processor to number it. Thus, the option should be "number" (or even number_lines, but that would be too much to type).

@mojavelinux mojavelinux added a commit to mojavelinux/asciidoctor that referenced this issue Jan 1, 2017
@mojavelinux mojavelinux resolves #1981 allow use of option to enable line numbers on source b…
…lock
a3e652a
@mojavelinux
Member

An open question is whether we should reify the line numbering option on the block when it is parsed. Currently, the global setting is being checked during conversion. This makes it so line numbering can't be turned off for specific blocks.

@mojavelinux mojavelinux added a commit to mojavelinux/asciidoctor that referenced this issue Jan 2, 2017
@mojavelinux mojavelinux resolves #1981 pass cloaked context to block extension
- pass cloaked context as cloaked-context attribute to process method of custom block extension
423f08c
@mojavelinux mojavelinux added a commit to mojavelinux/asciidoctor that referenced this issue Jan 2, 2017
@mojavelinux mojavelinux resolves #1981 pass cloaked context to block extension
- pass cloaked context as cloaked-context attribute to process method of custom block extension
0079f13
@mojavelinux mojavelinux added a commit to mojavelinux/asciidoctor that referenced this issue Jan 2, 2017
@mojavelinux mojavelinux resolves #1981 allow use of option to enable line numbers on source b…
…lock
6fc2a81
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment