[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [dita] Stage 1 Proposal: "Titleless" Topics and Context-Independent Content
|
I am certainly in favor of this simpler approach. Not sure we would use it, but would be nice to have the optionâ Thanks, --Scott From:
<dita@lists.oasis-open.org> on behalf of Amber Swope <amber@ditastrategies.com> Dawn, If I understand your proposal, you are suggesting the following: For topics that are always âtitlelessâ, use the standard topic types and add an attribute to trigger processing to ignore the title For topics that are âtitlelessâ based upon context, use an attribute on the topic reference to trigger processing to ignore the title Did I get it right? Thanks, A -----Original Message----- Hello all, As you know I have taken on creating the Stage 2 proposal for this issue (which I have included in its entirety from Eliot below). However, as I have been drafting it, I have begun to question whether the solution
needs to be as complex as captured here in the Stage 1 proposal. Eliot's write-up below very well captures the essence of the need -- to use topics where the title of the topic is irrelevant and not desired in rendered output. He proposes a two-pronged solution
-- 1 -- to create a 'titleless' topic to indicate that the title is irrelevant and 2 -- to create a new type of topicref to indicate that in the particular context being referenced a normal topic should be treated as titleless. As I have attempted to expand on the solution for Stage 2, I have found myself feeling that perhaps the solution adds unneeded complexity for the given need.
Let me tackle what I think is the easier piece first -- the creation of a new specialized element from map/topicref to reference a "normal" topic as titleless. This is necessary because there may be situations
where the same topic requires a title in some outputs, but not in other outputs--we don't want to designate the topic as always titleless. My feeling here is that we can avoid the addition of a new element and simply add an attribute to <topicref> that indicates
if the topic is "titled" or not. By default, this attribute (let's call it @title for now) is set by default to "yes" meaning that people who don't need this feature don't need to do anything to continue as they have always done. The attribute appears in the
list of attributes, but like most of the attributes can be ignored by them and doesn't get in the way. The people who do need this feature, simply set @title to "no" to suppress the title from the rendered output for that map. No one has another element in
their list of elements to choose from or another element to constrain if they donât need it. The attribute can be inherited -- for example, setting it on <topicgroup> and then all <topicref> elements would inherit it.
In this solution, like many attributes, @title is establishing a presentation expectation. The need is still a topicref semantically -- the element continues to define its purpose -- to reference a topic; the
new attribute refines the presentation expectations for that single reference. This solution works fine, unless we introduce the idea of a titleless topic which already has processing built into it. What then would it mean to have a "titleless" topic referenced
with a topicref that says @title="yes"? This question leads to the larger issue of whether we need a separate topic type -- basically one that would never have @title attribute set to "yes". Without such a topic type, users would be forced to always
set the attribute to 'no' and that could become tedious. To start, this may be the argument that we have a separate specialized topicref. They have to reference the topic somehow in the map regardless, so it's no additional effort to choose <titlelesstopicref> over
<topicref> for example; and in this case, it would essentially be a convenience element. Similar to how mapref simply sets @format to ditamap, titleesstopicref would set @title to "no". My issue with creating an entire new topic type has to do with the fact that although we are calling this a titleless topic -- the title remains a required element in the DTD as described in Eliot's discussion.
When it comes to usability and complexity -- two things I have to write about in the Stage 2 proposal -- I run aground. "<title> is a required element in the "titleless" topic type" -- how does this make sense to a non-techie person who doesn't understand
how topics are specialized? Further, I keep coming back to there's no change in the structure of this topic. The whole purpose for the new topic would be simply to change presentation. That's contrary to every other topic type, each of which has clear structural
distinctions from each other. So I guess my question for discussion is whether we need the new topic type or can we handle the entire need through either a single attribute alone or the attribute and the "convenience" element that presets
the attribute? Thanks for your input, Dawn On 1/23/18, 7:28 AM, "dita@lists.oasis-open.org on behalf of Eliot Kimber" <dita@lists.oasis-open.org on behalf of
ekimber@contrext.com> wrote: "Titleless" Topics [NOTE: In this proposal I use the term "publication" to mean "the assemblage of content represented by a root map created primarily to then produce deliverables intended to be read by humans, as opposed to
other possible uses for maps that are not publications in this sense.] Requirement: The ability to use topics where the title of the topic is considered "uninteresting" and, as such, is not reflected in normal deliverables produced from the topic. While the title element is required, it
may have either empty content or arbitrary or even generated content that serves more as a unique identifier for content management purposes than as a descriptive title one would expect to see in a table of contents or in narrative flow. Here the word "titleless" is in quotes because the topics must still have title elements, but for the purposes of presentation the title is ignored, as though the topic did not have a title at all. It also
recognizes that title elements with empty content are both allowed and sensible in this context. An example of this is topics containing Learning and Training interactions (questions and answers), where the requirement is to combine large numbers of individual questions into test structures where each
question is contained in a separate topic but where the desired presentation result is as though all the questions under a single parent title had been in the body of a single topic, avoiding the need to use content references within multiple topics to achieve
the same presentation result. This concept of "titleless" topic then allows elements that would otherwise only be reusable only via content reference from within topics to be used from maps using normal topicrefs. Proposal: To satisfy the requirement for "titleless" topics, define two new specializations: Specialization 1: New topic type for "titleless" topics Define a new topic type, specialized from topic/topic, that has the explicit semantic of: The title of this topic is not interesting or useful in normal presentations and should, by default, be omitted.
The content of any abstract, the short description, and the content of the body of the topic should be presented as though they had occurred within the body of a topic that contains any siblings of the "titleless" topic. This topic type does not allow nesting
of topics. By "normal presentation" is meant deliverables generated from the map that uses the "titleless" topic, e.g., books, Web sites, etc. It establishes the default presentation expectation for topics of this type.
Use case: Topics that contain individual Learning and Training assessments for the specific purpose of enabling the construction of tests through a combination of normal topics to establish the test hierarchy
(and provide any required context, e.g., instructions, learning metadata, etc.) and topics that contain the test questions. Specialization 2: New topicref type for treating any topic as "titleless" Define a new topicref type, specialized from map/topicref, that has the explicit semantic of "treat the referenced topic as though it were a 'titleless' topic." Use case: Produce the same result as one would get from using the "titleless" topic type but from any topic type. Background: In DITA there are two basic forms of use-by-reference:
* The use of topics from maps via topicrefs * Content reference, which allows non-topic elements to be used from any context where the re-used element is allowed. Another fundamental aspect of DITA's design is that topics must have titles. Having a title is an essential distinguisher between topics and all other elements in the DITA vocabulary. Topics are the atomic
unit of content for publications. Topics are also intended to be more-or-less standalone units of reusable information. When organized by maps or literally nested within other topics, topic titles, by definition, define a strict hierarchy of titles, i.e.,
the table of contents of the publication. While topics are intended to be context-independent, meaning that as an atomic unit of content topics can be used and re-used in different places with little or no concern about the context in which they
are used, elements within topics are usually highly context dependent, contributing to the local narrative flow of the topic's content or providing metadata to specific elements within the topic or to the topic itself. For example, one would not normally expect
a given paragraph to be freely re-usable in any context. However, the experience of the DITA Learning and Training community is that there is a class of non-topic elements that are inherently without context: interactions (questions and answers as defined in the
learning domain) and objectives. Interactions, in particular, have the characteristic that they are, for the most part, individually independent of any context within which they might be used. For example, it is common practice to create
tests by randomly selecting a set of questions from a much larger pool of questions. Likewise, in this scenario where there is a large collection of reusable questions, each question will be classified with metadata about its subject area, specific learning
objectives or standards to which it applies, and so on, in order to facilitate the accurate selection of questions for a specific use (e.g., 7th-grade algebra for the state of Texas). At the same time, the typical interaction does not have a natural title. The prompt of a question is usually not distinguishing (e.g., "What is the sum of the following numbers:"). As defined in DITA 1.x, interactions are elements within topics, not topics themselves. (In DITA 1.2 interactions specialized from <fig>, in 1.3 they specialize from <div>). And in general, questions are
not appropriately modeled as topics--they are, fundamentally, content elements that go within topics. However, the reuse requirements for interactions make use directly from maps much more convenient than using interactions via content reference from within topics. For example, if you are creating a test
of hundreds of questions organized into a hierarchy it would be much more natural and much easier to do that work using a map and topicrefs than using multiple topics with many content references. Using maps, out-of-the-box map editing and management tools
will work well. Using content references, out-of-the-box editors do not generally support the ease of creation, organization, and modification that is required in this use case. Thus many users of the DITA Learning and Learning2 domains quickly realized that they really wanted to be able to treat questions as though they were topics for the purposes of defining test structures but
also realized that these questions did not have natural titles and, even if they were put into topics that had titles, for publication purposes they would not want the titles reflected in the final output. Several of us in the Learning and Training community
independently defined "question topics" that allowed this use of questions from maps.
That is, the use of interactions from maps requires a topic whose title and non-body content (abstract or short description) is not presented. Essentially, the desire is to have the topics containing questions
treated as though the contents of these topics had been the body content of whatever topic or topic head is the parent of these "question topics". A similar requirement exists for objectives, in that the same objective definition may apply to many learning objects or elements within learning objects (e.g., interactions that serve to assess achievement
of the objective). Like interactions, objectives do not have natural titles beyond the objective statement itself and the objective statement may not, by itself, be distinguishing. (For example, two states may have the same
learning objective, with the same objective statement text, but different metadata reflecting the existence of these state-specific objectives in different systems of learning standards.) It would be useful, for example, to be able to use relationship tables to associate objectives, as standalone objects, with other learning objects or with specific points in a map hierarchy in order to establish
the learning-object-to-objective relationships, rather than literally including the objectives in the learning objects, either as literal elements or via content reference, which are the only options today. But again, as a matter of presentation, if objectives were in topics related using normal map-level mechanisms, the desire would be for the titles of the objective-containing topics to not be presented, only
the objectives themselves. Thus there is a general requirement for a type of topic and/or a type of topicref that explicitly means "the title of the topic is not intended to be used in normal presentations".
-- Eliot Kimber --------------------------------------------------------------------- To unsubscribe from this mail list, you must leave the OASIS TC that
generates this mail. Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php |
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]