Appendix sectnums

Asciidoc 0.1.4 assigns nice captions to appendices, but these aren't reflected in the sectnums. If I enable numbering, I'm getting output that looks like this
1. Section 1
2. Appendix A
  2.1 Subsection 1

What I would prefer to see is
1. Section 1
Appendix A
  A.1 Subsection 1

I've monkey patched this in with the following bit of code, but it feels rather kludgy. The upside of patching sectnum is that this is automatically reflected everywhere throughout the document. Is there a better way to do this?

def sectnum(delimiter = '.', append = nil)
  append ||= (append == false ? '' : delimiter)

  if !@level.nil? && @level > 1 && @parent.is_a?(Section)
    if @parent.appendix_number
      "#{@parent.appendix_number}#{delimiter}#{@number}#{append}"
    else
      "#{@parent.sectnum(delimiter)}#{@number}#{append}"
    end
  else
    if appendix_number
      ""
    else
      "#{@number}#{append}"
    end

  end
end

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Appendix-sectnums-tp706.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

Pepijn,

The numbering scheme you're suggesting is a great idea. Right now, the monkeypatch you implemented appears to be the simplest solution. I don't think you should feel uneasy about doing it that way.

To explain the output you're getting, with the goal of making the appropriate design change...

In AsciiDoc Python, the responsibility falls on the writer to turn off numbering around special sections like appendices. For example:

```asciidoc

== Sample section

content

:numbered!:

[appendix]

== Sample appendix

content

```

If the numbering is left on, as you have observed, it looks rather strange :/

I'm planning to introduce a new attribute in Asciidoctor 1.5.0 that allows you to control whether special sections (like appendices) are numbered [1]. What I'm wondering with whether we can expand the scope of that change so that you not only control whether the special sections are numbered, but also how. Perhaps there are three states for this attribute:

* specialnumbered!

* specialnumbered

* specialnumbered: natural

The new value is the last one, "natural". It would number the special sections using a natural numbering approach, which would mean "A.1" for the first subsection of the first appendix.

Keep in mind the name of this attribute is only tentative. If someone suggests a better name, by all means, we'll change it.

Of course, that option I just presented is quite limited if you are looking for broad control over section numbering. Since we're proposing to make the section id generator an extension point [2], it makes sense for the section number generator to be extension point as well.

In summary, I think we should do it. I'd like to hear your thoughts about whether you think these proposals are reasonable, or if you have other ideas about how it should work. The only thing to keep in mind is that we still need to be able to emulate the AsciiDoc behavior through some means (such as an attribute) to maintain compatibility.

-Dan

[1] https://github.com/asciidoctor/asciidoctor/issues/661

[2] https://github.com/asciidoctor/asciidoctor/issues/576

On Fri, Oct 4, 2013 at 9:44 AM, pepijnve [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Asciidoc 0.1.4 assigns nice captions to appendices, but these aren't reflected in the sectnums. If I enable numbering, I'm getting output that looks like this
1. Section 1
2. Appendix A
  2.1 Subsection 1

What I would prefer to see is
1. Section 1
Appendix A
  A.1 Subsection 1

I've monkey patched this in with the following bit of code, but it feels rather kludgy. The upside of patching sectnum is that this is automatically reflected everywhere throughout the document. Is there a better way to do this?

def sectnum(delimiter = '.', append = nil)
  append ||= (append == false ? '' : delimiter)

  if !@level.nil? && @level > 1 && @parent.is_a?(Section)
    if @parent.appendix_number
      "#{@parent.appendix_number}#{delimiter}#{@number}#{append}"
    else
      "#{@parent.sectnum(delimiter)}#{@number}#{append}"
    end
  else
    if appendix_number
      ""
    else
      "#{@number}#{append}"
    end

  end
end

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Appendix-sectnums-tp706.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

--

Dan Allen | http://google.com/profiles/dan.j.allen

I was doing some more thinking on this issue, and I'm inclined to agree that the numbering of appendices is simply a bug. When a letter is assigned to a special section, of which appendix is the only example, the subsection numbering should use that letter in the first position. I'll file an issue.

One question. If there's a section after the appendix, should a gap remain in the numbers or should it continue with the next number in the sequence? For instance, is this correct?

1. Section One

  1.1. Subsection of Section One

Appendix A: Sample Appendix

  A.1 Subsection of Sample Appendix

2. Section Two

(I realize this ordering is highly unlikely, but just in case).

-Dan

On Tue, Oct 8, 2013 at 11:29 PM, Dan Allen <[hidden email]> wrote:

Pepijn,

The numbering scheme you're suggesting is a great idea. Right now, the monkeypatch you implemented appears to be the simplest solution. I don't think you should feel uneasy about doing it that way.

To explain the output you're getting, with the goal of making the appropriate design change...

In AsciiDoc Python, the responsibility falls on the writer to turn off numbering around special sections like appendices. For example:

```asciidoc

== Sample section

content

:numbered!:

[appendix]

== Sample appendix

content

```

If the numbering is left on, as you have observed, it looks rather strange :/

I'm planning to introduce a new attribute in Asciidoctor 1.5.0 that allows you to control whether special sections (like appendices) are numbered [1]. What I'm wondering with whether we can expand the scope of that change so that you not only control whether the special sections are numbered, but also how. Perhaps there are three states for this attribute:

* specialnumbered!

* specialnumbered

* specialnumbered: natural

The new value is the last one, "natural". It would number the special sections using a natural numbering approach, which would mean "A.1" for the first subsection of the first appendix.

Keep in mind the name of this attribute is only tentative. If someone suggests a better name, by all means, we'll change it.

Of course, that option I just presented is quite limited if you are looking for broad control over section numbering. Since we're proposing to make the section id generator an extension point [2], it makes sense for the section number generator to be extension point as well.

In summary, I think we should do it. I'd like to hear your thoughts about whether you think these proposals are reasonable, or if you have other ideas about how it should work. The only thing to keep in mind is that we still need to be able to emulate the AsciiDoc behavior through some means (such as an attribute) to maintain compatibility.

-Dan

[1] https://github.com/asciidoctor/asciidoctor/issues/661

[2] https://github.com/asciidoctor/asciidoctor/issues/576

On Fri, Oct 4, 2013 at 9:44 AM, pepijnve [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Asciidoc 0.1.4 assigns nice captions to appendices, but these aren't reflected in the sectnums. If I enable numbering, I'm getting output that looks like this
1. Section 1
2. Appendix A
  2.1 Subsection 1

What I would prefer to see is
1. Section 1
Appendix A
  A.1 Subsection 1

I've monkey patched this in with the following bit of code, but it feels rather kludgy. The upside of patching sectnum is that this is automatically reflected everywhere throughout the document. Is there a better way to do this?

def sectnum(delimiter = '.', append = nil)
  append ||= (append == false ? '' : delimiter)

  if !@level.nil? && @level > 1 && @parent.is_a?(Section)
    if @parent.appendix_number
      "#{@parent.appendix_number}#{delimiter}#{@number}#{append}"
    else
      "#{@parent.sectnum(delimiter)}#{@number}#{append}"
    end
  else
    if appendix_number
      ""
    else
      "#{@number}#{append}"
    end

  end
end

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Appendix-sectnums-tp706.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

--

Dan Allen | http://google.com/profiles/dan.j.allen

--

Dan Allen | http://google.com/profiles/dan.j.allen