Date
1 - 11 of 11
Chapter and section numbering with Oxygen XML - DITA Map PDF based on HTML5 & CSS #CSS #PDF #Oxygen
|
Matt Lorenzi <mjlorenzi@...>
Hello, 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 <mjlorenzi@...>
Hi Eliot,
|
|
|
|
Matt Lorenzi <mjlorenzi@...>
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?
|
|
|
|
Hey, Eliot and Matt.
toggle quoted messageShow quoted text
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@contrext.com 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).
|
|
|
|
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
On 2020-01-09 12:37, Kristen James Eberlein wrote:
|
|
|
|
ekimber@contrext.com
The term "section" is almost as overloaded "document" and it causes no end of confusion.
toggle quoted messageShow quoted text
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@magliery.com> 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@contrext.com 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.
|
|
|
|
Matt Lorenzi <mjlorenzi@...>
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.
|
|
|
|
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 Deepbut 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:
|
|
|
|
Matt Lorenzi <mjlorenzi@...>
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!
|
|
|