numbered toc and sections without dot after the last digit

[p627]

Hi, I wonder if there is an opportunity to delete the dot in the numbering after the last digit? I think this is the common convention.

I have:

I search for something like this:

Thank you in advance.

[janosvitok]

I use this snippet to remove the trailing dot (save to a file, and call asciidoctor-pdf -r filename.rb):

require 'asciidoctor-pdf' unless defined? ::Asciidoctor::Pdf

module AsciidoctorPdfSectionExtensions
  def numbered_title opts = {}
    unless (@cached_numbered_title ||= nil)
      if (slevel = (@level == 0 && @special ? 1 : @level)) == 0
        @is_numbered = false
        @cached_numbered_title = @cached_formal_numbered_title = title
      elsif @numbered && !@caption && slevel <= (@document.attr 'sectnumlevels', 3).to_i
        @is_numbered = true
        @cached_numbered_title = %(#{sectnum('.', false)} #{title}) # <----- HERE
        @cached_formal_numbered_title = if slevel == 1 && @document.doctype == 'book'
          %(#{@document.attr 'chapter-label', 'Chapter'} #{@cached_numbered_title}).lstrip
        else
          @cached_numbered_title
        end
      else
        @is_numbered = false
        @cached_numbered_title = @cached_formal_numbered_title = captioned_title
      end
    end
    opts[:formal] ? @cached_formal_numbered_title : @cached_numbered_title
  end
end

Asciidoctor::Section.prepend AsciidoctorPdfSectionExtensions

The actual change from lib/asciidoctor-pdf/asciidoctor_ext/section.rb is

-        @cached_numbered_title = %(#{sectnum} #{title})
+        @cached_numbered_title = %(#{sectnum('.', false)} #{title})

[lisa-rosenberg]

I have the same problem.

janosvitok, can you tell me how to use your snippet, please? The command you have given is leading me to this output:

rosenbeli@N0601:/mnt/d/Documents$ asciidoctor-pdf -r remove-section-trailing-dot.rb
Usage: asciidoctor [OPTION]... FILE...
Translate the AsciiDoc source FILE or FILE(s) into the backend output format (e.g., HTML 5, DocBook 4.5, etc.)
By default, the output is written to a file with the basename of the source file and the appropriate extension.
Example: asciidoctor -b html5 source.asciidoc

    -b, --backend BACKEND            set output format backend: [html5, xhtml5, docbook5, docbook45, manpage] (default: html5)
                                     additional backends are supported via extensions (e.g., pdf, latex)
    -d, --doctype DOCTYPE            document type to use when converting document: [article, book, manpage, inline] (default: article)

[...]

Am I missing something? I am in the working directory where the .adoc file and the .rb file are stored.

I have to admit that I'm new to bash, asciidoctor and ruby. Maybe that's the problem :)

[janosvitok]

Lisa: Did you specify all your usual parameters in addition to the -r ? E.g. your document?
What I actually meant was that you have to add -r remove-section-trailing-dot.rb to your current asciidoctor parameters.

[lisa-rosenberg]

Hi janosvitok,

I couldn't get it to work until now, but I will look further into this, thank you :)

I am testing it with a very basic document:

= This is a Test

:numbered:
== With a section
=== A subsection
And some text.

After:
asciidoctor-pdf -r remove-section-trailing-dot.rb -d book test.adoc --trace

I'm getting this:

/usr/lib/ruby/2.3.0/rubygems/core_ext/kernel_require.rb:55:in `require': cannot load such file -- remove-section-trailing-dot.rb (LoadError)
        from /usr/lib/ruby/2.3.0/rubygems/core_ext/kernel_require.rb:55:in `require'
        from /usr/lib/ruby/vendor_ruby/polyglot.rb:63:in `require'
        from /var/lib/gems/2.3.0/gems/asciidoctor-1.5.6.1/lib/asciidoctor/cli/options.rb:230:in `block in parse!'
        from /var/lib/gems/2.3.0/gems/asciidoctor-1.5.6.1/lib/asciidoctor/cli/options.rb:228:in `each'
        from /var/lib/gems/2.3.0/gems/asciidoctor-1.5.6.1/lib/asciidoctor/cli/options.rb:228:in `parse!'
        from /var/lib/gems/2.3.0/gems/asciidoctor-pdf-1.5.0.alpha.16/bin/asciidoctor-pdf:25:in `<top (required)>'
        from /usr/local/bin/asciidoctor-pdf:22:in `load'
        from /usr/local/bin/asciidoctor-pdf:22:in `<main>'

Packages should be up to date:

ruby -v
ruby 2.3.5p376 (2017-09-14 revision 59905) [x86_64-linux-gnu]

asciidoctor -v
Asciidoctor 1.5.6.1 [http://asciidoctor.org]
Runtime Environment (ruby 2.3.5p376 (2017-09-14 revision 59905) [x86_64-linux-gnu]) (lc:UTF-8 fs:UTF-8 in:- ex:UTF-8)

asciidoctor-pdf -v
Asciidoctor PDF 1.5.0.alpha.16 using Asciidoctor 1.5.6.1 [http://asciidoctor.org]
Runtime Environment (ruby 2.3.5p376 (2017-09-14 revision 59905) [x86_64-linux-gnu]) (lc:UTF-8 fs:UTF-8 in:- ex:UTF-8)

[janosvitok]

@lisa-rosenberg
https://stackoverflow.com/questions/9750610/ruby-require-error-cannot-load-such-file
http://asciidoctor.org/docs/user-manual/#cli-options

TL;DR: either provide path to remove-section-trailing-dot.rb (e.g. -r ./remove-section-trailing-dot.rb or -r /home/asdf/remove-section-trailing-dot.rb) or add -I path (e.g. -I . or -I /home/asdf)

[michael-o]

I'd be interested too. There is no trailing dot in numbering. This is against common convention.

[mojavelinux]

To move forward, we need a way to express this configuration. It probably belongs in the theme. We need to agree on a key and value. Implementation is then rather trivial I would suspect.

[mojavelinux]

(it could also be done with a document attribute so it also applies to other converters).

[mojavelinux]

I'm looking for the name of an option that may exist in other systems, so we can build on established conventions. If we can't find one, we'll have to invent one.

[j-dimension]

I'd be interested too.

[dalemartin]

@mojavelinux what ever became of this? I would like to use the feature if it's been implemented.

[mojavelinux]

We're waiting on architecture. That hasn't been solved, so no code can be written yet. Feel free to propose solutions.

[michael-o]

I'd like to see this removed by default. Haven't found this in any book type setting nor in LaTeX.

[mojavelinux]

We can't simply change behavior on all users. There has to be a setting. Some way to describe that you want different output than what is typical (for Asciidoctor).

[mojavelinux]

O'Reilly always includes the trailing dot in their books. Other publishers do not.

[dalemartin]

We're waiting on architecture.

Not sure what this means? But either way, not a huge deal to me, just nice to have at this point.

[mojavelinux]

In order to code it, I need to know what to code. Since there are arguments both for and against it, I've made the decision that it must be controlled through configuration (with the current behavior being the default). And that brings us to this comment:

To move forward, we need a way to express this configuration.

Until we decide on what that configuration is, the specifications, nothing is going to happen. Feel free to submit proposals.

[janosvitok]

I'd say that add two doc attributes:

• :sectnumseparator:, by default '.'
• :sectnumappendseparator:, by default yes
  and both asciidoctor and asciidoctor-pdf should be changed (and maybe more)

[mojavelinux]

Interesting proposal. How strongly do you feel about the fact that this should be controlled from the document? It seems to me something that is presentation only, and thus should be configured in the theme. (On the other hand, the HTML converter doesn't really have a theme, so we lose the opportunity to configure it there).

If we use the attributes, I would make it sectnumseparator and sectnumtrailingseparator (which defaults to sectnumseparator). That way, we could achieve 1-1. or 1-1 or 1.1. or 1.1.

[janosvitok]

I don't have any strong feelings. In fact, I was thinking about something similar, but I've forgotten it when I wrote the proposal.

I've proposed attributes for the simple reason that HTML does not have templates, and HTML and PDF numbering should be the same.

[lotaris-xx]

This seems like a great idea. The trailing dots do bother me atm. I think the pair of attributes to specify the interior and trailing delimiter would be ideal.

[mojavelinux]

The more I think about this, the more I'm convinced it should be done via attributes because multiple converters will need to use it.

This change will need to be applied to core, but since Asciidoctor PDF is already overriding the method, we can change it here first, then follow-up in core.

[mojavelinux]

sectnumappendseparator

I think this should be sectnumsuffix.

[mojavelinux]

I wonder if we should shorten sectnumseparator and sectnumsuffix to just numseparator and numsuffix. The reason is, numbers are also used for blocks like figures (e.g., Figure 1. Title). So you're going to get the trailing dot there too. Or perhaps we shouldn't couple these things and have a different set of attributes for the caption label. wdyt?

[mojavelinux]

@janosvitok Thanks for responding to my call to architecture, btw. Very helpful.

[habakuk007]

I'm strongly interested in this feature because of ISO 2145 and DIN 1421 (explained in Wikipedia article Gliederung - translation).

And I would prefer to have different suffixes for figures because I need them like here: Tabelle 1: Einstellungen der seriellen Schnittstelle.

[ullenboom]

Is there any update on this feature?
Also belongs to asciidoctor/asciidoctor#3702

[mojavelinux]

If there is an update, I can assure you I will post it here. If you want it sooner, you can help by answering the open questions I have floated. If we can't answer those questions, we can't implement a change.

[r0ckarong]

I'm looking at the hack that @janosvitok provided and that I'm using in my docs every day so I came back to this discussion.

I wonder if we should shorten sectnumseparator and sectnumsuffix to just numseparator and numsuffix. The reason is, numbers are also used for blocks like figures (e.g., Figure 1. Title). So you're going to get the trailing dot there too. Or perhaps we shouldn't couple these things and have a different set of attributes for the caption label. wdyt?

In my opinion there should be separate options for section chapter/part heading and caption numbering. The more options to configure this the better; since a lot of people will want this freedom or need to adhere to certain style guidelines as @habakuk007 also stated.

The signifiers are modified using attributes and so I think the rest of the parts that make up the final result should be attributes as well.

IMHO the PDF theme should provide "fields" that can be filled via attributes and not hardcode content. What should be configurable in the PDF theme is if the TOC will show the signifier and separator/suffix in the listed items. Right now the signifier is dropped but the suffix is added.

Therefore this would work like this:

pdf-theme.yml

toc:
  signifier:
    chapter:
      display: false
    part:
      display: false
    section:
       display: false
  separator:
    chapter:
      display: true
    part:
      display: true
    section:
      display: true
  suffix:
    chapter:
      display: true
    part:
      display: true
    section:
      display: true

Keys could be a bit simpler maybe but I didn't want to concatenate too much and lose information here.

And I would propose the following for the attributes that control this within the document itself:

Section
sectnumseparator (default '.') (dot)
sectnumsuffix (default '. ') (dot space)

e.g. 1.1. My first sub heading

Part numbering:
partnumseparator (default '.') (dot)
partnumsuffix (default ' - ') (space hyphen space)

e.g. Part 1.1 - This is the firsty first part

Chapter numbering:
chapternumseparator (default '.') (dot
chapternumsuffix (default ' - ') (space hyphen space)

e.g. Chapter 3 - The problem with formats

Captions:
captnumseparator (default '.') (dot)
captnumsuffix (default ': ') (colon space)

e.g. "Caption 1.1: My figure"

This way you can have full freedom of what separates the numbering and text (snake_case? no problem). If you wish to remove any of the trailing elements you simply fill it with a space or set it empty (depending what look you need).

Not set should be handled as default.
Explicit unset should be handled as default, not empty. This way you can suppress the custom behavior for parts of the doc and then just restart with your custom numbering further on.

[mojavelinux]

I appreciate the feedback and I'll give it some thought. My initial reaction is that this is introducing too much complexity into the theme. I don't think that more options to configure is better. More options means more things users have to learn and makes the converter feel too complicated/overwhelming for most. We've had tremendous success with keeping things as simple as possible and letting the converter do the work. It's better for advanced functionality like this to allow the converter to be extended (or Asciidoctor in general) in order to influence the behavior. That would mean extracting the logic that sets up the numbering into an overriddable method. But that can be easier said than done.

[r0ckarong]

More options means more things users have to learn and makes the converter feel too complicated/overwhelming for most.

I can only speak for myself but I see it from the other side of the coin. I don't really learn often about something I don't need to configure, it just doesn't come across my attention. If the defaults are sensible, then I most likely will never touch them. But when I have some extrinsic motivation (like requirements or a styleguide) to adhere to and find out there is just no simple way to do achieve it, it's demotivating to say the least. It's really very much easier to ignore something that you don't care about than to invent something that you desperately need; especially when you've got time constraints.

[mojavelinux]

I understand your perspective, but also understand that I support Asciidoctor close to 24/7, and I can tell you from experience that adding more options makes it harder to support. I have time constraints too, and the more complex the configuration is, the more pressure it puts on those constraints.

[bmj2023]

TEX has the contrib package secdot that turns on the trailing dot after the section number. For simplicity the attribute could be :secdot!: to turn off the trailing dot in Asciidoctor.
There are two other commands that allow for adding the trailing dot by level (sectiondot) and turning on the dot and modifying the format of the trailing dot (sectionpunct).
A more complicated attribute could be :secdot: level, string.

https://ctan.org/tex-archive/macros/latex/contrib/secdot