DITA for Solo Writers

Unknown

Description

DITA for Solo Writers
Lone-DITA
2007 Louise Kasemeier2 | Lone-DITA DITA Tutorial | TOC
Contents
Introduction.............................................................................................................4
Benefits of Switching to DITA................................................................................5
Getting Started........................................................................................................6
Related Technologies...............................................................................................................6
DITA Toolkit Introduction........................................................................................8
Additional Components Needed to Use the DITA Toolkit.........................................................8
Creating DITA Files...............................................................................................10
XML Editing Tools...................................................................................................................11
Creating DITA Content with XMLMind....................................................................................11
Tutorial Introduction.............................................................................................13
Tutorial Requirements............................................................................................................13
How To Install the Toolkit.................................... ...

Sujets

• Extensible Stylesheet Language Transformations
• Tutoriel
• Recipe for Hate
• Document Type Definition
• Maple
• Fork

Informations

• Publié par: Asso
• Nombre de lectures: 182
• Langue: English

Extrait

DITA for Solo Writers

Lone-DITA 2007 Louise Kasemeier

2 | Lone-DITA DITA Tutorial |

Contents

T OC

Introduction.............................................................................................................4 Benefits of Switching to DITA................................................................................5 Getting Started........................................................................................................6 Related Technologies...............................................................................................................6 DITA Toolkit Introduction........................................................................................8 Additional Components Needed to Use the DITA Toolkit.........................................................8 Creating DITA Files...............................................................................................10 XML Editing Tools...................................................................................................................11 Creating DITA Content with XMLMind....................................................................................11 Tutorial Introduction.............................................................................................13 Tutorial Requirements............................................................................................................13 How To Install the Toolkit........................................................................................................13 How To Test the Toolkit Installation..............................................................................14 How To Install the Idiom FO Plug-in.......................................................................................15 How To Test Idiom FO Output......................................................................................15 Planning a Content Model......................................................................................................16 Creating Content....................................................................................................................17 Creating Tasks.............................................................................................................18 Creating Concepts.......................................................................................................23 Creating Reference Topics..........................................................................................26 Complete the Content..................................................................................................29 Keywords and Indexes...........................................................................................................30 Add Index Entries........................................................................................................31 DITA Map Files.......................................................................................................................31 Collection Types...........................................................................................................33 Titles in Content Pages and Navigation.......................................................................34 Relationship Tables......................................................................................................35 How to Create a Map File............................................................................................36 How To Create a Relationship Table............................................................................37 Building Output.......................................................................................................................38 XML Catalogs..............................................................................................................38 ANT Build Files............................................................................................................40 How To Build HTML Output.........................................................................................40 How To Build PDF Output............................................................................................41 Styles and Formatting............................................................................................................42 Customizing XHTML and HTML Help Output..............................................................43 Customizing Idiom FO (pdf2) Output...........................................................................49 Specializing Information Types...............................................................................................54 Designing the Recipe Topic Type.................................................................................55 How To Create the Recipe Module..............................................................................56

Lone-DITA DITA Tutorial | TOC |3

How to Create the Element Declarations in recipe.mod..............................................57 How to Declare Attributes in recipe.mod.....................................................................58 How To Create the Recipe Shell DTD.........................................................................59 Specializing Domains and Attributes......................................................................................61 How To Create the Cooking Domain Entity File...........................................................62 How To Create the Cooking Domain Definition Module...............................................62 How To Create the Extended Attribute Domain Entity File..........................................63 Integrate Domains and Attributes into the Shell DTD..................................................63 XML Catalogs..............................................................................................................64 Configuring XMLMind for Specialized Information Types............................................65 Using DITAVAL Files to Filter and Flag...................................................................................65 How To Create a Ditaval File.......................................................................................66 Content Inclusion....................................................................................................................68 How To Use Conref......................................................................................................68 Troubleshooting....................................................................................................70 XMLMind Tips and Tricks.....................................................................................71 Glossary................................................................................................................72

4| Lone-DITA DITA Tutorial | Introduction

Introduction

There are many introductory documents concerning DITA in general. Good places to start are listed at the end of this topic. Moving from traditional unstructured documentation, such asFramemakerorWordnioater dcuutemtnoduc str to using DITA involves a shift in how you think about the information in your documents as well as an ability and desire to learn new technologies. In some cases, structured documentation will offer little or no benefit to a small team or solo writer. But there is an increasing need to provide modular documentation, documentation that is customized to the needs a particular user or group of users and documentation in a variety of online and paper formats. These requirements can be particularly difficult for small teams to meet. The initial investment in time and effort is repaid by a much more streamlined method for producing useful, targeted documentation for users. These documents are the results of my own efforts to implement a DITA solution for a solo writer with a budget of virtually nothing. It can be done! I should make it clear that I am not recommending that everyone should forgo the expert advice of a professional consultant (I would have used one if I could!). But if, like me, that is not an option for you, then I hope that this guide will be useful.

LoneATT turoD-TI AID |5TI A

Single Source -> MultipleDITA allows you to produce documentation in multiple formats from a single set Formatsof XML source files. The current open source toolkit provides support for HTML, HTML Help, JAVA Help, Eclipse Help and PDF output. DITA eliminates the need to maintain multiple version of the same documents; a process which can be both error-prone and time consuming. Content can be reused within and across topics and output formats, making updating documents easier and reducing development time. DITA conditional processing provides a mechanism to produce multiple versions of a document from the same source. Documents can be created for spefic audience types, platforms, product versions and more, without needing to maintain multiple sets of content. Formatting is applied according to your style guidelines by stylesheets, freeing the writer to concentrate on writing content. The DITA DTD assists you in maintaining information that is consistently and logically formatted and structured across a document set. DITA specialization architecture allows you to use a vocabulary for your XML that is meaningful to other writers.

Benefits of Switching to DITA

Separation of Content and Formatting Consistency Vocabulary

Reuse Content Multiple Versions

eB | laio stifenchitSwf  Dtog in

6 | Lone-DITA DITA Tutorail | Getting Sta

Getting Started

rted

So how do you go fromDITA Open Toolkitto multiple documents in multiple formats? Hereand blank page is the basic workflow: 1.Create your content in XML files. The XML tags you use will conform to the specification in the DITA DTD provided in theDITA Open Toolkit. 2.which topics will be included in your output document, the order in which theyCreate a map file defining will appear and their hierarchy. 3.layout and formatting of each output type (PDF, HTML etc) or modifyCreate stylesheets to define the those provided with theDITA Open Toolkit. 4.Create a filter file if required. A filter file specifies that blocks of content or groups of map entries marked with a particular attribute/value pair will be excluded or flagged. I.e exclude all elements with audience='administrators'. 5.ANT and a build file that specifies which DITA map file and filter file to use, which output directoryUsing to create the docs in and which 'transtype' (output format - PDF, HTML, CHM etc) to use, transform and process/compile the documents. This workflow assumes that you have already completed planning tasks which include: � Plan your content model. This is the process of determining how you will decide which topics or blocks of content will be included in your document sets and how content will be re-used. Topics and smaller chunks of content can be re-used throughout a DITA documentation set through DITA maps used to assemble topics and through the content inclusion mechanism. This mechanism allows you to include a re-usable block of content in the same or across different topics. You can also take the filtered re-use approcah. This method uses selection attributes to select which content should be included or excluded. For example, the audience attribute could be used to exclude all content that is specifically for expert users. � Plan how you will manage your content. You will need to implement some method of keeping track of your topics and your metadata schemes. I use a combination of file system and a simpleMS Accessdatabase to keep track of my content but you may want to implement your own method, such as a spreadsheet. Specialized content management software is extremely expensive for small team/solo writers. � Set up your stylesheets according to your own requirements. This may be very simple, such as editing the CSS files for HTML and CHM outputs or it could be more complicated and entail actually modifying the XSL files. � Create any specializations that you need for topic types, map types, domains and attributes.

Related Technologies The technologies that you will need to learn in order to produce DITA documentation depend to some extent on the types of output that you want to produce. If you are producing HTML or CHM files, chances are that you are already familiar with those technologies. If you are producing PDF files, it is by no means likely that you are already familiar with XSL-FO since this is not necessary to produce PDFs fromFramemakeror similar applications. For each technology listed below, I have included a link to the appropriateW3schoolstutorial. These tutorials provide a good introduction and starting point for beginners. Technologies that anyone embarking on a DITA project should familiarize themselves with thoroughly are: � XML: XML tags are used to structure and tag your content. XML is the fundamental technology in DITA and you should have a good understanding of it.