Replace use of deprecated 'numbered' attribute by 'sectnums'

[abelsromero]

Thank you for opening a pull request and contributing to AsciidoctorJ!

Please take a bit of time giving some details about your pull request:

Kind of change

• Bug fix
• New non-breaking feature
• New breaking feature
• Documentation update
• Build improvement
• Other 👉 maintenance chore

Description

What is the goal of this pull request?

Replace use of deprecated attribute numbered by recommended value sectnums.

How does it achieve that?

• Replaces constant

  asciidoctorj/asciidoctorj-api/src/main/java/org/asciidoctor/Attributes.java

  Line 41 in 2a57067

  public static final String SECTION_NUMBERS = "numbered";

• Updates tests and JavaDocs when necessary
• No extra tests have been added. There are already valid ones present.

Are there any alternative ways to implement this?

No

Are there any implications of this pull request? Anything a user must know?

Only for users comparing the attibute with the internal value will notice. I personally don't consider that a breaking change since constants should be used to replace manually set values and the internal value should not be checked.

• Theres no impact for users using the constant or AttributesBuilder normally.
• Conversions setting "numbered" manually will still work since is still supported in the Ruby core.

Issue

If this PR fixes an open issue, please add a line of the form:

Fixes #1120

Release notes

Please add a corresponding entry to the file CHANGELOG.adoc

[robertpanzer]

Thank you!

I wasn't aware that the numbered attribute is deprecated, I found the corresponding comment here:
https://docs.asciidoctor.org/asciidoctor/latest/migrate/asciidoc-py/#updated-and-deprecated-asciidoc-syntax

Since we're changing the value of a constant users should be aware though that they need to recompile their code to use the new value of the constant. In my experience constants that are public static final are usually copied into the class of the referencing site.

[abelsromero]

Since we're changing the value of a constant users should be aware though that they need to recompile their code to use the new value of the constant. In my experience constants that are public static final are usually copied into the class of the referencing site.

I have no issue if this needs to go into a major release. To me it's not technically a breaking change, but it's true the compiler embeds the values and that can bring suprises, making it "breaking" in effect. 😞

[robertpanzer]

I checked that even when setting the attribute numbered a converter or extension would see the attribute sectnums.
I guess it's indeed safe then to consider it as a minor change and pull it into the v2.5.x branch.
I'll take care of that.