31
Structured Authoring in FrameMaker

Structured Authoring in FrameMaker - Novell · Adobe FrameMaker lets writers use either structured authoring or unstructured authoring to produce documents. 3 © Novell, Inc

Embed Size (px)

Citation preview

Structured Authoring in FrameMaker

© Novell, Inc. All rights reserved.2

In structured authoring, writers mark each unit of text according to its purpose, using a standard set of tags or elements that identify such things as a paragraph, a section, a table, or an inline element such as a cross-reference. Each element has a specific place in a hierarchy of elements, and the structure can be viewed and manipulated in various ways.

In unstructured authoring, a writer composes the text, then applies the formatting either manually or by using styles.

Adobe FrameMaker lets writers use either structured authoring or unstructured authoring to produce documents.

© Novell, Inc. All rights reserved.3

DocSys uses a subset of the elements that are defined in the DocBook DTD, which is a widely accepted document type definition for software documentation.

Novell product documentation uses a customized version of FrameMaker as its structured authoring tool. This toolset is called DocSys.

© Novell, Inc. All rights reserved.4

The DTD provides a list of elements and the basic rules for using them. It's similar to using styles, but in a more formalized, predictable, and viewable way.

© Novell, Inc. All rights reserved.5

In practice, it's not necessary for a writer to be acquainted with all of the details of the DTD and its rules. Instead, writers use the authoring tool interface to view the document structure and the list of valid elements. In addition, the authoring tool provides different ways to automate and simplify how the DTD is used.Within FrameMaker, DocSys provides several ways for you to view your document and its structure.

© Novell, Inc. All rights reserved.6

For example, you can use a simple WYSIWYG view of the text.

© Novell, Inc. All rights reserved.7

You can add element boundaries to the WSIWYG view.

© Novell, Inc. All rights reserved.8

Or, you can view the element boundaries as tags.

© Novell, Inc. All rights reserved.9

You can display a tree view of the document structure.

© Novell, Inc. All rights reserved.10

And you can use an Element Catalog to select an element to add to the structure. The catalog displays all of the elements that are valid where your cursor is located.

© Novell, Inc. All rights reserved.11

Most writers prefer a combined view that displays the document, the Structure View, and the Element Catalog. This screen shot shows them on one monitor, but you can display them on two monitors if you prefer.

© Novell, Inc. All rights reserved.12

Let's look at how DocSys helps you with some common authoring tasks:

• Creating a book.• Creating a table of contents.• Moving existing chapters or adding new chapters to a book.• Adding a subordinate table of contents within a chapter.• Moving content to another place within the document.• Creating a table with a title.• Renaming a file on disk without causing problems in the book structure.• Exchanging information with an incompatible application.• Producing different output formats without manual reformatting or using a

third-party application.• Exporting different parts of a master document to different target documents.• Copying text from a master location to many different places, then

automatically updating all the copies when you change the source.

© Novell, Inc. All rights reserved.13

Task 1: You want to create a book. DocSys provides different elements for all of the substructures in a book, including the front matter, preface, chapters, and appendixes. You create individual files, then you assemble them into a master file called a Book file. For example, to create the front matter of a book, you select BookInfo as the top-level element in the file.

1. When you begin, both the document and the structure are blank, because you haven't added anything yet.

2. To create the front matter, you double-click BookInfoin the Element Catalog.

© Novell, Inc. All rights reserved.14

DocSys inserts a BookInfo element that is prepopulated with the required title page and boilerplate text for all front matter files.

1. For the title page, you customize the text for the book name, the product name, the version, and the date.

2. For the Legal Notices page, all you need to customize is the copyright date.

© Novell, Inc. All rights reserved.15

After you create the files for the book, you assemble them into the Book file.

1. Once again, the structureis empty when you start.

2. You use the Add menuto navigate to the files youwant, then add them toyour book.

3. The book is populated with the files you selected.

© Novell, Inc. All rights reserved.16

Task 2: You want to create a Table of Contents and make sure that page and chapter numbers are correct and current.

After you create a book, you run anUpdate process to automatically numberheadings, create page footers and page numbers, create cross-references, and create the table of contents.

© Novell, Inc. All rights reserved.17

Task 3: You want to rearrange chapters in your book, or add a new chapter.

1. If you want to change the order of chapters within the book, you simply drag a chapter to its new location, then run Update to correct all of the numbering and cross-references throughout the book.

2. If you want to add another chapter, you use the Add Files menu to add a single file, drag the file to the place where you want it in the book, and run Update to correct the numbering and cross-references

© Novell, Inc. All rights reserved.18

Task 4: At the beginning of each chapter of your book, you want to create a list of all of the first-level headings within the chapter.

1. You want to insert a subordinatetable of contents here.

2. Simply insert aSubToc elementat the correct location in thestructure.

3. DocSys automatically generates and inserts the linked list of headings.

4. If you change or relocate any headings, DocSys automatically updates the SubToc.

© Novell, Inc. All rights reserved.19

Task 5: You've created a heading with several subheadings, tables, and graphics, and you need to move all of it to another location in the document.

Section 5.1 is four pages long, with a SubToc, four subheadings, and several lists and graphics. However, you want it to be Section 5.7.

© Novell, Inc. All rights reserved.20

1. Select Section 5.1 in the Structure View. This selects the top-level element and all of its child elements. Selecting the section in the Structure View also selects it in the document view.

2. Drag the selected element to its new location, or cut it and paste it.

© Novell, Inc. All rights reserved.21

DocSys automatically performs several actions when you relocate the section:

• It renumbers the top-level heading.

• It regenerates any cross-references (such as the ones in the SubToc) so they have correct section numbers and page numbers.

• It renumbers all of the subordinate headings.

• It renumbers figures and tables as necessary.

© Novell, Inc. All rights reserved.22

Task 6: You need to create a table with a title, but you're not sure what elements and sub-elements are necessary.

1. Place your cursor where you want the table to be.

2. Double-click Table in the Element Catalog.

© Novell, Inc. All rights reserved.23

1.The table is inserted, along with all of the necessary child elements, ready for you to begin typing text.

2. Red boxes or red dotted lines in the Structure View indicate incomplete or invalid content.

3. To make the document valid, all you need to do is save it, which creates the ID numbers for the table and its individual rows.

© Novell, Inc. All rights reserved.24

Task 7: You want to rename a file that is already in the book, and you want the filename in the book and the filename on disk to be synchronized.

Double-click the filename to make it editable, type the new name, then click OK in the confirmation dialog box. The file is renamed in the book file and on disk.

© Novell, Inc. All rights reserved.25

Task 8: You want to exchange files with an application that doesn't natively allow saving to a common format.

You can use the XML output from Frame as a bridge to an incompatible application, especially if the application uses the same DTD that DocSys uses.

For example, Novell writers can exchange documents with SUSE writers, who use the Vi text editor. Text is exported from each separate authoring system into XML, then imported into the other authoring system.

StructuredFrameMaker

DocBook DTD

Vitext editor

DocBook DTDXML

© Novell, Inc. All rights reserved.26

Task 9: You want to produce different output formats without manual reformatting or using third-party applications.

With DocSys, you can easily produce many different kinds of documentation from a single source:

WebHelp

Man Pages

PDF Text

HTML Help

© Novell, Inc. All rights reserved.27

Task 10: You want to export different parts of the source document to different target documents.

Master Document - Introductory text about widgets. - Text about Widget A - Text about Widget B

Book for Widget A - Introductory text - Text about Widget A

Book for Widget B - Introductory text - Text about Widget B

In DocSys, this is called profiling, and you can use it to direct output from one master document to several different sources, in whatever combinations you want.

© Novell, Inc. All rights reserved.28

Task 11: You want to copy text from a master location to many different places, then automatically update all of the copies when you change the source.

In DocSys, this is called sharing.

Hello World Hello World

Hello World

Hello World

Hello Worlds Hello Worlds

Hello Worlds

Hello Worlds

© Novell, Inc. All rights reserved.29

All in all, using DocSys has many advantages:

• The consistent structure lets you spend less time thinking about formatting and more time writing.

• DocSys automates many of the time-consuming manual tasks of an unstructured authoring environment.

• You can easily rearrange the structure without a lot of reformatting.• The structure ensures an identical appearance for each document.• You can create multiple outputs from a single source.

Unpublished Work of Novell, Inc. All Rights Reserved.This work is an unpublished work and contains confidential, proprietary, and trade secret information of Novell, Inc. Access to this work is restricted to Novell employees who have a need to know to perform tasks within the scope of their assignments. No part of this work may be practiced, performed, copied, distributed, revised, modified, translated, abridged, condensed, expanded, collected, or adapted without the prior written consent of Novell, Inc. Any use or exploitation of this work without authorization could subject the perpetrator to criminal and civil liability.

General DisclaimerThis document is not to be construed as a promise by any participating company to develop, deliver, or market a product. It is not a commitment to deliver any material, code, or functionality, and should not be relied upon in making purchasing decisions. Novell, Inc. makes no representations or warranties with respect to the contents of this document, and specifically disclaims any express or implied warranties of merchantability or fitness for any particular purpose. The development, release, and timing of features or functionality described for Novell products remains at the sole discretion of Novell. Further, Novell, Inc. reserves the right to revise this document and to make changes to its content, at any time, without obligation to notify any person or entity of such revisions or changes. All Novell marks referenced in this presentation are trademarks or registered trademarks of Novell, Inc. in the United States and other countries. All third-party trademarks are the property of their respective owners.