Topics

Chapter and section numbering with Oxygen XML - DITA Map PDF based on HTML5 & CSS #CSS #PDF #Oxygen

Matt Lorenzi
 

Hello,

Testing out publishing a DITA map and content that was originally created in Adobe FrameMaker.

I am looking to publish to PDF with numbering on my headings and sections. The map is created as a bookmap and contains chapter headings, concept topics, and task topics. Within some of the concept topics I use the <section> element to chuck content. Each section within the concept has its own <title>

Previously in FrameMaker the numbering would apply to all chapter headings right down to my section titles. In Oxygen I have set the args.css.param.numbering parameter to "deep", which should number all chapters and sections.

The problem is, none of my sections are getting numbered. All individual topics are getting numbered, right down to three levels of nesting, but any topic that has a section(s) in it does not see the numbeting applied.

Any suggestions?

ekimber@contrext.com
 

DITA sections, by definition, do not contribute to the navigation hierarchy of a publication and therefore would normally not be numbered. Certainly the default behavior of any Open Toolkit process should be to not number sections or reflect them in navigation structures (tables of contents).

In contexts like standards or milspec docs where you number down to the paragraph level then that's different (because a different editorial practice is in place) but for that you'd need custom code to implement the numbering you want.

Usually in a case like this the sections should really be subtopics--you'll have to determine that for your content but in my experience that's almost always the case.

The <section> element is intended primarily for use in things like reference topics where you have a repeating and invariant set of titles within the topics where you would not want the titles reflected in tables of contents. The use of sections with arbitrary titles within non-reference topics is much harder to justify--in that context they function much more like DocBook "bridge titles".

Cheers,

E.
--
Eliot Kimber
http://contrext.com


On 1/9/20, 11:13 AM, "Matt Lorenzi via Groups.Io" <dita-users@groups.io on behalf of mjlorenzi=yahoo.com@groups.io> wrote:

Hello,

Testing out publishing a DITA map and content that was originally created in Adobe FrameMaker.

I am looking to publish to PDF with numbering on my headings and sections. The map is created as a bookmap and contains chapter headings, concept topics, and task topics. Within some of the concept topics I use the <section> element to chuck content. Each section within the concept has its own <title>.

Previously in FrameMaker the numbering would apply to all chapter headings right down to my section titles. In Oxygen I have set the args.css.param.numbering parameter to "deep", which should number all chapters and sections.
The problem is, none of my sections are getting numbered. All individual topics are getting numbered, right down to three levels of nesting, but any topic that has a section(s) in it does not see the numbeting applied.
Any suggestions?

Matt Lorenzi
 

Hi Eliot,


Thanks for this. I'm not suggesting what I have here is propper DITA. Some (most) of this is legacy content. I can see how you would use a <section> title for something a little more generic and repeating, and hence not want it reflected in a TOC.

So looks like I might go with the two options - live with it and not have the <section> titles be numbered, or, break out these sections into subtopics.
I'm less interested in a custom code solution. I would rather have it done correctly.

It still doesn't answer my question as to why Oxygen is not applying the numbering with the parameter set to "deep", but will take that up with the support at Oxygen.

Matt Lorenzi
 

I think I may have answered my own question here and it may be a matter of semantics.

When Oxygen refers to a section, perhaps they mean a section (topic) as a child of a chapter? What I was referring to was a <section> element within a topic. Perhaps similar but not the same? 

Kristen James Eberlein
 

Hey, Eliot and Matt.

Eliot, I also started to reply to Matt, saying that the topic is the atomic level of use in DITA, and thus the DITA-OT and oXygen CSS-based transformation do not number sections.

But then I thought that I should look at the oXygen documentation at https://www.oxygenxml.com/doc/versions/21.1/ug-editor/topics/dcpp_numbering_types.html

The content at that page is unclear to me. When it talked about numbering sections, does it mean topics? Or actual <section> elements?

Matt, you might want to cross-post on the oxygen-users list.

Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)

On 1/9/2020 1:38 PM, ekimber@... wrote:
DITA sections, by definition, do not contribute to the navigation hierarchy of a publication and therefore would normally not be numbered. Certainly the default behavior of any Open Toolkit process should be to not number sections or reflect them in navigation structures (tables of contents).

In contexts like standards or milspec docs where you number down to the paragraph level then that's different (because a different editorial practice is in place) but for that you'd need custom code to implement the numbering you want.

Usually in a case like this the sections should really be subtopics--you'll have to determine that for your content but in my experience that's almost always the case.

The <section> element is intended primarily for use in things like reference topics where you have a repeating and invariant set of titles within the topics where you would not want the titles reflected in tables of contents. The use of sections with arbitrary titles within non-reference topics is much harder to justify--in that context they function much more like DocBook "bridge titles".

Cheers,

E.
--
Eliot Kimber
http://contrext.com

On 1/9/20, 11:13 AM, "Matt Lorenzi via Groups.Io" <dita-users@groups.io on behalf of mjlorenzi=yahoo.com@groups.io> wrote:

Hello,

Testing out publishing a DITA map and content that was originally created in Adobe FrameMaker.

I am looking to publish to PDF with numbering on my headings and sections. The map is created as a bookmap and contains chapter headings, concept topics, and task topics. Within some of the concept topics I use the <section> element to chuck content. Each section within the concept has its own <title>.

Previously in FrameMaker the numbering would apply to all chapter headings right down to my section titles. In Oxygen I have set the args.css.param.numbering parameter to "deep", which should number all chapters and sections.
The problem is, none of my sections are getting numbered. All individual topics are getting numbered, right down to three levels of nesting, but any topic that has a section(s) in it does not see the numbeting applied.
Any suggestions?







Tom Magliery
 

A challenge we all face as producers of documentation about documentation is the overloading of some of the terminology in our industry. I think we all get complacent and become guilty of carelessness at times.

mag
-- 
Tom Magliery, mostly lurking nowadays


On 2020-01-09 12:37, Kristen James Eberlein wrote:

Hey, Eliot and Matt.

Eliot, I also started to reply to Matt, saying that the topic is the atomic level of use in DITA, and thus the DITA-OT and oXygen CSS-based transformation do not number sections.

But then I thought that I should look at the oXygen documentation at https://www.oxygenxml.com/doc/versions/21.1/ug-editor/topics/dcpp_numbering_types.html

The content at that page is unclear to me. When it talked about numbering sections, does it mean topics? Or actual <section> elements?

Matt, you might want to cross-post on the oxygen-users list.

Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)

On 1/9/2020 1:38 PM, ekimber@... wrote:
DITA sections, by definition, do not contribute to the navigation hierarchy of a publication and therefore would normally not be numbered. Certainly the default behavior of any Open Toolkit process should be to not number sections or reflect them in navigation structures (tables of contents).

In contexts like standards or milspec docs where you number down to the paragraph level then that's different (because a different editorial practice is in place) but for that you'd need custom code to implement the numbering you want.

Usually in a case like this the sections should really be subtopics--you'll have to determine that for your content but in my experience that's almost always the case.

The <section> element is intended primarily for use in things like reference topics where you have a repeating and invariant set of titles within the topics where you would not want the titles reflected in tables of contents. The use of sections with arbitrary titles within non-reference topics is much harder to justify--in that context they function much more like DocBook "bridge titles".

Cheers,

E.
--
Eliot Kimber
http://contrext.com
  On 1/9/20, 11:13 AM, "Matt Lorenzi via Groups.Io" <dita-users@groups.io on behalf of mjlorenzi@...> wrote:

     Hello,

     Testing out publishing a DITA map and content that was originally created in Adobe FrameMaker.

     I am looking to publish to PDF with numbering on my headings and sections. The map is created as a bookmap and contains chapter headings, concept topics, and task topics. Within some of the concept topics I use the <section> element to chuck content. Each section within the concept has its own <title>.

     Previously in FrameMaker the numbering would apply to all chapter headings right down to my section titles. In Oxygen I have set the args.css.param.numbering parameter to "deep", which should number all chapters and sections.
     The problem is, none of my sections are getting numbered. All individual topics are getting numbered, right down to three levels of nesting, but any topic that has a section(s) in it does not see the numbeting applied.
     Any suggestions?













ekimber@contrext.com
 

The term "section" is almost as overloaded "document" and it causes no end of confusion.

In my work at the GAO we refer to our top-level topics as "master sections" and then have "subsections", which are generic (unspecialized) topics descending from "master sections". We do not use DITA <section> elements at all. And then there's the work I've done with codified municipal code, where a "section" is a specific kind of titled division that means different things in different legal contexts (one city's section is another city's article (or division or chapter or ...).

"Which section of the Section did you find the <section>?"

Hmph.

Cheers,

E.

--
Eliot Kimber
http://contrext.com


On 1/9/20, 3:17 PM, "Tom Magliery" <dita-users@groups.io on behalf of yahoo@...> wrote:

A challenge we all face as producers of documentation about documentation is the overloading of some of the terminology in our industry. I think we all get complacent and become guilty of carelessness at times.
mag
--
Tom Magliery, mostly lurking nowadays

On 2020-01-09 12:37, Kristen James Eberlein wrote:

Hey, Eliot and Matt.

Eliot, I also started to reply to Matt, saying that the topic is the atomic level of use in DITA, and thus the DITA-OT and oXygen CSS-based transformation do not number sections.

But then I thought that I should look at the oXygen documentation at https://www.oxygenxml.com/doc/versions/21.1/ug-editor/topics/dcpp_numbering_types.html

The content at that page is unclear to me. When it talked about numbering sections, does it mean topics? Or actual <section> elements?

Matt, you might want to cross-post on the oxygen-users list.

Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com <http://www.eberleinconsulting.com>
+1 919 622-1501; kriseberlein (skype)

On 1/9/2020 1:38 PM, ekimber@... wrote:
DITA sections, by definition, do not contribute to the navigation hierarchy of a publication and therefore would normally not be numbered. Certainly the default behavior of any Open Toolkit process should be to not number sections or reflect them in navigation structures (tables of contents).

In contexts like standards or milspec docs where you number down to the paragraph level then that's different (because a different editorial practice is in place) but for that you'd need custom code to implement the numbering you want.

Usually in a case like this the sections should really be subtopics--you'll have to determine that for your content but in my experience that's almost always the case.

The <section> element is intended primarily for use in things like reference topics where you have a repeating and invariant set of titles within the topics where you would not want the titles reflected in tables of contents. The use of sections with arbitrary titles within non-reference topics is much harder to justify--in that context they function much more like DocBook "bridge titles".

Cheers,

E.
--
Eliot Kimber
http://contrext.com
On 1/9/20, 11:13 AM, "Matt Lorenzi via Groups.Io" <dita-users@groups.io on behalf of mjlorenzi=yahoo.com@groups.io> wrote:

Hello,

Testing out publishing a DITA map and content that was originally created in Adobe FrameMaker.

I am looking to publish to PDF with numbering on my headings and sections. The map is created as a bookmap and contains chapter headings, concept topics, and task topics. Within some of the concept topics I use the <section> element to chuck content. Each section within the concept has its own <title>.

Previously in FrameMaker the numbering would apply to all chapter headings right down to my section titles. In Oxygen I have set the args.css.param.numbering parameter to "deep", which should number all chapters and sections.
The problem is, none of my sections are getting numbered. All individual topics are getting numbered, right down to three levels of nesting, but any topic that has a section(s) in it does not see the numbeting applied.
Any suggestions?

Lief Erickson
 

As I wrote elsewhere, I think it's possible that  there's a conflation between the HTML <section> element and its matching CSS selector in oXygen and the DITA <section> element. To Tom's point, overloaded terminology. I suspect oXygen numbers HTML sections, which are based on topicrefs, not DITA sections. The oXygen support team should be able to clear up that question pretty easily.

-Lief

On Thu, Jan 9, 2020 at 2:37 PM Kristen James Eberlein <kris@...> wrote:
Hey, Eliot and Matt.

Eliot, I also started to reply to Matt, saying that the topic is the
atomic level of use in DITA, and thus the DITA-OT and oXygen CSS-based
transformation do not number sections.

But then I thought that I should look at the oXygen documentation at
https://www.oxygenxml.com/doc/versions/21.1/ug-editor/topics/dcpp_numbering_types.html

The content at that page is unclear to me. When it talked about
numbering sections, does it mean topics? Or actual <section> elements?

Matt, you might want to cross-post on the oxygen-users list.

Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)

On 1/9/2020 1:38 PM, ekimber@... wrote:
> DITA sections, by definition, do not contribute to the navigation hierarchy of a publication and therefore would normally not be numbered. Certainly the default behavior of any Open Toolkit process should be to not number sections or reflect them in navigation structures (tables of contents).
>
> In contexts like standards or milspec docs where you number down to the paragraph level then that's different (because a different editorial practice is in place) but for that you'd need custom code to implement the numbering you want.
>
> Usually in a case like this the sections should really be subtopics--you'll have to determine that for your content but in my experience that's almost always the case.
>
> The <section> element is intended primarily for use in things like reference topics where you have a repeating and invariant set of titles within the topics where you would not want the titles reflected in tables of contents. The use of sections with arbitrary titles within non-reference topics is much harder to justify--in that context they function much more like DocBook "bridge titles".
>
> Cheers,
>
> E.
> --
> Eliot Kimber
> http://contrext.com
>   
>
> On 1/9/20, 11:13 AM, "Matt Lorenzi via Groups.Io" <dita-users@groups.io on behalf of mjlorenzi=yahoo.com@groups.io> wrote:
>
>      Hello,
>
>      Testing out publishing a DITA map and content that was originally created in Adobe FrameMaker.
>
>      I am looking to publish to PDF with numbering on my headings and sections. The map is created as a bookmap and contains chapter headings, concept topics, and task topics. Within some of the concept topics I use the <section> element to chuck content. Each section within the concept has its own <title>.
>
>      Previously in FrameMaker the numbering would apply to all chapter headings right down to my section titles. In Oxygen I have set the args.css.param.numbering parameter to "deep", which should number all chapters and sections.
>      The problem is, none of my sections are getting numbered. All individual topics are getting numbered, right down to three levels of nesting, but any topic that has a section(s) in it does not see the numbeting applied.
>      Any suggestions?
>
>
>
>
>
>
>
>
>



Matt Lorenzi
 

I hope someone at Oxygen stumbles on this thread - regardless I think the definition for <section> from the Oasis website clears things up and affirms we may have been using it wrong:
3.1.1.2.31 section

The <section> element represents an organizational division in a topic. Sections are used to organize subsets of information that are directly related to the topic. For example, the titles Reference SyntaxExample and Properties might represent section-level discourse within a topic about a command-line process—the content in each section relates uniquely to the subject of that topic. Multiple sections within a single topic do not represent a hierarchy, but rather peer divisions of that topic. Sections cannot be nested. A section may have an optional title.

The "multiple sections within a single topic do not represent a hierarchy" bit definitely negates the need for numbering. 

Radu Coravu
 

Hi Matt,

I stumbled on this thread, as the thread is long it was an easy stumble :)

So our DITA to PDF using CSS documentation mentions:

https://www.oxygenxml.com/doc/versions/21.1/ug-editor/topics/dcpp_numbering_types.html
Deep
Each chapter and section is numbered (sections are prefixed with the chapter number). Figures, tables, and pages are numbered sequentially from the start of the publication and they do not reset.
but I think the "section" wording there was originally indented to mean "topic" located on any level and not DITA <section>. I will add an internal issue to clarify this in our documentation.

Indeed one possibility to move forward is to convert the sections in your topic to inner topics, we have an "Convert Nested Topics to New Topics" action available in the Oxygen DITA Maps Manager view.

https://www.oxygenxml.com/doc/versions/21.1/ug-editor/topics/dita-maps-manager.html

Do you want as an outcome the numbered sections to just appear numbered in the PDF content or also to appear in the table of contents and the bookmarks area?
Because if you do not want the sections to appear also in the TOC and the bookmarks area I think this numbering could be achieved using CSS.

I see you also started a thread on the Oxygen XML Forum, I will probably reply also on that one:

https://www.oxygenxml.com/forum/viewtopic.php?p=56674#p56615

Regards,
Radu

Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com

On 1/10/2020 12:21 AM, Matt Lorenzi via Groups.Io wrote:
I hope someone at Oxygen stumbles on this thread - regardless I think the definition for *<section>* from the Oasis website clears things up and affirms we may have been using it wrong:
3.1.1.2.31 section
The <section> element represents an organizational division in a topic. Sections are used to organize subsets of information that are directly related to the topic. For example, the titles Reference Syntax, Example and Properties might represent section-level discourse within a topic about a command-line process—the content in each section relates uniquely to the subject of that topic. Multiple sections within a single topic do not represent a hierarchy, but rather peer divisions of that topic. Sections cannot be nested. A section may have an optional title.
The "multiple sections within a single topic do not represent a hierarchy" bit definitely negates the need for numbering.

Matt Lorenzi
 

Hi Radu,
So originally my intent was to mirror the numbering outcome we achieved using FrameMaker. There we achieved numbering for all topics as well as the DITA <section>, so a topic might show like this:

3.0 Safety
3.1 Safety Wording/Symbols (DITA <section>)
3.2 General Warning and Cautions (DITA <section>)
3.3 Electrical Safety (DITA <section>)


So in the example above this is all in one topic, yet I achieve this numbering (both in the body and the TOC). I am curious how we achieved this numbering out of FrameMaker since this is not standard DITA-OT behaviour. Perhaps we had some custom scripting done at the time.

I guess to preserve this hierarchy in my document I will need to break out these <sections> into DITA topics. And if I just want to have non-hierarchical headings within a topic, I can continue to use <section><title></title></section>.

Thanks again!