Loading ...
Sorry, an error occurred while loading the content.
 

Re: I Want to Nest Sections!!!

Expand Messages
  • despopoulos_chriss
    Well, I thought one conceptual rule for a topic is that it must stand on its own. In that case, these things I m worried about fail. If that s a guideline
    Message 1 of 13 , Oct 1, 2012
      Well, I thought one conceptual rule for a topic is that it must stand on its own. In that case, these things I'm worried about fail. If that's a guideline and not a religious issue, then I guess I can live with them being topics. Then if I save them out as separate files, I use conref to wrap them in their respective parent "Topics-that-I-really-want-to-be-topics" topics. Is that right? And then for the TOC I can set up rules to get what I want.

      Or can I even keep them all as separate topics and separate files, and use a map to build the full document I want... Then when rendering as HTML (for example) I use rules to wrap things within a "true-topic" parent file, and let the TOC take care of the rest?

      Finally, if I want to render pages on the fly (as query response), I just need rules that say any response must:
      * Include the found topic plus all children
      * Be wrapped in a topic that shows in the TOC

      I can see this working... Is it legal and (perhaps more importantly) not controversial?

      Thanks... cud


      --- In dita-users@yahoogroups.com, Eliot Kimber <ekimber@...> wrote:
      >
      > You can't say "they're not topics" without saying why they're not topics.
      >
      > In particular, not being in the ToC of a particular rendering is not, by
      > itself, sufficient to indicate something is not a topic. You may have topics
      > that are referenced from the map but are not included in a particular toc,
      > either because the ToC generation rules limit the ToC depth or because
      > you've specified toc="no" on the topicref.
      >
      > If a thing has a title is is a candidate to be a topic.
      >
      > If it has a title and it has titled things under it that are not figures or
      > tables or sections, it *must* be a topic (because only topics can nest).
      >
      > If it has a title and it has titled things under that are only ever figures
      > or tables, then it *may* be a section, but it might still be a topic.
      >
      > In general, if it has a title and isn't a figure or table, your default
      > response should be to make it a topic.
      >
      > It can be a section if and only if:
      >
      > 1. It doesn't *ever* contribute to any navigation hierarchy (that is, it
      > doesn't normally show in ToCs and the presentation of the title is not
      > normally conditioned in the hierarchical position of the containing topic.
      >
      > 2. It would never have titled things within it that are not figures or
      > tables.
      >
      > In the specific case of reference-type content, sections are the usual way
      > to represent consistent and repeating titles for the subcomponents of a
      > reference topic. That is the primary use case for sections.
      >
      > You have to be careful not to conflate the Tech Doc notion of topic as a
      > unit of information and the DITA markup notion of topic, which is "a thing
      > with a title that can contain other things with titles".
      >
      > Cheers,
      >
      > E.
      >
      > On 9/28/12 1:46 PM, "despopoulos_chriss" <despopoulos_chriss@...>
      > wrote:
      >
      > > Well, the fact is, they're not topics. But, they include hierarchies of their
      > > own, which means headings. Hence the subject line... I want to nest
      > > sections. But I can't. I agree with you, I can't call them topics. So what
      > > *do* I do? What (asking as a green newbie here) do I use to have a
      > > sub-something within a topic, that can include sub-sub-somethings, and maybe
      > > even sub-sub-sub-somethings?
      > >
      > > As for the limit at H3 for topics, I'm only referring to a particular legacy
      > > document. The organization of it had anything below H3 excluded from the
      > > TOC... Hence not a topic.
      > >
      > > In fact, it sometimes excludes H2s from the TOC, as well as some H3s. You can
      > > say this is bad writing practice, but there it is. Rewriting to satisfy a
      > > standard would require more ROI investigation. It could well be that a
      > > non-standard XML (that allows the legacy structure) would win that argument.
      > > The most important output process is going to be in-house engineered anyway...
      > > Giving up the open toolkit may cost less than rewriting.
      > >
      > > Cheers cud
      > >
      > > --- In dita-users@yahoogroups.com <mailto:dita-users%40yahoogroups.com> ,
      > > Eliot Kimber <ekimber@> wrote:
      > >>
      > >> Either the things you want to nest are part of the navigation hierarchy or
      > >> they're not.
      > >>
      > >> If they are, they must be topics. If they're not, they can't be topics. They
      > >> may be sections, they may be something else.
      > >>
      > >> If you are sure that the 4th level can't be a topic then you need to figure
      > >> out what it really is and what the things under really are.
      > >>
      > >> Why do you say "Level 3 is about the limit for turning a heading to a
      > >> topic"?
      > >>
      > >> Cheers,
      > >>
      > >> E.
      > >>
      > >> On 9/27/12 5:40 PM, "despopoulos_chriss" <despopoulos_chriss@>
      > >> wrote:
      > >>
      > >>> Subject says it all. But of course, that's not done. So what IS done? I'm
      > >>> converting an existing doc to DITA, and it has 5 levels of headings. Level
      > >>> 3
      > >>> is about the limit for turning a heading into a topic. So that leaves level
      > >>> 4
      > >>> as a section, and then what do I do with level 5? I need the titles...
      > >>>
      > >>> Apologies if this has been covered before -- brief search turned up nothing.
      > >>> And yes, I'm pretty new with actually *using* DITA.
      > >>>
      > >>> Thanks in advance...
      > >>>
      > >>>
      > >>>
      > >>>
      > >>>
      > >>>
      > >>
      > >> --
      > >> Eliot Kimber
      > >> Senior Solutions Architect, RSI Content Solutions
      > >> "Bringing Strategy, Content, and Technology Together"
      > >> Main: 512.554.9368
      > >> www.rsicms.com
      > >> www.rsuitecms.com
      > >> Book: DITA For Practitioners, from XML Press,
      > >> http://xmlpress.net/publications/dita/practitioners-1/
      > >>
      > >
      > >
      > >
      > >
      >
      > --
      > Eliot Kimber
      > Senior Solutions Architect, RSI Content Solutions
      > "Bringing Strategy, Content, and Technology Together"
      > Main: 512.554.9368
      > www.rsicms.com
      > www.rsuitecms.com
      > Book: DITA For Practitioners, from XML Press,
      > http://xmlpress.net/publications/dita/practitioners-1/
      >
    • despopoulos_chriss
      Well, this seems to be the consensus... So I ll stop worrying, and get to work. Thanks all!!!
      Message 2 of 13 , Oct 1, 2012
        Well, this seems to be the consensus... So I'll stop worrying, and get to work.

        Thanks all!!!

        --- In dita-users@yahoogroups.com, "matt_kaatman" <mkaatman@...> wrote:
        >
        > I agree. Why not just make them topics? Then you can set toc="no" on the topicref in the map if you don't want them to appear. Or setup your plugin to exclude beyond a certain level.
        >
        > --- In dita-users@yahoogroups.com, Sander Verhagen <sverhagen@> wrote:
        > >
        > > Hi,
        > >
        > >
        > > Should you not just make topics and nested topics?
        > >
        > > You have a choice to create topics in a new file or as nested topics within the same file. That sounds to satisfy your "deeper elements don't qualify as topics".
        > >
        > > I belief you can subsequently configure up to what level topics should appear in the table of contents.
        > >
        > > I had a similar situation coming from our legacy solution, where the nesting level sometimes went well into the double digits. I'm currently in the process of refactoring the document altogether, but that's besides the point. I converted everything to topics, then manually decided which topics warranted their own files, and which should just reside within their parent topic's file.
        > >
        > > I have never done anything with sections in DITA.
        > >
        > > Kind regards, Sander.
        > >
        > >
        > > From: dita-users@yahoogroups.com [mailto:dita-users@yahoogroups.com] On Behalf Of despopoulos_chriss
        > > Sent: vrijdag 28 september 2012 11:57
        > > To: dita-users@yahoogroups.com
        > > Subject: [dita-users] Re: I Want to Nest Sections!!!
        > >
        > >
        > >
        > > Converting unstructured FrameMaker files, using whatever I can make work (Maker conversion tables, API, XSLT, Java... Whatever). If I had an answer to this issue, I'd be nearly done.
        > >
        > > My nesting limit is in the semantics of the legacy. It must retain deeper headings, but the deeper elements don't qualify as topics. And <section> doesn't allow nesting. If it did, I'd have no problem. Certainly DITA has accounted for this need?
        > >
        > > I'm absolutely green with practical DITA (apologies). But I have done work with XML, from publishing catalogs to passing data to generating an array of language bindings for an API. So if I sound goofy, it's probably because I am...
        > >
        > > cud
        > >
        > > --- In dita-users@yahoogroups.com<mailto:dita-users%40yahoogroups.com>, Wayne Brisette <wbrisett@<mailto:wbrisett@>> wrote:
        > > >
        > > > I'm sure Eliott will correct me if I'm wrong, but there isn't a limitation based
        > > >
        > > > on the DITA spec. If there is a level limitation, that's in your implementation
        > > > of the DTD, not the DITA spec itself.
        > > >
        > > > What are you using to generate and build your DITA topics?
        > > >
        > > > Wayne
        > > >
        > >
        >
      • Eliot Kimber
        On 10/1/12 6:33 AM, despopoulos_chriss ... This is the difference between DITA as *practice* and DITA as syntax and structure.
        Message 3 of 13 , Oct 1, 2012
          On 10/1/12 6:33 AM, "despopoulos_chriss" <despopoulos_chriss@...>
          wrote:

          > Well, I thought one conceptual rule for a topic is that it must stand on its
          > own.

          This is the difference between DITA as *practice* and DITA as syntax and
          structure.

          In the context of technical writing practice, a topic should stand on its
          own, and in fact in the context of writing practice generally. Let's call
          this type of topic a "Topic" (uppercase "T") to distinguish it from a
          syntactic topic (lowercase "t").

          For good or ill, the DITA architecture today does not distinguish
          syntactically between Topics and topics. Syntactically, a topic is simply a
          container that is distinguished by *requiring* a title.

          That is one of the three distinguishing features of syntactic topics: they
          must have titles.

          No other titleable element in DITA *requires* a title and most elements may
          not have titles.

          The second distinguishing feature of topics is that they may nest without
          restriction at the base content model level, meaning that the base content
          model for topic is:

          Topic requires title (exactly one),
          allows prolog (zero or one),
          shortdesc or abstract (zero or one),
          body (zero or one),
          and topic (zero or more).

          Only topics may contribute to the titled hierarchy of a publication (which
          we normally take to mean the table of contents, or more generally, the
          "navigation hierarchy").

          Topics are also the unit of reuse from maps--maps can only point to topics
          (or other maps).

          Syntactically, because topics are the only thing that can nest, if you need
          any sort of arbitrarily-nested titled structure, your only choice is to use
          topics, even if these topics would not be Topics. This is just how it is.

          Of course, because you can specialize, you can choose to define your own
          specializations of topic that make a clearer distinction between Topic and
          topic in your content. You can define your DTDs or constraint modules so
          that only Topic elements are usable as topic document roots, that sort of
          thing.

          If you need arbitrarily-nested untitled structures, then you can use bodydiv
          or sectiondiv (DITA 1.2) or div (DITA 1.3) to create arbitrary structures
          for use within <body> or <section>. The key here is that these structures
          may not have directly-authored titles. (They may have titles or labels
          generated as a matter of output style, but they can't have literal <title>
          elements.)

          Finally, keep in mind that while it's often useful to manage Topics as
          individual files (that is, one Topic per file), that is not a requirement of
          the DITA standard. You could, if you really wanted to, put all the content
          of a whole publication into a single XML document with a single topic
          element as its root and nested topics to define the structure. Such a
          document would look very much like a typical DocBook document and would be
          perfectly processible by most DITA-aware processing tools. It would even be
          possible to reuse the nested topics within that document from other maps, it
          would just take more care with @chunk attributes on <topicref> tags to make
          sure you got the results you intended.

          In Publishing practice, for example, it is typical to manage content at the
          chapter level, where a given chapter topic will be a single XML document
          with all subordinate sections and sidebars held as nested topics within that
          document. There is no general requirement that each syntactic topic be
          stored and managed as a separate XML document (file).

          In general, your file-organization rules should reflect either your intended
          or required unit of reuse or your unit of authoring. That is, things are
          that intended primarily to be the unit of reuse from maps should be stored
          in separate XML documents. If reuse is not a primary concern, then things
          that are authored as a unit or by different authors should be stored as
          separate XML documents. This is because access control and addressing starts
          at the document (file) level, so aligning your file structure with your
          re-use and authoring units makes things easier (or, for weak management
          tools, possible).

          Applying this rule to tech docs, you see that it makes sense to manage
          top-level concepts, tasks, and reference items as separate files because
          those are usually the unit of reuse and/or authoring.

          Applying this rule to textbooks, you see that it makes sense to manage
          chapters, sidebars, tests, and exercises as separate files, because those
          are the units of re-use within textbooks. It doesn't usually make sense to
          manage subsections within chapters as separate files because those are
          seldom, if ever, re-used.

          Applying this rule to general Publishing, where there is little reuse, you
          see that it makes sense to manage chapters as separate files, because in
          most Publishing workflows the chapter is the unit of authoring.

          Cheers,

          Eliot

          --
          Eliot Kimber
          Senior Solutions Architect, RSI Content Solutions
          "Bringing Strategy, Content, and Technology Together"
          Main: 512.554.9368
          www.rsicms.com
          www.rsuitecms.com
          Book: DITA For Practitioners, from XML Press,
          http://xmlpress.net/publications/dita/practitioners-1/
        Your message has been successfully submitted and would be delivered to recipients shortly.