Image maps can be defined in DITA, but rather than being content, image maps contain presentational information. (In theory, DITA should only contain content, and not any presentational form information.)
--------------------------------------------------------------------------------
/Syntax_and_Markup/c_Mark-up_Concepts.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
5 | Working with mark-up
6 |
7 |
There are a number of concepts and principles of XML mark-up in general,
8 | and DITA mark-up in particular.
9 |
Variables are often used phrases (such as product names)
8 | that are re-used by replacing the value of the variable at the time the
9 | information is published.
10 |
DITA includes a range of elements and attributes to manage references in
8 | ditamaps, and to govern the way the references are treated during the
9 | publishing process.
10 |
To best take advantage of content re-use, you should adopt practices to
8 | reduce the impediments, increase the opportunities for re-use, and to make the
9 | process of re-using easier.
10 |
11 |
12 |
13 |
--------------------------------------------------------------------------------
/Metadata_Conditional/c_Filtering_and_Flagging.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 | Filtering and flagging
6 | Content marked with metadata attributes can be conditionally
7 | processed so that the content is filtered (excluded) or flagged (highlighted)
8 | in the published output.
9 |
10 |
11 |
12 |
13 |
--------------------------------------------------------------------------------
/Syntax_and_Markup/c_Lists.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 | Lists
6 | The purpose of a list is to make it easier for the reader to
7 | understand sequences of information and collections of like information.
8 | Different types of lists are used for different information structures.
9 |
10 |
11 |
12 |
13 |
--------------------------------------------------------------------------------
/Content_Reuse/c_Advanced_conref_Principles.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Advanced conref principles
5 |
6 |
The features and capabilities of content referencing was extended in
7 | DITA 1.2, making it possible to conref multiple elements at the one time, to
8 | indirectly reference content, and to
9 | push content from the source element.
10 |
Make sure you SVG editor is fully W3C SVG compliant. You will have fewer problems in Inkscape (an open source dedicated SVG editor) than you might have in a commercial tool such as Illustrator. Microsoft Visio also seems to provide compliant SVG output.
You should also try to draw your images in the size in which you wish to render the in the output.
--------------------------------------------------------------------------------
/Syntax_and_Markup/c_Procedures.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 | Procedures and steps
6 | The purpose of procedural documents is to explain to the reader
7 | how to accomplish tasks. The task information type is specifically designed for
8 | procedures, with a well-defined structure built around steps.
9 |
10 |
11 |
12 |
13 |
--------------------------------------------------------------------------------
/c_The_DITA_Publishing_Process.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | The DITA documentation process
5 |
6 | The most difficult thing is the decision to
7 | act, the rest is merely tenacity. The fears are paper tigers. You can do
8 | anything you decide to do. You can act to change and control your life; and the
9 | procedure, the process is its own reward.
10 |
11 |
12 |
13 |
--------------------------------------------------------------------------------
/c_Working_with_Graphics_and_Figures.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Graphics and figures
5 | graphicsimagesfigures
6 |
7 |
8 | Un bon croquis vaut
9 | mieux qu'un long discours. (A good sketch is better than a long speech.)
10 |
11 |
12 |
13 |
--------------------------------------------------------------------------------
/Syntax_and_Markup/c_Software_Domain.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 | Software domain
6 | domainssoftwaresoftware
7 | domain
8 |
9 |
10 |
The software domain elements are designed for documenting the operation
11 | of a software program.
12 |
13 |
14 |
15 |
--------------------------------------------------------------------------------
/Syntax_and_Markup/c_Tables.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Tables
5 | The purpose of a table is to structure,
6 |
8 | and present factual data that a user will need to look up or reference. There
9 | are two general purpose table types in DITA:
10 | table and
11 | simpletable.
12 |
13 |
14 |
--------------------------------------------------------------------------------
/c_Syntax_and_Markup.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
5 | Syntax and mark-up
6 |
7 | I ascribe a basic importance to the phenomenon
8 | of language. To speak means to be in a position to use a certain syntax, to
9 | grasp the morphology of this or that language, but it means above all to assume
10 | a culture, to support the weight of a
11 | civilization.
12 |
13 |
14 |
15 |
--------------------------------------------------------------------------------
/Maps/obsolete_c_Excluding_Topics_from_Output_TOC.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 | Excluding Topics from the Output Table of Contents
If a topic is to be included in the output file (eg, a CHM file) it must be nominated in the ditamap. The ditamap is used as the basis for the Table of Contents in many output types. To exclude a topic from the output table of contents, the relevant ditamap topicref must have its toc attribute set to no.
The utilities domain elements are non-semantic elements used in defining
12 | image maps.
13 |
14 |
15 |
16 |
--------------------------------------------------------------------------------
/c_Content_Re-use.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
5 | Content re-use
6 |
7 | Re-use, re-use, re-use,
8 | re-use... content re-use is key to content management so it bears repeating
9 | repeating repeating. Content re-use means that you can write content once and
10 | use it wherever required, but it also means that you have to write content
11 | consistently so that it can be re-used.
12 |
13 |
14 |
15 |
--------------------------------------------------------------------------------
/c_Topics_and_Information_Types.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 | Information types and topics
6 | Topics are the building blocks of modular documents, and
7 | organising topics by semantic information types is one of the architectural
8 | features of DITA.
9 |
10 |
11 | Information is not knowledge. Knowledge is not
12 | wisdom. Wisdom is not truth.
13 |
14 |
15 |
16 |
--------------------------------------------------------------------------------
/Syntax_and_Markup/c_User_Interface_Domain.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 | User interface domain
6 | domainsuser
7 | interfaceuser interface
8 | domain
9 |
10 |
11 |
The user interface domain elements are designed for documenting the user
12 | interface of a software program.
13 |
The metadata domain elements are designed for describing index entries
11 | and map-level metadata elements.
12 |
13 |
14 |
15 |
--------------------------------------------------------------------------------
/Maps/c_Collection_Type_Example_Choice.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Collection type example:
5 |
6 |
7 |
8 | Example of
9 | collection type
12 | Example of choice collection type
13 |
14 |
15 |
16 |
17 |
--------------------------------------------------------------------------------
/Maps/c_Collection_Type_Example_Family.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Collection type example:
5 |
6 |
7 |
8 | Example of
9 | collection type
12 | Example of family collection type
13 |
14 |
15 |
16 |
17 |
--------------------------------------------------------------------------------
/Maps/c_Collection_Type_Example_Sequence.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Collection type example:
5 |
6 |
7 |
8 | Example of
9 | collection type
12 | Example of sequence collection type
13 |
14 |
15 |
16 |
17 |
--------------------------------------------------------------------------------
/Metadata_Conditional/c_Other_Metadata.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 | Other metadata
6 | In addition to the select attributes, DITA content includes many
7 | forms of metadata. These metadata elements and attributes are used to manage
8 | and
9 |
11 | topics, ditamaps and publications.
12 |
13 |
14 |
15 |
16 |
--------------------------------------------------------------------------------
/Content_Reuse/c_Organising_Reuse_Elements.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
6 | re-use topics and elements
7 |
8 |
Re-use of content is easier for the author to accomplish if the elements
9 | to be re-used are carefully
10 |
12 | in predictable locations.
13 |
14 |
15 |
16 |
--------------------------------------------------------------------------------
/Cross_Referencing/c_Cross-referencing_Elements_in_a_Topic.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 | Cross-referencing elements in a topic
6 | Cross-references to elements within topics such as figures and
7 | tables allow a reader to easily navigate through a document, whether it is in a
8 | page layout format or a hypertext format. The
9 | xref element is always used for cross-referencing elements
10 | within a topic.
11 |
12 |
13 |
14 |
15 |
--------------------------------------------------------------------------------
/Maps/c_Collection_Type_Example_Unordered.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Collection type example:
5 |
6 |
7 |
8 | Example of
9 | collection type
13 | Example of unordered collection type
14 |
15 |
16 |
17 |
18 |
--------------------------------------------------------------------------------
/Syntax_and_Markup/c_Programming_Domain.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 | Programming domain
6 | domainsprogrammingprogramming
7 | domainexemplarchunking
8 | attribute
9 |
10 |
11 |
The elements in the programming domain are designed for documenting
12 | programming languages.
13 |
14 |
15 |
16 |
--------------------------------------------------------------------------------
/artefact_introduction.ditamap:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
9 |
--------------------------------------------------------------------------------
/Cross_Referencing/c_Cross-referencing_Topics_and_External_Resources.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
5 | Cross-referencing topics and external resources
6 | Cross-references are commonly made to other DITA topics in a
7 | collection, and to information resources outside the collection. These external
8 | targets can be any type of electronic resource that can be addressed through a
9 | URI, including e-mail addresses, documents on a network file server, and Web
10 | content.
11 |
12 |
13 |
14 |
15 |
--------------------------------------------------------------------------------
/c_Conventions_(Not_Included_in_Output).dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 | Conventions (Not Included in Output)
6 |
7 |
8 |
9 |
ditamap is not a term; it is just a normal word. The exception is when
10 | it is being defined. Avoid starting a sentence with ditamap.
11 |
12 |
conref is not a term; it is just a normal word. The exception is when it
13 | is being defined. Avoid starting a sentence with conref.
14 |
15 |
16 |
17 |
--------------------------------------------------------------------------------
/Documentation_Process/c_Help2_from_DITA_Source.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Microsoft Help 2 from DITA Source
5 |
6 |
If you need to create Microsoft Visual Studio Help 2 output, the best
7 | approach is to create an HTML Help (.chm) file through the DITA Open Toolkit
8 | normally, and then use a tool such as HelpWare FAR to convert the .chm file to
9 | .hxs format.
10 |
11 |
13 |
14 |
15 |
16 |
17 |
--------------------------------------------------------------------------------
/conref/conref_source_footnotes.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 | Conref Source for Footnotes
6 | This topic is not meant for inclusion in a ditamap, but as a
7 | source of transcluded footnote content.
8 |
9 |
10 |
A footnote must exist in a paragraph, as it is an inline element, not a
11 | block element.
12 |
13 |
Ament, K., 2003. Single Sourcing: Building Modular
14 | Documentation 1st ed., New York: William Andrew Publishing.
15 |
16 |
17 |
18 |
--------------------------------------------------------------------------------
/c_Language_and_Punctuation.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 | Language and punctuation
6 |
7 | If language is not correct, then what is said is
8 | not what is meant; if what is said is not what is meant, then what must be done
9 | remains undone; if this remains undone, morals and art will deteriorate; if
10 | justice goes astray, the people will stand about in helpless confusion. Hence
11 | there must be no arbitrariness in what is said. This matters above everything.
12 |
13 |
14 |
15 |
--------------------------------------------------------------------------------
/c_Types_of_Metadata.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 | Metadata, conditional processing, and indexing
6 |
7 | Knowledge is not gained by collecting
8 | information, but by understanding what information to throw away.
9 |
10 |
12 | References
13 |
John Durham Peters quotation from keynote address delivered at ANZCA
14 | 2010, Canberra, Australia.
15 |
It is possible that an unordered list's items might be re-sequenced (if
7 | not randomised), such as where the unordered list comprises possible answers
8 | for a multiple choice question in a Learning specialisation topic.
9 |
10 |
Perhaps discuss that lists can be sorted during processing. Maybe use
11 | linklist and linkpool as examples.
12 |
Refer to http://www.thecontentwrangler.com/article/do_screen_captures_still_makes_sense/
Summary:
Ask yourself, will users still be successful in performing their intended task and find the information useful, without the presence of one or more screen captures? Do one of the following:
If yes to #1, do not include the screen capture(s).
If no to #1, make improvements to the surrounding prose (and possibly the application UI). Then proceed to #1
Another interesting difference is that DITA allows other information
11 | types to be defined through
12 | specialisations. Some common DITA specialisations are:
13 |
Topic-level content reuse is simple to understand.
9 |
10 |
A ditamap is an ingredient list of a collection. More than one ditamap
11 | can reference the same topic.
12 |
13 |
So if you have a repository of DITA content topics covering how to use a
14 | range of cameras from the same manufacturer, we could create a ditamap for the
15 | Model 400 User Guide, another ditamap for the
16 | Model 700 User Guide, and another for the
17 | Model 700 Administrator's Guide. Some topics might be common
18 | to all ditamaps, while others might be unique to one.
19 |
24 |
25 |
26 |
27 |
--------------------------------------------------------------------------------
/Language_and_Punctuation/c_Avoiding_Writing_for_Output.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Avoiding writing for output
5 | Do not include formatting information in your DITA content topics.
6 |
7 |
8 | Tony Selfseparation
9 | of content and
10 | formagnosticpresentation
11 |
12 |
13 |
If you find that you are deliberately coding your DITA topics in such a
14 | way as to achieve a particular output effect, you are without doubt taking the
15 | wrong path. DITA topics must be delivery-agnostic; they must be free of as much
16 | context (how the information is going to be used, presented or sequenced) as
17 | possible.
18 |
A common form of documentation is Application Programming Interface (API) documentation. This involves documenting the functions of a shared programming library, and allows developers to re-use common programming functions. The information structure of an API function may be:
File Name
Prototype
Arguments
Options
Return Values
Related Functions
Usage example
A specialised reference information types should be used for this sort of information structure. Some such specialised information types are available publicly, and are suited for particular programming languages. For example, the is a Java API information type available from the DITA Open Toolkit area on SourceForge.
--------------------------------------------------------------------------------
/Authoring_Concepts/obsolete_c_A_Definition_of_DITA.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | A Definition of DITA
5 | DITA can be defined an open standard for creating, sharing and
6 | re-using content.
7 |
8 | Tony
9 | SelfDITAdefinitionRockley,
10 | Manning, et al
11 |
12 |
13 |
Just as they provided a good definition of what architecture means in
14 | the DITA context,
15 | Rockley, Manning et al follow up with a lovely, succinct
16 | definition of DITA.
17 |
18 | DITA is an open content
19 | standard that defines a common structure for content that promotes the
20 | consistent creation, sharing, and reuse of content.
21 |
22 |
23 |
24 |
--------------------------------------------------------------------------------
/Cross_Referencing/c_The_desc_Element_in_Links.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
5 | The
6 | desc element in links
7 | Descriptive metadata can be added to
8 | link elements in the
9 | related-links section.
10 |
11 | Tony Selfdesc
12 | elementrelated-links
13 | elementsdescelementsdesclink
14 |
15 |
16 |
The
17 | desc element inside the
18 | link element holds a description of the link target. The
19 | desc content is not rendered as content, but will
20 | typically appear as tooltip text in online outputs.
21 |
22 |
23 |
24 |
--------------------------------------------------------------------------------
/Syntax_and_Markup/c_Paragraphs.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
5 | Paragraphs
6 | Paragraphs are the basic components of topics. A paragraph
7 | (p) element should be a self-contained unit dealing with one
8 | idea or point, typically expressed in two or more related sentences. The
9 | p element should be used when no other semantically-specific
10 | block element is available.
11 |
12 |
13 |
15 | Rationale
16 | There are two purposes for paragraphs, the
17 | one logical and the other practical. The logical purpose is to signal stages in
18 | a narrative or argument. The practical one is to relieve the forbidding gloom
19 | of a solid page of text.
20 |
21 |
22 |
23 |
24 |
--------------------------------------------------------------------------------
/Syntax_and_Markup/obsolete_c_Using_Term_Element_for_Definitions.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Using the
5 | term Element When Defining a Term
6 |
7 |
How should an expansion of acronym, abbreviation or other term be
8 | handled? For example, in the snippet:
9 |
10 | technologies such as XML Localization Interchange File Format
11 | (XLIFF)
12 |
13 |
should the mark-up be:
14 |
15 | technologies such as XML Localization Interchange File Format (<term>XLIFF</term>)
16 |
or
17 |
18 | technologies such as <term>XML Localization Interchange File Format</term> (<term>XLIFF</term>)
19 |
or
20 |
21 | technologies such as <term>XML Localization Interchange File Format</term> (XLIFF)
22 |
or something else?
23 |
24 |
25 |
26 |
--------------------------------------------------------------------------------
/Topics_and_Information_Types/c_Disambiguation_Topics.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Disambiguation topics
5 | Disambiguation topics help direct readers to the appropriate
6 | content where a term or concept is ambiguous and may refer to more than one
7 | topic.
8 |
9 | Tony
10 | Selfdisambiguationparent
11 | topics
12 |
13 |
14 |
Disambiguation topics help clarify ambiguity when one term
15 | or topic title may relate to a number of different topics. For example, a term
16 | ABS may stand for
17 | Anti-lock Braking System or for
18 | Automatic Brightness Sequencer. A disambiguation topic is
19 | typically a single topic explaining the different uses of the term, and links
20 | to the relevant alternative topics.
21 |
Transitional text is text that leads the reader to a following topic, or
12 | connects the topic to a previous topic. Examples of transitional text include:
13 | As we saw previously... and
14 | This processed is explained later.... In DITA, topics should be
15 | designed to be context-agnostic, so that a topic can be re-used in different
16 | publications or outputs, in different sequences. Transitional text reduces
17 | re-use opportunities.
18 |
19 |
20 | This could be merged with similar topics on glue text
21 |
22 |
23 |
24 |
25 |
--------------------------------------------------------------------------------
/Topics_and_Information_Types/c_Task.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Task
5 | The
6 | task topic is one of the three base DITA information types.
7 |
8 | Tony Selfinformation
9 | typestasktask information
10 | typetask topic
11 |
12 |
13 |
Task topics are used to document the steps of a particular task or procedure,
14 | or to document the stages within a high level process. Task topics are the building
15 | blocks for task-oriented documentation. Task topics are more strictly structured than
16 | concept and reference topics.
17 |
Task topics address the question of how to?.
18 |
The root element of a task topic is
19 | task.
20 |
21 |
22 |
23 |
--------------------------------------------------------------------------------
/c_Cross-referencing.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
5 | Cross-referencing
6 | Cross-references are a means of binding individual topics into a
7 | coherent and navigable document.
8 |
9 | linkinglinkslinkslinking
10 |
11 |
12 | There
14 | is no greater skill a web professional needs to develop than the ability to
15 | create quality links. Many websites do not need more publishing. Rather, they
16 | need more linking of content in appropriate task journeys. Linking is a complex
17 | skill because it requires you to see the task through your customer's eyes.
18 |
19 |
20 |
21 |
--------------------------------------------------------------------------------
/Content_Reuse/obsolete_c_Linking_Dangers_with_Content_Reuse.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Problems with links in re-used content
5 |
6 |
There is a danger in including links (xref elements)
7 | within the text of a topic. This potential problem did not exist in many
8 | earlier authoring environments. But with comprehensive content re-use, the
9 | eventual context of a topic is unknown to the author. Including a link creates
10 | a dependency on the link target. If the source topic is used in a collection
11 | (or information set) that does not include the target, the link will be broken.
12 |
13 |
14 |
The solution to this problem in DITA is map-based linking. Links can be
15 | automatically generated at the bottom of each topic, with the links based on
16 | either the structure of the hierarchy of
17 | topicrefs in the ditamap, or instructions in a
18 | relationship table in the map.
19 |
10 | Describe stub or disambiguation topics that use generated
11 | child topic short descriptions. Show how collection-type attribute affects the
12 | way these child topics are listed. Refer to Swinburne DITA strategy if
13 | necessary, or use the Collection Type Examples parent node from this Maps
14 | chapter. Screen captures of the different results would be useful. Perhaps move
15 | some content from discussion of
16 | shortdesc in the Exegesis.
17 |
18 | There is a reference to generated summary content in
19 | (stub) parent topics in Hierarchical Linking Relationships.
20 |
21 |
To create a new topic type (something other than topic, task, concept or reference), the steps that Eliot Kimber suggests you should follow are:
Work out which elements you will need in your new topic type. For example, if your new topic type is designed to contain lists of airliner registrations, you may decide you need elements for manufacturer, build number, model number, model name, version number, country of registration, and registration code.
"Clone" the shell DTD of the base topic type that is the closest match to your new topic type. For example, our airliner registration topic may be a specialised type of reference topic.
Create a sample document with the mark-up for the new topic type.
Modify the DTD modules until the sample document validates.
--------------------------------------------------------------------------------
/Authoring_Concepts/c_Information_Types.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
5 | Information typing
6 | Information typing is a methodology which underpins
7 | DITA. Information is structured by topics with content models appropriate to
8 | the nature of the content. The three base DITA information types are concept,
9 | task and reference.
10 |
11 | information
13 | types
14 |
15 |
16 |
18 |
19 |
Information typing is also used in other methodologies such as
20 | .
22 |
23 |
24 |
25 |
--------------------------------------------------------------------------------
/Topics_and_Information_Types/c_Concept.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Concept
5 | The
6 | concept topic is one of the three base DITA information types.
7 |
8 |
9 | Tony Selfinformation
10 | typesconceptconcept information
11 | typeconcept topic
12 |
13 |
14 |
Concept topics are used to document conceptual or overview information.
15 | They contain background information that users must know before they can successfully
16 | work with a product or within a process. Concepts can be broken into sections, but they
17 | are primarily comprised of simple paragraphs and unordered lists.
18 |
Concept topics answer the question what is?.
19 |
The root element of a concept topic is
20 | concept.
21 |
22 |
23 |
24 |
--------------------------------------------------------------------------------
/Maps/c_Collection_Type_Examples.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Collection type examples
5 | The effect of the
6 | collection-type attribute on the output publication is well
7 | illustrated with examples of the results of the use of different types.
8 |
9 | collection-type
10 | attributeexamplesgenerated
11 | linksexamplesreltableexamples
12 | of links
13 |
14 |
15 |
17 | Future enhancements
18 |
Change the examples in this group of topics to
19 |
21 | examples from subaru_repository.ditamap.
22 |
23 |
24 |
25 |
26 |
--------------------------------------------------------------------------------
/Syntax_and_Markup/c_Body_Elements.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Body elements
5 | The simple block structures within the body of topics are
6 |
8 | as the
9 | body elements.
10 |
11 | Tony
12 | Selfelementsbodybody
13 | elements
14 |
15 |
16 |
Body elements are the most common content authoring block elements, and
17 | include:
18 |
19 |
20 |
paragraph
21 |
22 |
list
23 |
24 |
phrase
25 |
26 |
figure
27 |
28 |
29 |
30 |
31 |
--------------------------------------------------------------------------------
/Metadata_Conditional/c_Indexing.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Indexing
5 | DITA incorporates powerful features for indexing, including
6 | multi-level indexing, and
7 | see and
8 | see-also redirection. Index entries can be applied in the ditamap,
9 | in the topic prolog, and inline within the topic content.
10 |
11 | Tony
12 | Selfindexes
13 |
14 |
15 |
The indexing features in DITA are built around three elements:
16 | indexterm,
17 | index-see, and
18 | index-see-also. These elements can technically be placed
19 | at almost any point in the body of a topic, as well as in the topic
20 | prolog and in the
21 | topicmeta of the topicref in the ditamap. However, to
22 | avoid potential translation and processing complications, the elements should
23 | be deliberately placed in specific locations within the topic or map.
24 |
10 | Talk about nesting relationship tables, and having
11 | multiple relationship tables. Also, storing reltables in separate maps from the
12 | hierarchy. Diagram would help. This might become an essay (probably not as big
13 | as a paper).
14 |
15 | Mention that in task-oriented documentation, the task
16 | should be the focal point for reltable design. The reltable can be started with
17 | a row for each task topic, and then concept and reference topicrefs added as
18 | required.
19 |
20 |
26 |
27 |
28 |
29 |
--------------------------------------------------------------------------------
/Syntax_and_Markup/c_Prolog_Elements.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Prolog elements
5 | A topic's metadata is stored in a range of
6 | prolog elements.
7 |
8 | Tony
9 | Selfelementsprologprolog
10 | elements
11 |
12 |
13 |
The DITA prolog elements contain the main metadata for a topic or
14 | collection.
15 |
16 |
The types of information recorded in the prolog include:
17 |
18 |
author
19 |
20 |
copyright information
21 |
22 |
critical tracking dates
23 |
24 |
permissions for
25 | use/management of the content
26 |
27 |
extensive metadata about the
28 | content of the document
29 |
30 |
31 |
32 |
33 |
34 |
--------------------------------------------------------------------------------
/Topics_and_Information_Types/c_Reference.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Reference
5 | The
6 | reference topic is one of the three base DITA information
7 | types.
8 |
9 | Tony Selfinformation
10 | typesreferencereference
11 | information type
12 |
13 |
14 |
Reference topics are used to describe features of sets of things, such
15 | as codes, types and commands. Information that normally demands tabular presentation
16 | probably belongs in reference topics. Catalogues, directories and bibliographies are
17 | good examples of reference topic information. Reference topics are often into tables.
20 |
Reference topics contains facts without explanation.
21 |
The root element of a reference topic is
22 | reference.
23 |
24 |
25 |
26 |
--------------------------------------------------------------------------------
/Syntax_and_Markup/r_Typography_Domain_Elements.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
5 | Typographic domain elements
6 | The typographic domain elements each have a specific styling
7 | purpose.
8 |
9 | Tony
10 | Selfelementstypographictypographic
11 | domain
12 |
13 |
14 |
15 | Element NameSemantic
16 | Purpose
17 |
18 | bbold (strong)
19 |
20 | iitalic (emphasis)
21 |
22 | uunderlined
23 |
24 | ttteletype (typewriter)
25 |
26 | supsuperscript
27 |
28 | subsubscript
29 |
30 |
31 |
32 |
33 |
--------------------------------------------------------------------------------
/Documentation_Process/c_File_Naming_Conventions.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | File and folder naming conventions
5 | Using an
6 | ,
8 | well-documented file naming and folder structure convention will improve the
9 | usability of the authoring process for DITA authors, especially those working
10 | in a team.
11 |
12 | file
14 | namingconventionsfolder
15 | namesdirectory names
16 |
17 |
18 |
Use descriptive folder and file names. Use
19 | .dita as the file extension for topic files, and
20 | .ditamap for ditamap files. File names are
21 | case-sensitive, and lower case file names are preferred. Prefix topic names
22 | with a letter corresponding to their information type.
23 |
24 |
25 |
26 |
--------------------------------------------------------------------------------
/Syntax_and_Markup/r_Utilities_Domain_Elements.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
5 | Utilities domain elements
6 | The elements in the utilities domain each have a specific purpose
7 | in defining image map properties.
8 |
9 | Tony
10 | Selfelementsutilitiesutilities
11 | domainimage
12 | mapshypergraphics
13 |
14 |
15 |
16 | Element NameSemantic
17 | Purpose
18 |
19 | imagemapclient-side image
20 | map
21 |
22 | areahotspot area within an image
23 | map
24 |
25 | coordsco-ordinates of a hotspot area
26 | within an image map
27 |
28 | shapeshape of a hotspot area within an
29 | image map
30 |
31 |
32 |
33 |
34 |
--------------------------------------------------------------------------------
/Syntax_and_Markup/r_userinterface_domain_elements.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
6 | User interface domain elements
7 | The elements in the user interface domain each have a specific
8 | semantic purpose.
9 |
10 | Tony
11 | Selfelementsuser
12 | interfaceuser interface
13 | domain
14 |
15 |
16 |
17 | Element NameSemantic
18 | Purpose
19 |
20 | uicontroluser interface
21 | control
22 |
23 | wintitlewindow title
24 |
25 | menucascademenu cascade
26 |
27 | shortcutshortcut
28 |
29 | screencharacter (text only) screen
30 |
31 |
32 |
33 |
34 |
35 |
--------------------------------------------------------------------------------
/Content_Reuse/winant_generated_ditamap.ditamap:
--------------------------------------------------------------------------------
1 |
2 |
--------------------------------------------------------------------------------
/Syntax_and_Markup/c_Map_Elements.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
5 | Map elements
6 | The
7 | map elements are the elements used in ditamaps and bookmaps.
8 |
9 | Tony
10 | Selfelementsmapmap
11 | elements
12 |
13 |
14 |
The map elements are a small set of elements, some of which have been
15 |
17 | into other elements for use in bookmaps.
18 |
The elements in the typographic domain are used to describe styling
11 | characteristics. They are primarily intended as the basis for
12 | .
14 | Avoid using these elements.
15 |
16 |
Semantic elements should always be used in preference
17 | to typographic elements.
18 |
19 |
21 | Rationale
22 | Never use these elements when a semantically specific element is
23 | available. These elements are not intended for use by
24 | specializers, and are intended solely for use
25 | by authors when no semantically appropriate element is available and a
26 | formatting effect is required.
27 |
28 |
29 |
30 |
31 |
--------------------------------------------------------------------------------
/Cross_Referencing/c_The_linkinfo_Element.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | The
5 | linkinfo element
6 | The
7 | linkinfo element can be used to add a block of descriptive
8 | text to a link list.
9 |
10 | Tony Selflinkinfo
11 | elementelementslinkinfolinklistrelated-links
12 | elementslinkinfo
13 |
14 |
15 |
The
16 | linkinfo element can be used within the ordered link list
17 | (linklist) element to provide an explanation of the purpose of
18 | the list of links. The
19 | linkinfo block typically appears after the list of links
20 | in the output reading format.
21 |
22 |
When used in conjunction with a
23 | title element also within the
24 | linklist, you can create a brief description of a process
25 | in the
26 | related-links section. However, you should always prefer
27 | creating small task topics, or stub topics with generated links to
28 | child tasks.
29 |
30 |
31 | Maybe add example?
32 |
33 |
34 |
35 |
36 |
--------------------------------------------------------------------------------
/Authoring_Concepts/c_Use_of_Class_Attribute.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Use of Class Attribute
5 | The class attribute in DITA is not analogous to the class element
6 | in HTML. DITA's class element is used for specialisation, and should not be set
7 | by authors.
8 |
9 | Tony
10 | Selfclassattributesclassoutputclassspecialisationinheritance
11 |
12 |
13 |
All DITA elements have a
14 | class attribute, but as a DITA author, you should never
15 | change this attribute. In fact, most DITA editors will hide it from you. The
16 | DITA
17 | class attribute is not the same as the HTML
18 | class attribute. (DITA's
19 | outputclass attribute is the closest match to HTML
20 | class.)
21 |
22 |
All DITA based processors use the
23 | class attribute to determine how an element should be
24 | processed, rather than by using the element name itself. This is because
25 | specialisation may make the element name unfamiliar to the processor, but the
26 | class will indicate the element's inheritance, and therefore how it should be
27 | handled.
28 |
Do not include any unlinked text in the related links
10 | linklist element; it should contain only
11 | link elements.
12 |
13 |
14 | The schema prevents this anyway? Furphy?
15 |
16 | This topic was Related Links Groups
17 |
18 |
19 |
21 | Rationale
22 |
Answering a question about whether additional text is allowed within
23 | the
24 | link element but outside the child
25 | linktext element:
26 |
27 |
29 |
Having text like that plays havoc with localization anyway, so it
30 | was just too much trouble to even try.
31 |
32 |
Go with relationship tables. Remember that you can use multiple
33 | relationship tables, if that makes them easier for you to work with.
34 |
35 |
36 |
37 |
38 |
39 |
--------------------------------------------------------------------------------
/Syntax_and_Markup/duplicated_c_Phrases_and_Blocks.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 | Phrases and Blocks
6 | DITA domain elements can be classified into
7 | block elements and
8 | phrase elements.
9 |
10 | Tony Selfphrase
11 | elementsblock elementsinline
12 | elementsspan elementsparagraph
13 | elements
14 |
15 |
16 |
In XML document mark-up languages, including DITA and XHTML, there are
17 | typically two types of content mark-up elements: block (or paragraph) elements,
18 | and phrase (or inline) elements.
19 |
20 |
Phrases are spans of text within a larger block of text, such as words
21 | within a paragraph. Typical phrase elements are term (term),
22 | code phrase (codeph), quotation (q), and syntax
23 | phrase (synph).
24 |
25 |
Blocks are paragraph-like elements, which are normally displayed with
26 | spacing above and below the block. Typical block elements are paragraph
27 | (p), code block (codeblock), long quotation
28 | (lq), and note (note).
29 |
30 |
31 |
32 |
--------------------------------------------------------------------------------
/Syntax_and_Markup/r_software_domain_elements.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
5 | Software domain elements
6 | The elements in the software domain each have a specific semantic
7 | purpose.
8 |
9 | Tony
10 | Selfelementssoftwaresoftware
11 | domain elements
12 |
13 |
14 |
15 | Element NameSemantic
16 | Purpose
17 |
18 | msgphmessage phrase
19 |
20 | msgblock message block
21 |
22 | msgnummessage number
23 |
24 | cmdnamecommand name
25 |
26 | varnamevariable (to be provided by
27 | user) name
28 |
29 | filepathfile name or path, or
30 | URI
31 |
32 | userinputuser input
33 |
34 | systemoutputsystem output
35 |
36 |
37 |
38 |
39 |
--------------------------------------------------------------------------------
/Language_and_Punctuation/c_Line_Breaks_in_Titles.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Line breaks in titles
5 | There is no line break element or equivalent in DITA.
6 |
7 | Tony Selfline
8 | breaksseparation of content and
9 | formworkarounds
10 |
11 |
12 |
Line breaks are formatting constructs, so in general, DITA mark-up
13 | doesn't provide for them. However, it's not quite so clear cut. Despite working
14 | to the ideal that content should be separated from form, DITA does provide for
15 | a good deal of form mark-up.
16 |
17 |
Table column widths can be specified in DITA, even though that's form.
18 | Image sizes can be specified in DITA, and that too is form.
19 |
20 |
It is possible to use these loopholes in the separation of content and
21 | form to make possible things such as line breaks in titles. For example, a
22 | workaround is to place a one pixel by one pixel image within the title, and set
23 | the image element's placement attribute to break. This will cause, in most
24 | outputs, the title to be displayed with text before the image displayed on a
25 | different line to text following.
26 |
27 |
You must avoid the temptation to use such workarounds
28 | in an attempt to introduce form into DITA content.
29 |
30 |
31 |
32 |
--------------------------------------------------------------------------------
/Maps/c_Breadcrumbs.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
6 | Breadcrumbs
7 | Breadcrumb trails are navigation tools used in some online
8 | document formats, and can be automatically generated from DITA source.
9 |
10 | Tony
11 | SelfbreadcrumbsnavigationEclipse
12 | Help
13 |
14 |
15 |
A feature of some document delivery formats, notably Eclipse Help, is
16 | the
17 | breadcrumb trail.
18 | Breadcrumbs provide the user with the position of the
19 | currently displayed topic in the TOC hierarchy through links to parent and
20 | other ancestor topics.
21 |
22 |
Breadcrumbs are derived entirely from the TOC structure,
23 | and do not need to be separately defined in the DITA source.
24 |
25 |
26 | TOC hierarchy used to derive breadcrumb trail in Eclipse Help
27 | output
30 | Screen capture showing how TOC hierarchy is used to create a
31 | breadcrumb trail at the top of a topic
32 |
33 |
34 |
35 |
36 |
--------------------------------------------------------------------------------
/Syntax_and_Markup/c_Topic_Elements.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Topic elements
5 | The
6 | topic elements are the basic structural building blocks of all
7 | information types.
8 |
9 | Tony
10 | Selfelementstopictopic
11 | elements
12 |
13 |
14 |
The topic elements are the main structural elements of topics. Some
15 | topic elements are generic (ie, inherited from the
16 | topic proto information type), while others are specific to
17 | the concept, task or reference information types.
18 |
body (and refbody, conbody,
29 | taskbody, glossBody)
30 |
31 |
section
32 |
33 |
example
34 |
35 |
related-links
36 |
37 |
38 |
39 |
40 |
41 |
--------------------------------------------------------------------------------
/Metadata_Conditional/c_Conventions_for_otherprops.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Conventions for the
5 | otherprops attribute
6 | By using a convention for recording values in the
7 | otherprops attribute, you can extend the amount of metadata
8 | stored.
9 |
10 | Tony Selfotherprops
11 | attributemetadata
12 | attributesconventionsattributesotherpropsconventionsattributes
13 |
14 |
15 |
The
16 | otherprops attribute can be used for storing any other
17 | metadata information that does not otherwise fit into the standard condition
18 | attributes (audience,
19 | platform, and
20 | product).
21 |
22 |
To extend the functionality of the
23 | otherprops attribute, a naming convention can be used that
24 | a processor can interpret and action. For example, settings of
25 | otherprops="Market(Australia)" and
26 | otherprops="Publication(Symmetry)" would allow the same
27 | attribute to be used for a number of functions. In this example, a processor
28 | could differentiate between
29 | Market and
30 | Publication.
31 |
32 |
33 |
34 |
--------------------------------------------------------------------------------
/Metadata_Conditional/c_The_props_Attribute.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
5 | The
6 | props attribute
7 | The
8 | props attribute is only used for
9 |
11 | new metadata attributes.
12 |
13 | Tony
14 | Selfattributespropsselect
15 | attributescondition
16 | attributesprops attribute
18 |
19 |
20 |
The
21 | props attribute is technically one of the select (or
22 | condition) attributes, designed for filtering and flagging during publishing.
23 | However, the
24 | props attribute is not intended to be used within a topic
25 | or document. It is provided to be used as the basis for
26 |
28 | condition attributes.
29 |
30 |
Do not use this attribute when authoring DITA topics
31 | or maps.
32 |
33 |
34 |
35 |
--------------------------------------------------------------------------------
/Authoring_Concepts/c_The_A_in_DITA.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | The A in DITA
5 | DITA provides a standardised architectural framework for creating
6 | and maintaining content.
7 |
8 | Tony
9 | Selfarchitectureopen
10 | standardinformation
11 | architectureRockley, Manning, et
12 | al
13 |
14 |
15 |
DITA can be described as an approach to information architecture. That's
16 | why there's an A for Architecture in DITA!
17 |
18 |
A great definition of architecture in the DITA context can be found in
19 | the book
20 | DITA 101:
21 | An open
22 | content standard that defines a common structure for content that promotes the
23 | consistent creation, sharing, and re-use of content.
24 |
25 |
26 |
This definition is great because it highlights the facts that:
27 |
37 |
38 |
39 |
40 |
--------------------------------------------------------------------------------
/Documentation_Process/c_Working_in_a_Team.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Unit testing in a team
5 | A process where multiple authors are working on a large repository
6 | of topics can make it difficult to manage the quality and consistency of the
7 | content.
8 | Unit testing is a technique to identify validation errors
9 | earlier in the documentation process.
10 |
11 | Tony Selfunit
12 | testingteamdocumentation
13 | processworking in a
14 | team
15 |
16 |
17 |
When a team of authors is working on the same collection of topics,
18 | particularly when the collection is very large, it is sometimes difficult to
19 | identify a problem with the build. For example, a topic referenced in the
20 | master ditamap may be invalid; finding that invalid topic in
21 | a large collection will be difficult.
22 |
23 |
Some information architects provide each author with a ditamap of that
24 | author's topics. Before the author submits the final set of topics, the ditamap
25 | must successfully and cleanly build as a unit. The author's ditamap can be
26 | discarded after testing if it is not otherwise used for publishing.
27 |
28 |
This unit testing approach allows any issues to be addressed in a
29 | smaller, quicker to build, environment.
30 |
31 |
32 |
33 |
--------------------------------------------------------------------------------
/Syntax_and_Markup/c_Single_Step_Procedure.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Single step procedure
5 | A procedure or task containing just one action should be marked-up
6 | using the normal steps/step/cmd structure.
7 |
8 | Tony Selfsteps
9 | elementstep elementsingle step
10 | procedureelementssteps
11 |
12 |
13 |
A single step procedure should still be marked up
14 | using the
15 | steps structure, rather than
16 | steps-unordered or
17 | steps-informal.
18 |
19 |
Some writers object to the default processing of something like:
20 |
because they feel the number is unwarranted or confusing.
28 |
29 |
However, the semantics of the DITA source should always be observed over
30 | any preference in output format. The output processing should be changed if the
31 | output needs to be different (in our case, represented as a bulleted item
32 | instead of a numbered item). The DITA source shouldn't be corrupted or
33 | bent to achieve a certain output result.
34 |
35 |
36 |
37 |
--------------------------------------------------------------------------------
/Syntax_and_Markup/c_Choice_Lists.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
5 | Choice lists
6 | When writing task topics, the choice list structure can be used to
7 | describe alternative step choices.
8 |
9 | Tony Selfchoice
10 | listlistschoice list in task
11 | topicelementschoiceschoicechoices
12 | elementchoice element
13 |
14 |
15 |
A choice list is a special purpose list used within
16 | step elements in task topics to indicate that the user has
17 | to choose one of several actions to complete the task.
18 |
19 |
The choice list (choices) is similar in structure to the
20 | general purpose unordered list (ul). A
21 | choices element contains one or more
22 | choice elements.
23 |
24 |
An example of a choice list being used within a step is:
25 | <step>
26 | <cmd>Place the car in gear.</cmd>
27 | <choices>
28 | <choice>For automatic gearboxes, select <uicontrol>Park</uicontrol>.</choice>
29 | <choice>For manual gearboxes, select first gear.</choice>
30 | </choices>
31 | </step>
32 |
33 |
34 |
35 |
--------------------------------------------------------------------------------
/c_DITA_Authoring_Concepts.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 | DITA authoring concepts
6 | Moving from style-based authoring to a structured authoring
7 | methodology such as DITA requires a radically different approach to writing.
8 |
9 |
10 | DITA is an open content standard that defines a
11 | common structure for content that promotes the consistent creation, sharing,
12 | and re-use of content.
13 |
14 |
15 | This section needs reorganisation, and more DITA overview
16 | content from papers, WinANT, or HATC424. (Perhaps refer to TACTICS workbook?)
17 | Some of the topics should be moved to the Literature review section of the
18 | Exegesis.
19 |
20 | Need to add an introduction topic to say that this Manual
21 | of Style isn't a replacement for the DITA Langref, but is intended to be read
22 | alongside it. Also, it is not intended to be a comprehensive guide to all DITA
23 | elements and attributes, and nor is it intended to be a DITA training manual.
24 | It is intended to be a reference when contentious issues are encountered. It
25 | documents a series of suggestions for how DITA should be implemented, and its
26 | main goal is to provide a tool for creating consistent and logical DITA
27 | semantic mark-up.
28 |
29 | Do we need a topic explaining the open source movement
30 |
31 |
32 |
33 |
34 |
--------------------------------------------------------------------------------
/Maps/c_Output_Styling.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Heading levels and ditamaps
5 | The topic hierarchy in the ditamap is used to generate heading
6 | levels and styles in page layout outputs.
7 |
8 | Tony
9 | Selfheadingslevelsheadingsstylesstylesheadingtopic
10 | hierarchyheading
11 | styles
12 |
13 |
14 |
In DITA, each topic is written as a standalone chunk of content. The
15 | style in which a topic title, for example, is eventually presented to the user
16 | is determined by the position of the topic in the relevant ditamap.
17 |
18 |
For example, if a topic called
19 | About SD Cards is located at:
20 | Camera Model 700 > Storing Pictures > Memory > About SD Cardsthen its heading style in RTF output might be
21 | Heading 4.
22 |
23 |
If that same topic is re-used in a different ditamap, located at:
24 | Taking Pictures > Storing > About SD Cardsthen its heading style in RTF output might be
25 | Heading 3. The topic is identical, but its
26 | presentation is appropriate to the output context.
27 |
28 |
And it gets better! Topic titles can be different in different ditamaps.
29 |
30 |
31 |
32 |
33 |
--------------------------------------------------------------------------------
/Topics_and_Information_Types/obsolete_c_What_if_the_Content_Model_Does_Not_Fit.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | What if a content model doesn't fit?
5 |
6 |
7 | This belongs in syntax, with a new title, such as Hacking
8 | the Content Model. File name would need changing too. May be already a topic
9 | with same purpose, so maybe merge?
10 |
11 |
12 |
14 | Rationale
15 | I was wondering if anyone knows of an extension that's been developed
16 | that allows you to add a <note> element *between* <step> elements
17 | in a DITA task. (Even if you have to wrap it in an <info> element.) There
18 | are places in our documentation where we need a cautionary statement to come
19 | before a step or a series of steps. Putting it within the previous step's
20 | element won't cut it.
21 |
22 | For example:
23 |
24 | <steps>
25 | <step><cmd>This is the first step.</cmd></step>
26 | <info><note type="warning">Here is a warning statement that
27 | needs to come before the next step.</note></info>
28 | <step><cmd>This is the next step.</cmd></step>
29 | <step><cmd>You get the point.</cmd></step>
30 | </steps>
31 |
Mike Kokic, correspondence to dita-users Yahoo group
32 |
33 |
34 |
35 |
36 |
--------------------------------------------------------------------------------
/Authoring_Concepts/c_Where_DITA_Fits_In.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Where DITA fits...
5 | DITA is technically defined as an XML application, and is
6 | therefore built on XML language standards. XML itself is based on other
7 | character representation rules. DITA can also be used in conjunction with
8 | related standards and technologies.
9 |
10 | XHTMLXMLS1000DDocBookSGMLUnicodebase
12 | content modelDITADITAframework
14 |
15 |
16 |
17 | DITA in relation to other standards and technologies
18 | Diagram:
19 | ComTech/Quadralay Presentation (Webinar), Jen Linton and Andrew
20 | VanConas
21 |
24 |
25 | Block diagram showing where DITA fits in a world of standards and
26 | technologies
27 |
28 |
29 |
30 |
31 |
--------------------------------------------------------------------------------
/Metadata_Conditional/c_Conditional_Processing_Dangers.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Conditional processing dangers
5 | Any filtering conditions that apply must still result in valid
6 | DITA mark-up.
7 |
8 | Tony
9 | Selffilteringconditional
10 | processingdangersWeb only
11 | contentprint only
12 | content
13 |
14 |
15 |
When using filtering in single-sourcing, you must be careful to ensure
16 | that a conditional processing rule doesn't result in invalid DITA. Filtering
17 | must not result in a required element being removed during processing.
18 |
19 |
For example, in the following snippet, if a condition of
20 | exclude web_only and exclude print_only was set, there would be no
21 | steps in the task, and the topic would be invalid. (The
22 | steps element requires at least one child
23 | step element.)
24 |
25 |
26 | <task id="myTopic">
27 | <title>Making a Warranty Claim</title>
28 | <taskbody>
29 | <context>...</context>
30 | <steps>
31 | <step otherprops="web_only">...</step>
32 | <step otherprops="print_only">...</step>
33 | </steps>
34 | <result>...</result>
35 | </taskbody>
36 | </task>
37 |
38 |
39 |
--------------------------------------------------------------------------------
/Metadata_Conditional/c_Managing_Metadata.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Managing metadata elements and attributes
5 | The use of metadata elements and attributes may be best managed by
6 | a Content Management System.
7 |
8 | Tony
9 | SelfmetadatamanagingCMS
10 |
11 |
12 |
When working in a topic-based, modular architecture, where metadata
13 | plays a key role, one of the major challenges for authors is managing metadata.
14 | In this respect,
15 | managing metadata means such things as ensuring consistent
16 | metadata use, using metadata for retrieval of authoring topics, enforcing
17 | business metadata rules, and effective use of conditional metadata attributes.
18 | The most effective way of managing metadata is through a
19 | Content Management System (CMS).
20 |
21 |
If a
22 | CMS is not being used, you may find that recording metadata
23 | attribute values used in a collection inside a comments area within the ditamap
24 | XML code might be helpful.
25 |
26 |
There are some DITA software tools that provide some features that
27 | leverage metadata, such as reporting on attribute values in a collection. You
28 | may find these tools useful in supplementing your authoring tool features. Two
29 | such tools are
30 | DITAinformationcenter and
31 | WinANT Echidna.
32 |
33 |
34 |
35 |
--------------------------------------------------------------------------------
/Maps/c_Hierarchical_Linking_Relationships.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
5 | Hierarchical linking relationships
6 | The hierarchical relationship of topic references in the ditamap
7 | can be used to generate links from parent topics to child topics, from child
8 | topics to parent topics, and between child topics.
9 |
10 | Tony
11 | Selfditamaphierarchygenerated
12 | linkslinksgenerated from
13 | ditamaphierarchical
14 | linksparent-child
15 | links
16 |
17 |
18 |
The hierarchy of topic references in the ditamap controls not only the
19 | sequence of topics in the output and/or the TOC, but also influences
20 | automatically-generated navigation links and generated summary content in
21 | parent topics in some output formats.
22 |
23 |
DITA permits you to adjust the basis on which the automatic navigation
24 | links are generated through the
25 | collection-type attribute of the
26 | topicref element.
27 |
28 |
Which collection type to use is dependent on the nature of the content.
29 | However, if in doubt, leave the default, which provides links to any child
30 | topics, and a link back from child to parent. This ensures that all topics in a
31 | hypertext output such as HTML can be traversed using links alone.
32 |
One of the most powerful features of DITA is the automatic generation of
19 | cross-reference links in the output. This feature allows greater content
20 | re-use, as it removes linking context from topics and moves it to the map.
21 |
22 |
Cross-reference links at the bottom of output topics are generated by
23 | hierarchical relationships defined in the ditamap, non-hierarchical
24 | relationships defined in the
25 | reltable section of the ditamap, and links defined in the
26 | related-topic section of the individual topic.
27 |
28 |
Of course, how links are generated will ultimately be up to the
29 | publishing engine you use.
30 |
31 |
The
32 | collection-type and
33 | linking attributes (of the topicref and relcell elements)
34 | allow you to fine-tune the way in which links are generated.
35 |
36 |
37 |
38 |
--------------------------------------------------------------------------------
/Syntax_and_Markup/c_Poetry_Dialogue_Text_Fragments.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Poetry,
5 |
7 | and fragments of text
8 | The
9 | lines element is used for content where the line breaks are
10 | important to the meaning of the text.
11 |
12 | Tony
13 | Selflineselementslinespoetrytext
15 | fragmentsline
16 | breakspre-formatting
17 | text
18 |
19 |
20 |
The
21 | lines element may be used to represent character
22 | ,
24 | and text fragments where the line breaks can be considered to be part of the
25 | content. A good example of the
26 | lines element is to describe a poem.
27 |
28 |
A processor will treat line-end characters within a
29 | lines element to be part of the data; normally, for most
30 | other elements, line-end characters are ignored.
31 |
32 |
The
33 | lines element is similar to the
34 | pre element in HTML.
35 |
36 |
37 |
38 |
--------------------------------------------------------------------------------
/Maps/c_Topic_Manifest.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
5 | Topic manifest
6 | Any topics referenced anywhere in the ditamap will be processed
7 | into the output publication.
8 |
9 | Tony Selftopicref
10 | elementprint
11 | attributeattributesprintmanifestpicking
12 | listditamapmap
13 |
14 |
15 |
Topics to be included in the output are referenced through
16 | topicref elements in the ditamap. The
17 | topicref elements (and
18 |
20 | of
21 | topicref) are used both in the hierarchy and the
22 | relationship table sections of the map. If a ditamap includes an embedded map
23 | (a
24 | topicref referencing a ditamap rather than a DITA topic),
25 | then topics referenced by
26 | topicref elements in the embedded map will also be
27 | included in the output.
28 |
29 |
Simplistically, any topic referenced in the ditamap will be included in
30 | the output. An exception is for topics with the
31 | topicref element's
32 | print attribute set to
33 | ; these topics will not be included in page layout
34 | outputs (such as PDF).
35 |
36 |
37 |
38 |
--------------------------------------------------------------------------------
/Metadata_Conditional/c_Filtering_Composite_Topics.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Filtering composite (ditabase) topics
5 | Care must be taken when applying conditions to composite topics,
6 | as filtering a nested topic through the
7 | topicref element will not necessarily result in the topic
8 | being excluded.
9 |
10 | Tony
11 | Selfditabasecomposite
12 | topicsfilteringcomposite (ditabase)
13 | topicsconditional processingin
14 | composite (ditabase) topics
15 |
16 |
17 |
Although you should avoid the use of composite topics in any case, there
18 | are some complications when filtering such content.
19 |
20 |
If you have a ditamap
21 | topicref element with a condition attribute pointing to a
22 | topic within a composite topic file, then excluding elements with that
23 | attribute in the build process will not result in the (nested) topic being
24 | excluded from the output, unless that (nested) topic also has the condition
25 | attribute. The processor will include the entire composite topic if any topic
26 | within that composite topic is included in the published output.
27 |
28 |
Even if the chunking feature is used to split the composite DITA topic
29 | into multiple HTML topics, for example, the entire contents of the DITA topic
30 | will be output unless condition attributes are applied within the topic.
31 |
32 |
33 |
34 |
--------------------------------------------------------------------------------
/artefact_test.ditamap:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
20 |
--------------------------------------------------------------------------------
/Maps/c_Nesting_bookmaps_Within_ditmaps.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Nesting bookmaps within ditamaps
5 | For complex collection structures, only use bookmap at the top
6 | level. Any nested maps should be ditamaps.
7 |
8 | nested
9 | ditamapsmapsnestedbookmapmap
10 | structure
11 |
12 |
13 |
You should not nest bookmaps within ditamaps, as the
14 | structure will cause confusion for both processing software and for
15 | documentation authors.
16 |
17 |
If you need to re-use content from a bookmap inside a
18 | ditamap, then a lower-level ditamap should be nested in the bookmap, and that
19 | lower level ditamap re-used in the main ditamap. In fact, except for small
20 | documents, you should aim to have the top-level bookmap contain only map
21 | references, and no topic references.
22 |
23 |
25 | Rationale
26 | Now that
28 | <bookmap has been provided, my sense is that it should be thought of as
29 | hierarchically above <map>, and this usage of referencing <bookmap>
30 | from <map> should be prohibited or at least cautioned against, not least
31 | because of the issues you're raising.
32 |
33 |
34 |
35 |
36 |
--------------------------------------------------------------------------------
/Syntax_and_Markup/c_The_systemoutput_Element.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
5 | Printouts, read-outs and other system output
6 | When a computer system, application or hardware equipment produces
7 | some output intended for reading by a user, the output is described in DITA
8 | using the
9 | systemoutput element.
10 |
11 | Tony
12 | Selfelementssystemoutputsystemoutput
13 | elementprintoutsread-outs
14 | from systems
15 |
16 |
17 |
The system output (systemoutput) element is used to
18 | describe the display or read-out from the device, application or system being
19 | documented. The
20 | systemoutput element is similar to the
21 | msgph element in that both elements describe the output
22 | from a system. The
23 | msgph element specifically describes a system message;
24 | systemoutput is less specific.
25 |
26 |
The
27 | systemoutput element should also be used when describing
28 | snippets of text from a printout from a computer application or system, such as
29 | words on the printed page.
30 |
31 |
Example:
32 | <p>Second and subsequent level numbers in a nested ordered
33 | list are typically rendered following the format of
34 | <systemoutput>1. a. I.</systemoutput>.</p>
35 |
36 |
37 |
38 |
--------------------------------------------------------------------------------
/Metadata_Conditional/c_The_status_attribute.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
5 | The
6 | status attribute
7 | The position of a topic or content element in the development life
8 | cycle is recorded in the
9 | status attribute.
10 |
11 | Tony Selfstatus
12 | attributeattributesstatusDocument
13 | Development Life Cyclelife
14 | cycleproject planning
15 |
16 |
17 |
Most DITA content elements include the
18 | status attribute. This attribute makes most sense when
19 | applied to the top-level topic element, such as
20 | concept,
21 | task and
22 | reference elements, and you can use it to record the
23 | status or progress of the information in its life cycle.
24 |
25 |
Valid values for the
26 | status attribute are:
27 |
28 |
new
29 |
30 |
changed
31 |
32 |
deleted
33 |
34 |
unchanged
35 |
36 |
37 |
38 |
Some authoring tools may highlight topics with different
39 | status attribute values in different ways, and some
40 | publishing tools may also take advantage of the attribute values.
41 |
42 |
43 |
44 |
--------------------------------------------------------------------------------
/Cross_Referencing/c_The_importance_Attribute_and_Related_Links.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 | The
6 | importance attribute and related links
7 | Setting the
8 | importance attribute of a
9 | link element in the
10 | related-links section in a task topic to
11 | will result in the link appearing in the
12 | pre-requisites section of the topic.
13 |
14 | Tony
15 | Selfattributesimportanceimportance
16 | attributeelementsprereqprereq
17 | element
18 |
19 |
20 |
When writing a task topic, you will often include a pre-requisites
21 | (prereq) element. In some cases, pre-requisites for the task
22 | will include other procedures, described in separate topics. Logically, these
23 | pre-requisite task topics should be linked to in the
24 | prereq block.
25 |
26 |
Rather than including a link to an associated topic in an
27 | xref element in the
28 | prereq block, you should create a
29 | link element in the
30 | related-links section, and then set the
31 | importance attribute of the
32 | link element to
33 | . In typical output processing, this will result
34 | in the link being rendered at the end of the
35 | prereq block.
36 |
37 |
38 |
39 |
--------------------------------------------------------------------------------
/Documentation_Process/c_Structured_Authoring_Process.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Structured authoring documentation stages
5 | The documentation process within a DITA workflow can be separated
6 | into stages of building, associating, and publishing.
7 |
8 | Tony
9 | Selfdocumentation
10 | processstages of the documentation
11 | process
12 |
13 |
14 |
The process of creating, producing and delivering a document in DITA's
15 | modular, structured authoring environment can be divided into three different
16 | stages:
17 |
18 |
19 |
Building
20 |
21 |
Building is the authoring process, normally undertaken by a writer.
22 |
23 |
24 |
25 |
26 |
Associating
27 |
28 |
Associating is the drawing together of the topics into collections
29 | (such as books and Web sites), normally undertaken by the
30 | information architects. A bundle of independent topics
31 | only becomes a book when the topics are associated, or linked, to each other
32 | through the ditamap.
33 |
34 |
35 |
36 |
Publishing
37 |
38 |
Publishing is the generation of the output collections of topics.
39 | The output might be a Word document, a PDF document, a CHM file, a collection
40 | of HTML files, or even a collection of XML files.
41 |
42 |
43 |
44 |
45 | Building and associating are independent, and are not
46 | sequential stages.
47 |
48 |
49 |
50 |
--------------------------------------------------------------------------------
/Metadata_Conditional/c_Styling_Issues_with_Conditions.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Styling Issues for Conditional Text
5 |
6 |
7 | This topic isn't really required; out of scope.
8 |
9 |
10 |
12 | Rationale
13 |
15 |
I'd suggest that our approach to style policies should consist of
16 | selectors and properties. In essence, a policy file should be able to attach
17 | any style or layout property (including an exclude or hide property) to any
18 | content fragment. The selectors should be CSS-like matches on inherited class,
19 | instance identifier, token value, or nesting of the above. The goal should be
20 | to put policy decisions in the hands of the broad audience that wouldn't be
21 | successful with XSLT. (Because XSLT is always available as a general fallback,
22 | style policies can provide a purely declarative set of selectors and properties
23 | rather than executable flow and expressions.) To produce books from bookmaps,
24 | the set of properties will need properties like page break and so on. A bit
25 | more on the thought:
26 | http://www.oasis-open.org/apps/org/workgroup/dita/email/archives/200409/msg00022.html
27 |
28 |
Paul's note below highlights the convergence of this approach with
29 | DITA conditional values, which also provide a system of selectors and
30 | properties. In a perfect world, existing DITA values files would remain valid
31 | instances of the more general style policies format. A transform might be
32 | acceptable.
33 |
Referring to the US Government's
18 | Open Government Directive:
19 |
21 |
22 |
23 |
Firstly, all Web
24 | content must be analyzed to discover what content the agency has and where it
25 | is stored.
26 |
27 |
Secondly, it must be
28 | enhanced to improve on the condition of the content
29 |
30 |
Thirdly, it must be
31 | standardized to ensure content can be re-used
32 |
33 |
Fourthly, it needs to
34 | be findable, by being located within the Information Architecture in a suitable
35 | repository
36 |
37 |
And lastly, it needs
38 | to be monitored and maintained in real time against the organization's quality
39 | policies to ensure the quality standards that have been established continue to
40 | be met
41 |
42 |
43 |
44 |
45 |
46 |
47 |
48 |
--------------------------------------------------------------------------------
/Maps/c_Generated_Relationship_Links.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Generated relationship links
5 | Cross-reference links based on the relationships defined in the
6 | hierarchy and reltable sections of the ditamap can be automatically generated
7 | and added to the bottom of output topics, in both hypertext and paged media
8 | outputs. Most publishing tools support this DITA feature.
9 |
10 | Tony Selfgenerated
11 | linksautomatically-generated
12 | linksrelationship
13 | linksreltableexamplesgenerated
14 | relationship links
15 |
16 |
17 |
When a ditamap is
18 | processed (transformed into a reading format), particularly
19 | to a hypertext format, cross-referencing links can be automatically generated.
20 | For example, the samples following show some automatically generated related
21 | topics links.
22 |
23 |
24 | Generated links in HTML output
27 | Collection Links in HTML output
28 |
29 |
30 |
31 | Generated links in PDF output
34 | Collection links in PDF output
35 |
36 |
37 |
38 |
39 |
--------------------------------------------------------------------------------
/Maps/c_Link_Text_for_Relationship_Tables.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Link text for
5 | reltable related topic links
6 | To control the text displayed in links automatically-generated
7 | from the relationship table, a
8 | linktext element must be added to the
9 | topicmeta for the
10 | topicref.
11 |
12 | Tony Selflinktext
13 | elementrelationship
14 | tablelinktextnavtitletopicmetaelementslinktextnavtitle
15 | attributeattributesnavtitle
16 |
17 |
18 |
By default, the link text used for generated links will be the title of
19 | the target topic.
20 |
21 |
If you want the link generated by a reltable to have a different title
22 | to the title of the linked topic itself, you may think the technique would be
23 | to use a
24 | navtitle attribute in the
25 | topicref element. However, that doesn't work!
26 |
27 |
The technique to use is to add a
28 | topicmeta element to the
29 | topicref, and include a
30 | linktext element containing the name of the link text. The
31 | following example shows the technique.
32 |
33 | <reltable>
34 | ...
35 | <topicref href="foo.xml">
36 | <topicmeta>
37 | <linktext>Replacement text</linktext>
38 | </topicmeta>
39 | </topicref>
40 | ...
41 | </reltable>
42 |
43 |
44 |
45 |
46 |
--------------------------------------------------------------------------------
/Metadata_Conditional/c_Filtering_ditamaps.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
5 | Filtering ditamaps
6 | When filtering a nested ditamap, you should apply the condition
7 | attribute to the reference (topicref or
8 | mapref element) to the nested ditamap, rather than to the
9 | map element.
10 |
11 | Tony Selfmapref
12 | elementtopicref elementmap
13 | elementconditional
14 | processingmetadata
15 | attributesselect
16 | attributescondition
17 | attributesfilteringditamapselementsmapmapreftopicref
18 |
19 |
20 |
It is possible in DITA, and often good practice, to have nested
21 | ditamaps. Although it does depend on circumstance, it is generally better
22 | practice to apply conditions to the
23 | topicref or
24 | mapref element, rather than the
25 | map element of the nested ditamap.
26 |
27 |
The reason for this, and a point that should always be considered when
28 | deciding on a filtering strategy, is the reduced processing load during
29 | generation of the output. If the processor has to read in a topic, or a nested
30 | map, only to find it's not needed in the current build because of the filtering
31 | metadata, it is an inefficient model. It is much better for the exclusion to be
32 | notified to the processor before having to load the file.
33 |
34 |
35 |
36 |
--------------------------------------------------------------------------------
/Syntax_and_Markup/c_Code_Blocks.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 | Identifying programming code
6 | The codeblock and codeph elements are used to identify code
7 | snippets.
8 |
9 | Tony Selfcodeph
10 | elementcodeblock
11 | elementelementscodephcodeblocksample
12 | codeprogramming codemark-up
13 | languagesmarking up
14 |
15 |
16 |
Examples of programming, scripting, or mark-up language code are marked
17 | up using the code phrase (codeph) and code block
18 | (codeblock) elements. As the element names suggest, code phrase
19 | is used when the code sample occurs inline within a paragraph or other block
20 | element, while code block is used when the code is more than one line long, and
21 | is a block in its own right.
22 |
23 |
Code block elements can be nested inside a paragraph (or other block
24 | element).
25 |
26 |
If you have text that introduces the codeblock and more text that
27 | immediately explains the code, you can use a structure such as in the following
28 | example:
29 | <p>
30 | If you display debugging information, such as in:
31 | <codeblock>
32 | debugText = app.name & app.ver
33 | debug.print("Value is " & debugText)
34 | </codeblock>
35 | you must launch the application in debugging mode.
36 | </p>
37 |
38 |
39 |
Line breaks can be used inside
40 | codeblock elements.
41 |
42 |
43 |
44 |
--------------------------------------------------------------------------------
/Topics_and_Information_Types/c_Avoiding_Links_in_Topics.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Avoiding linking in topics
5 | A topic with an embedded link is bound to the target of that link.
6 | If the target topic is not included in the same output, the link is not
7 | relevant (and will appear as a broken link in the output). Links should
8 | therefore be removed from the topic to the ditamap; the map being the place
9 | where context is stored.
10 |
11 | Tony
12 | Selfreltablerelationship
13 | tablecontextseparation of content
14 | and
15 | formlinksembeddedlinksgeneratedhyperlinksembedded
16 | links
17 |
18 |
19 |
For content to be truly separated from format, structure, context and
20 | delivery, there can be no links embedded within the topic content, because
21 | links contain
22 | context.
23 |
24 |
Embedded links create a dependency upon the linked topics; the topic can
25 | only make sense if the target topics for each of the links it are delivered
26 | alongside it. If a target topic is not included in the same collection as the
27 | topic, then the link will be broken.
28 |
29 |
DITA includes automatic linking mechanisms based on relationships
30 | established in
31 | relationship table (reltable) within the ditamap. Because
32 | the ditamap defines the collection of topics to be delivered as a publication,
33 | this is a more logical place for links between topics in the collection to be
34 | defined.
35 |
36 |
37 |
38 |
--------------------------------------------------------------------------------
/Authoring_Concepts/c_DITA_Features.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | DITA features
5 | DITA incorporates features designed to improve the quality and
6 | efficiency of documentation.
7 |
8 | Tony
9 | SelfDITAfeatures
10 |
11 |
12 |
47 |
48 |
49 |
50 |
--------------------------------------------------------------------------------
/Syntax_and_Markup/c_Multiple_Titles_in_a_Section.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
5 | Titles
6 | A title is not the same as a heading. A topic, a figure, a table
7 | and a section should each have only one title.
8 |
9 | Tony
10 | Selfsectionsheadingstitle
11 | elementsection elementtopic
12 | elementfig elementtable
13 | elementtitlesfigureselementssectiontitletopicfigtable
14 |
15 |
16 |
The intention of the DITA approach is that the elements most commonly
17 | cross-referenced, such as topics, sections, figures and tables, should have a
18 | title. In some cases, the title element is mandatory.
19 |
20 |
Even though the DITA DTD may technically allow
21 | multiple titles to exist in one section, you should limit your section content
22 | to one title. Do not use titles as though they are headings. If you need
23 | multiple headings in a section, chances are that you really need multiple
24 | sections.
25 |
26 |
28 | Rationale
29 | Multiple
31 | titles are allowed by the *DTD* but not by the language of the specification.
32 |
33 |
34 |
35 |
36 |
--------------------------------------------------------------------------------
/Authoring_Concepts/c_Modularity.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Modularity
5 | DITA enables modular document development. Not only can topics be
6 | re-used, but any group of topics or elements can be treated as a modular
7 | document component.
8 |
9 | Tony
10 | Selfmodulardocumentsarchitecturemodularassemblycontent
11 | assemblytopic-based
12 | authoring
13 |
14 |
15 |
Modularity is the technique of building large complex things in smaller,
16 | self-contained pieces. Modular furniture is a good example of modularity in
17 | practice. Instead of being one large piece, a modular couch may be four pieces
18 | that can be arranged in different ways to form different couch configurations.
19 |
20 |
Creation of a manual can also be
21 | .
23 | Instead of being constructed as one piece, a large manual may be designed as a
24 | collection of different modules, and those modules can be arranged into
25 | different configurations to create different manuals. Modular manuals are
26 | easier to maintain, and can be produced more efficiently. A ditamap referencing
27 | a group of topics can be embedded within another ditamap, just as a set of
28 | elements within a single topic can be re-used in many different topics.
29 |
30 |
XML technologies (such as
31 | XPath) make modularity technically easy to implement. DITA
32 | can take advantage of such complementary XML technologies.
33 |
34 |
35 |
36 |
--------------------------------------------------------------------------------
/Syntax_and_Markup/c_Images_within_Steps.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Images within steps
5 | Images that support a procedural step can be included within a
6 | stepxmp or an
7 | info element.
8 |
9 | Tony Selfimage
10 | elementelementsimagestepxmpinfoinfo
11 | elementstepxmp
12 | elementimageswithin
13 | steps
14 |
15 |
16 |
Images can be used to support documentation of task steps, as
17 | image elements within the
18 | cmd element, or as
19 | image elements within the
20 | stepxmp or
21 | info elements.
22 |
23 |
24 | Task topic
25 | steps structure showing
26 | image within a
27 | step
30 | Screen capture of task topic in DITA editor showing semantic
31 | elements
32 |
33 |
34 |
35 | Typical rendered result of steps mark-up
40 | Screen capture showing the rendered result of steps mark-up
41 |
42 |
43 |
44 |
45 |
--------------------------------------------------------------------------------
/Syntax_and_Markup/c_Types_of_Tables.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
5 | Types of tables
6 | There are two different types of general purpose tables in DITA,
7 | table and
8 | simpletable, both of which are based on the CALS table model
9 | standard.
10 |
11 | Tony
12 | Selftablestypes
13 | oftable
14 | elementsimpletable
15 | elementelementstablesimpletable
16 |
17 |
18 |
The two types of general purpose tables in base DITA are:
19 |
20 |
21 |
table
22 |
23 |
The standard
24 | table structure is designed for complex, tabular
25 | information, where a title can be applied to the table. The
26 | table can also be easily cross-referenced, and a
27 | List of Tables generated during the publishing process.
28 |
29 |
30 |
31 |
simpletable
32 |
33 |
The
34 | simpletable structure is a much simplified design,
35 | with no provision for titles or cross-referencing. It is used for informal,
36 | simple tabular information.
37 |
38 |
39 |
40 |
41 |
Both types of table are based on the CALS standard table structure; the
42 | table structure of HTML is based on the same standard.
43 |
44 |
DITA also includes some special purpose tables, including relationship
45 | tables (used in ditamaps for cross-reference metadata) and
46 | properties tables (used in reference topics).
47 |
48 |
49 |
50 |
--------------------------------------------------------------------------------
/Topics_and_Information_Types/c_Specialising_Information_Types.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
5 |
7 | information types
8 |
10 | information types provide a topic architecture that closely matches the
11 | structure of your content.
12 |
13 | Tony Selfinformation
15 | typescontent
17 | model
18 |
19 |
20 |
DITA is designed around topic
21 | .
23 | Many types of content will not suit the structure of the DITA base information
24 | types of concept, task and reference, but new information types, with a
25 | structure to exactly suit the nature of the content, can be evolved from the
26 | base types.
27 |
28 |
A
29 |
31 | information type is always derived from another DITA information type, so that
32 | you only need to define how your information type is different from what it is
33 | based on.
34 |
35 |
36 |
37 |
--------------------------------------------------------------------------------
/Syntax_and_Markup/c_Use_of_Class_Attribute.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Use of
5 | class attribute
6 | The
7 | class attribute is used in
8 | ,
10 | and should not be set by a DITA author. The
11 | class attribute should not be confused with the
12 | outputclass attribute.
13 |
14 | Tony
15 | Selfinheritanceclass
16 | attributeoutputclass
17 | attributeattributesclassoutputclass
19 |
20 |
21 |
All DITA elements have a
22 | class attribute, but as a DITA author, you should never
23 | change this attribute. In fact, most DITA editors will hide it from you. The
24 | DITA
25 | class attribute is not the same as the HTML
26 | class attribute. (DITA's
27 | outputclass attribute is the closest equivalent to HTML
28 | class.)
29 |
30 |
All DITA based processors use the class attribute to determine how an
31 | element should be processed, rather than by using the element name itself. This
32 | is because
33 |
35 | may make the element name unfamiliar to the processor, but the
36 | class will indicate the element's inheritance, and
37 | therefore how it should be handled.
38 |
39 |
40 |
41 |
--------------------------------------------------------------------------------
/Metadata_Conditional/c_The_source_Element.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 | The
6 | source element
7 | When a topic is based on information from another resource,
8 | details of that related resource can be stored in the
9 | source metadata element in the topic
10 | prolog section.
11 |
12 | Tony SelfDublin Core Metadata Element
14 | Setsource
15 | elementDublin Core
16 | Metadataelementssourceattributeshrefhref
17 | attribute
18 |
19 |
20 |
The
21 | source element in the topic
22 | prolog section is used to nominate the name and/or
23 | location of information from which the topic was drawn or based. It is based on
24 | the Dublin Core Metadata Initiative
25 | property. The location of the resource is recorded
26 | in the
27 | source element's
28 | href attribute.
29 |
30 |
For example, if a topic was based on figures published in a Department
31 | of Transport report, the source element may be coded as:
32 | <source href="http://www.transport.gov.au/design/adr_online.aspx">
33 | Australian Design Rules
34 | </source>
35 |
36 |
When published to an HTML-based output format, the address in the
37 | href attribute of the
38 | source element are included in the Dublin Core
39 | DC.source metadata in the head section of the HTML page.
40 |
41 |
42 |
43 |
--------------------------------------------------------------------------------
/Syntax_and_Markup/c_Required_and_Optional_Steps.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
5 | Required and optional steps
6 | The
7 | importance attribute of a step is used to indicate whether
8 | an element is optional or mandatory.
9 |
10 | Tony Selfstep
11 | elementsubstep elementimportance
12 | attributeattributesimportanceelementsstepsubstepmandatory
13 | stepsoptional steps
14 |
15 |
16 |
The
17 | step and
18 | substep elements have an optional
19 | importance attribute, which has two valid values:
20 | and
21 | . The attribute is used to indicate whether the
22 | step is optional (within a set of mandatory steps), or required (within a set
23 | of optional steps). The
24 | setting is more commonly used than
25 | .
26 |
27 |
During processing to a reading format, steps with an
28 | importance attribute are typically rendered with an
29 | Optional: or
30 | Required: prefix.
31 |
32 |
33 | Typical rendering of step with importance attribute
34 | set
38 | Screen capture showing typical rendering of step with importance
39 | attribute set
40 |
41 |
42 |
43 |
44 |
--------------------------------------------------------------------------------
/Syntax_and_Markup/c_Parameter_Lists.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
5 | Parameter lists
6 | When documenting programming functions and interfaces, the
7 | parameter list can be used to explain parameters passed between applications
8 | and functions.
9 |
10 | Tony Selfparameter
11 | listslistsparameter
12 | listelementsparmlplentryptpdparml
13 | elementplentry elementpt
14 | entrypd entry
15 |
16 |
17 |
Parameter lists are a special purpose list used to describe parameters
18 | in a program or application programming interface. The parameter list
19 | (parml) is similar in structure to the general purpose
20 | definition list (dl).
21 |
22 |
A parameter list (parml) element contains one or more
23 | parameter list entry (plentry) elements, each typically
24 | containing a parameter name or term (pt) and a parameter
25 | description (pd) element.
26 |
27 |
An example of a parameter list being used to explain some programming code is:
28 | <codeblock>callHelp(hFileName, contentId)</codeblock>
29 | <p>where
30 | <parml>
31 | <plentry>
32 | <pt>hFileName</pt>
33 | <pd>is the relative path to the Help file</pd>
34 | </plentry>
35 | <plentry>
36 | <pt>contentId</pt>
37 | <pd>is the context ID of the topic to display</pd>
38 | </plentry>
39 | </parml>
40 | </p>
41 |
42 |
43 |
44 |
--------------------------------------------------------------------------------
/artefact_graphics.ditamap:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
15 |
--------------------------------------------------------------------------------
/Cross_Referencing/c_Scope_Attribute.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Linking in a new window
5 | The
6 | scope attribute of the cross-reference (xref)
7 | is used to nominate whether the target topic, file or other resource is
8 | external to the DITA source topics. Some publishing tools (such as the DITA
9 | Open Toolkit) will generate cross-references with an
10 | external scope attribute as hyperlinks that will
11 | open the target in a new window.
12 |
13 | Tony Selfxref
14 | elementelementsxrefscope
15 | attributeattributesscopecross-referenceswindowsopen
16 | link targets in
17 | newlinks
18 |
19 |
20 |
If a topic being referenced in an
21 | xref is external to the document content, the
22 | xref element's
23 | scope attribute should be set to
24 | external to semantically identify this
25 | relationship.
26 |
27 |
If you want a cross-referenced Web or external
28 | resource to open in a new window, code the
29 | xref as in the example:
30 | <xref href="..../somefile.html" format="html" scope="external" />
31 |
32 | Opening external target resources in a new window is a processing
33 | function, and is therefore dependent upon the publishing tool used and its
34 | configuration. This
35 |
37 | is not part of the DITA standard itself.
38 |
39 |
40 |
41 |
--------------------------------------------------------------------------------
/Syntax_and_Markup/c_Definition_Lists_vs_Tables.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
5 | Definition lists versus tables
6 | Definition lists should be used for structuring terms and their
7 | corresponding definitions, rather than an alternative table structure.
8 |
9 | Tony
10 | Selfelementsdltabledefinition
11 | liststablesdefinitionsterms
12 |
13 |
14 |
Some information structures, particularly terms with corresponding
15 | definitions, can be marked up as either definition lists or tables.
16 |
17 |
If the content is indeed made up of terms and
18 | definitions, the definition list (dl) structure should be used.
19 | For content not so clearly identifiable as terms and definitions, but where
20 | there is a two part structure made up of short phrase and a longer explanation
21 | of the phrase, the simpler definition list structure should always be preferred
22 | over the table structure.
23 |
24 |
Definition lists are particularly suited to defining or explaining
25 | components or items.
26 |
27 |
28 | The difference between tables and definition lists
32 | Screen captures showing the difference between tables and
33 | definition lists in PDF output
34 |
35 |
36 |
Definition lists are rendered with fewer potential complications than
37 | tables, and are semantically stronger than the more generic table structure.
38 |
39 |
40 |
41 |
--------------------------------------------------------------------------------
/Syntax_and_Markup/c_List_of_Domains.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Element domains
5 | Elements in DITA are arranged into domains for
6 |
8 | purposes and technical reasons.
9 |
10 | Tony
11 | Selfdomainsmark-up
12 | domainselement
13 | domainsDTDschemaXSD
14 |
15 |
16 |
The base DITA elements are grouped into
17 | domains. You can see this clearly in the
18 | .
20 |
21 |
22 |
The DITA element mark-up domains are:
23 |
24 |
programming
25 |
26 |
user interface
27 |
28 |
software
29 |
30 |
utilities
31 |
32 |
metadata
33 |
34 |
typographic
35 |
36 |
37 |
38 |
Different sets of elements are intended for use when documenting
39 | different types of things. The software domain, for example, contains the
40 | elements designed to semantically describe software characteristics.
41 |
42 |
The element domains are technically
43 |
45 | into different DTD or XSD schema modules.
46 |
47 |
48 |
49 |
--------------------------------------------------------------------------------
/Syntax_and_Markup/c_Footnotes.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
6 | Footnotes
7 | The footnote (fn) element is used to nominate
8 | supplementary information that is not appropriate to be included in the flow of
9 | the content.
10 |
11 | Tony Selffn
12 | elementelementsfnfootnotes
13 |
14 |
15 |
A footnote is usually seen as being specific to page layout output
16 | formats, so marking up text as a footnote could be viewed as recording
17 | presentational information within content; something that DITA tries to avoid.
18 |
19 |
However, footnotes can also be considered as semantic identifiers for
20 | supplementary information that doesn't belong inline in the text. The footnote
21 | content is not critical to understanding the content, but provides extra
22 | information that may be useful to some readers.
23 |
24 |
The footnote (fn) element is typically rendered in the
25 | output as a number in the flow of the text and the footnote content at the
26 | bottom of the page or topic. The footnote number is automatically calculated
27 | during the publishing process. In hypertext output formats, the inline footnote
28 | reference number may be hyperlinked to the footnote at the bottom of the topic.
29 | Some publishing tools may display the footnote content in a popup window (in
30 | some hypertext output formats).
31 |
32 |
An example of a footnote (fn) element is:
33 | <p>Always wear a seatbelt.
34 | <fn>Some jurisdictions allow a medical exemption from wearing a seat belt
35 | in exceptional circumstances.</fn>
36 | </p>
37 |
38 |
39 |
40 |
41 |
42 |
--------------------------------------------------------------------------------
/Topics_and_Information_Types/obsolete_c_FAQ_Topics.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Example: FAQ (or Question and Answer) as Specialised Information
5 | Type
6 |
7 |
8 |
9 |
11 | Rationale
12 | ejosejulie wrote: > In the troubleshooting section of the
13 | document, I want to design the > page with all the questions in the
14 | beginning that is linked to the > answers in the same page. Please explain
15 | how to do it? The low-tech way is to use <xref> for the questions at the
16 | beginning. Each one points to the Question+Answer which comes later in the
17 | topic. I'd probably use <section> for a Question+Answer, <title>
18 | for the question, and <p> for the answer. <concept id="thistopic">
19 | <title>Troubleshooting</title> <conbody> <sl>
20 | <sli><xref href="#thistopic/q1">What is
21 | foo?</xref></sli> <!-- More questions --> </sl>
22 | <section id="q1"> <title>What is foo?</title> <p>foo is
23 | a word used as a placeholder by geeks.</p> </section> <!-- More
24 | answers. --> </conbody> </concept>
25 |
26 |
Source: Deborah Pickett, Yahoo! DITA Users Group
27 |
28 |
29 | Turn this into a worked example...
30 |
31 |
32 |
Follow up from Michael Priestley
33 |
34 | Or a reference topic, with nested reference topic children - put the
35 | <related-links> to the children in the container reference topic. Same
36 | idea as others, but moving from xref and section to link and topic, which I
37 | tend to prefer for architectural reasons (like ability to integrate with
38 | map-based linking at some later point)
39 |
40 |
41 |
42 |
43 |
--------------------------------------------------------------------------------
/Syntax_and_Markup/c_Program_Script_and_Routine_Names.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
6 | Program, script and routine names
7 | Program, routine, API and script names are identified using the
8 | cmdname and
9 | apiname elements.
10 |
11 | elementscmdnameapinameapiname
12 | elementcmdname elementprogram
13 | names
14 |
15 |
16 |
The DITA programming domain is a set of mark-up elements used for
17 | documenting programming languages and their use. The software domain is a
18 | similar set of elements used for documenting software applications.
19 |
20 |
To identify a program or script name within an
21 | end-user's use of a software application, you should use the
22 | cmdname (command name) element (from the software domain).
23 |
24 |
25 |
To identify a function, API or sub-routine within
26 | documentation aimed at programmers, you should use the
27 | apiname (API name) element (from the programming domain).
28 |
29 |
30 | Referring to a program name
31 | <step><cmd>After resetting the computer, run
32 | the <cmdname>syscheck</cmdname> program to verify
33 | the recovery.</cmd></step>
34 |
35 |
36 | Referring to a sub-routine or function
37 | <p>You can link the <apiname>print</apiname> sub-routine to
38 | the button's <apiname>onclick</apiname> event.</p>
39 |
40 |
41 |
42 |
--------------------------------------------------------------------------------
/Topics_and_Information_Types/c_Topic_Proto.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
5 | Topic (proto information type)
6 | The
7 | topic information type is the
8 | ancestor of all DITA information types, and is used mainly as
9 | the basis for
10 |
12 | new information types.
13 |
14 | Tony Selfinformation
15 | typestopictopic information
16 | typeproto information
17 | type
18 |
19 |
20 |
All DITA information types have
21 | evolved from the
22 | topic
23 | proto information type. The
24 | topic type is
25 | weakly information typed, or even
26 | untyped, in that it has generic rather than semantic
27 | elements. It is designed as a starting point for
28 | ,
30 | and not for use as a container for structured, semantic content.
31 |
32 |
Apart from for
33 | ,
35 | the other purpose of the untyped topic information type is to store legacy
36 | information during the migration of style-based documents to DITA. For example,
37 | when migrating untyped HTML content to DITA, it can be useful to first convert
38 | HTML topics to untyped DITA topic, for later conversion to correctly typed DITA
39 | information types such as concept, task and reference.
40 |
41 |
The root element of an untyped topic is
42 | topic.
43 |
44 |
45 |
46 |
--------------------------------------------------------------------------------
/conref/conref_source_metadata.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Metadata Conref Source
5 | This topic contains only metadata for re-use in other topics.
6 |
7 | Tony SelfHyperWrite Pty
9 | Ltdspecialisationspecialisation
12 | elementsgeneralisationorganisingorganising re-usespecialisedorganisation of
18 | elementsdomain
20 | specialisationstructural
22 | specialisationspecialisationpros and
24 | consspecialisationrules
26 | ofspecialisationtypes
28 | ofdomainstructuraldialoguelocalising graphicslocalisationlabellinglocalisationgraphics
34 |
35 |
36 |
37 |
--------------------------------------------------------------------------------
/conref/en-US_conref_source_metadata.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Metadata Conref Source
5 | This topic contains only metadata for re-use in other topics.
6 |
7 | Tony SelfHyperWrite Pty
9 | Ltdspecializationspecialization
12 | elementsgeneralizationorganizingorganizing re-usespecializedorganization of
18 | elementsdomain
20 | specializationstructural
22 | specializationspecializationpros and
24 | consspecializationrules
26 | ofspecializationtypes
28 | ofdomainstructuraldialoglocalizing graphicslocalizationlabelinglocalizationgraphics
34 |
35 |
36 |
37 |
--------------------------------------------------------------------------------
/Content_Reuse/obsolete_c_Transclusion.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Transclusion
5 |
6 |
An old OASIS News story from 2002, titled
7 | The Holy Grail of Content Reuse: IBM's DITA XML,
8 | summarises conrefs well, and also introduces
9 | the idea of
10 | transclusion.
11 |
12 |
13 |
DITA design focuses upon the "topic" as a conceptual unit of
14 | authoring. Larger documents can be created by aggregating topic units. A
15 | "content referencing" (conref) mechanism may be used at the mark-up level to
16 | combine several topics into a single document, or to share content among
17 | topics.
18 |
19 |
The DITA design has a unified content reuse mechanism by which an
20 | element can replace itself with the content of a like element elsewhere, either
21 | in the current topic or in a separate topic that shares the same content
22 | models. The distinction between reusable content and reusing content, which is
23 | enshrined in the file entity scheme, disappears: Any element with an ID, in any
24 | DITA topic, is reusable by conref.
25 |
26 |
DITA's conref 'transclusion' mechanism is similar to the SGML conref
27 | mechanism, which uses an empty element as a reference to a complete element
28 | elsewhere. However, DITA requires that at least a minimal content model for the
29 | referencing element be present, and performs checks during processing to ensure
30 | that the replacement element is valid in its new context. This mechanism goes
31 | beyond standard XInclude, in that content can be incorporated only when it is
32 | equivalent: If there is a mismatch between the reusing and reused element
33 | types, the conref is not resolved. It also goes beyond standard entity reuse,
34 | in that it allows the reused content to be in a valid XML file with a DTD. The
35 | net result is that reused content gets validated at authoring time, rather than
36 | at reuse time, catching problems at their source.
37 |
38 |
39 |
40 |
41 |
--------------------------------------------------------------------------------
/Cross_Referencing/c_Cross_References_in_Titles.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Cross-references in titles
5 | You should not use cross-reference elements within topic titles.
6 |
7 | Tony
8 | Selfcross-referencesin
9 | titletitle
10 | elementelementstitlexreftopic
11 | titleexemplartip
12 |
13 |
14 |
The
15 | title element cannot directly contain an
16 | xref element, primarily because titles are used in many
17 | different presentational contexts, some of which do not support child elements.
18 | For example, the
19 | title element of a DITA topic may become the
20 | title element in the
21 | head section of an output XHTML file, which must be plain
22 | text. Likewise, the title element of a DITA topic may be used as the basis for
23 | link text in its parent topic.
24 |
25 |
Including child elements in titles therefore reduces the opportunities
26 | for re-use, increases the risk of a transformation error caused by
27 | mis-interpretation of the mark-up, and complicates what should be a simple
28 | semantic element.
29 |
30 |
However, it
31 | is technically possible to embed
32 | xref or other child elements within a
33 | title element by nesting them within an (allowed)
34 | ph element. While the
35 | title element cannot contain
36 | xref elements, it
37 | can contain
38 | ph elements, and
39 | ph elements can contain
40 | xref elements.
41 |
55 |
56 |
57 |
--------------------------------------------------------------------------------
/Maps/c_The_topicref_Element.dita:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 | The
6 | topicref element
7 | The basic building block of ditamap files is the topic reference
8 | (topicref) element.
9 |
10 | topicref
11 | elementelementstopicref
12 |
13 |
14 |
Topic references nominate the topic or other resource to be included in
15 | the collection. They are similar in function to a cross-reference
16 | (xref) element in topic content.
17 |
18 |
The
19 | topicref element is used for the hierarchical section of
20 | the ditamap and the relationship table section.
21 |
22 |
Resources that a
23 | topicref element can reference include DITA topics within
24 | the collection, (embedded) ditamaps, DITA topics external to the collection,
25 | external files, and Internet resources.
26 |
27 |
The main attributes of the
28 | topicref element are the
29 | href,
30 | scope,
31 | format, and
32 | type attributes.
33 |
34 |
36 | Future Enhancements
37 |
39 |
A topicref element may not reference elements nested inside a topic,
40 | but it may be used to reference elements inside of a map. For example, this is
41 | a valid reference on a topicref:
42 |
I would like to thank the people who helped me bring
8 |
10 | project to fruition.
11 |
12 |
I owe a huge debt of gratitude to Scott Prentice, who spent a great deal
13 | of time and effort on a technical review of the content.
14 |
15 |
I give special thanks to Kris Eberlein, Gary Kilsen, Sarah O'Keefe, and
16 | Kathy Betts, who inspired, supported and/or encouraged me in this project. I
17 | dips me lid to John Hunt, who first got me involved in the DITA
18 | world. To the Yahoo! DITA Users Group community, and especially those such as
19 | Deb Pickett who patiently and diligently answer the questions of others, thank
20 | you!
21 |
22 |
Thank you Mike Hughes and Jen Linton for permission to reproduce some
23 | illustrations and examples in this Guide.
24 |
25 |
Thanks also to Fiona Self for undertaking the copy editing task, and to
26 | Nolwenn Kerzreho for reviewing the content. Su-Laine Yeo and the JustSystems
27 | team deserve my gratitude for their support for the project. It would also be
28 | remiss of me not to mention the help of Matthew Ellison, Suku Sinnappan, Helen
29 | Self, and Joe Welinske. To anyone whose acknowledgement I've overlooked, I
30 | sincerely apologise!
31 |
32 |
A project of this time and nature takes a lot of time and emotional
33 | energy, and I give thanks to my wife Penny Bradley for helping me every step of
34 | the way.
35 |
36 |
It is also important to me that I acknowledge the efforts of the OASIS
37 | DITA Technical Committee and the OASIS DITA Adoption Technical Committee, whose
38 | members generously donate countless hours of their considerable experience and
39 | expertise to the technical communication community.
40 |