BOOK STRUCTURE VIEWER

What is BSV?

Book Structure Viewer (BSV) is a tool for performing global operations on multi-file DITA and IBMIDDOC documents.

BSV provides some extra functionality not found in the IDWB. For example, the Epic editor has only a limited concept of a book -- it is basically a single-file editor. BSV, on the other hand, "sees" a DITA or IBMIDDOC document as a complete entity, and allows you to view and edit it as such.

Imagine, for example, that you have a document consisting of 1000+ files, many of which are 500 - 600 lines long. You want to find all instances of a specific text string and change some, but not all, to a different value. Furthermore, the order in which the instances occur is significant, so you want to examine each one in the order in which it occurs in the book. You want to do this quickly. For a job like this, you need BSV!

The following sections describe some of the things you can do with BSV.

Functions available in both DITA and IBMIDDOC documents

Viewer functions

Explore the structure of a DITA or IBMIDDOC document. Opening a .ditamap file gives you a tree view of its navigable files. Similarly, opening an .IDD file gives you a tree view of its embedded files (including common files). You can expand or contract branches of the tree.
Clicking on a text file file in the tree view immediately displays the file in a separate edit window. This has all the usual edit functions. (Readonly files are never overwritten.)

Clicking on an .EPS or .GIF file in the tree view displays the graphic in your chosen graphics-viewer program (for example, GhostView (for EPS files) or Windows Paint (for GIF files)).
Go to a specified line number in a particular file. This is useful for debugging IDWB error messages that invariably quote a line number.

Search and replace functions

Do a fast, interactive, sequential, global search (LFIND) of the whole document.
Do a fast, interactive, sequential, global search-and-replace (LCHANGE). All the usual "Y/N", "skip file", "replace all", "quit" functions are supported.
Use regular expressions in a global search or global search-and-replace. As of Version 8, regular expressions are fully supported.

IDs functions

List all the IDs in your book, or in a specific file. The listings include full information about each ID -- e.g. the type of element it occurs on, the element's title or caption, and the name of the file the ID occurs in.
Sort the IDs in various ways, filter them, and print or save the listings. For example, if another writer needs to create hypertext links to information in your book, you can give them a printed listing of IDs/division titles, sorted sequentially by file.
Run a "single-click" check for duplicate IDs.

Cross-reference functions

List all the cross-references (xrefs) in your book, or in a specific file. The listings show the REFID itself, the file it's in, the element-type of the target (division, fig, table, etc.), the title or caption of the target, and the target filename. If the target doesn't exist, the xref is listed as UNRESOLVED.
Filter, print, and save the listings. For example, you can show just the xrefs that are UNRESOLVED.
Run a "single-click" check for unresolved cross-references.

Revision bar functions

Remove all revbars from a book, or from a specific file, in seconds.
Change all revbar identifiers in a book, or in a file, to a single value ("flatten").
List revbar IDs and see which files each occurs in; filter lists by revbar ID and/or file-type (R/O, R/W, ALL).
Selectively remove or flatten revbars.

Trademark functions

List all trademarks, all registered trademarks, or all non-registered trademarks in a book (i.e. all phrases that have been marked as trademarks).
Filter the list to remove duplicates, showing only unique trademarks.
Run a "single-click" job to remove all trademark tagging from an entire document.

Configuration functions

You can create and save multiple configurations, and switch between them at the click of a button. For example, you can save multiple filepaths, enabling you to open books that embed files from different sets of directories. Other preferences you can specify include:

The search path to be used to find embedded files. Note:In DITA documents, BSV automatically looks for referenced files in all descendent directories of the .mapfile/.maplist directory.
The default filetype (.DITAMAP, .MAPLIST, or .IDD) to be used to filter files in the File Open dialog.
Whether to permit manual changes during global search-and-replace operations.

DITA-specific functions

Topics functions

List the navigable topics referenced from a .ditamap or .maplist file. Only navigable topics are listed, and inherited attributes (such as 'toc=no') are supported. Information about each topic-reference includes the topic-type (topic, concept, task, or reference), navtitle, href, numeric "level" in the navigation tree, and name of the topic file. The IDWB algorithms are used to find the values of attributes such as navtitle.
Filter the listings by topic-type and level, and print or save them.
Display information about the topic file referenced by a topicref: e.g. its full filename, title, type, ID, navtitle, and searchtitle; the topic's parent XML node; its child XML nodes.
Display the XML content of the topic, its parent node, or any of its child nodes in a separate window.

XML function

Validate the XML content of each referenced topic file against the relevant DTD, as the map file is loaded.

Links functions

List all the links in a document, or in a specific file. The listings show: the link ID, the source file in which the link occurs, the element-type of the target (division, table, fig, etc.), the title or caption (if any) of the target element, and the target book.
Run a "single-click" check for unresolved links.

Configuration function

Whether to validate each referenced DITA topic file against the appropriate DTD when a map file is loaded.

IBMIDDOC-specific functions

Divisions functions

List all the divisions in your book, or in a specific file. The listings include full information about each division -- e.g. division-level, ID, title, name of the file it occurs in, and whether it is classified as "task", "concept", or "reference"-style information (or none).
Filter the divisions in various ways, and print or save the listings. For example, you can list all the division 2s that don't have IDs; or all the Parts, division 1 and 2s that are classified as "concept" information.

Links functions

List all the inter-book links in your book, or in a specific file. The listings show: the link ID, the link text, the source file in which the link occurs, the element-type of the target (division, table, fig, etc.), and the target book.
Run a "single-click" check for undefined links.

Configuration functions

Whether to show entity (.ENT) files in the file tree view.
Whether to show graphics (.EPS and .GIF) files in the file tree view.
The programs to be used to display graphics (.EPS and .GIF) files.
The name of an optional exit program to be used, instead of BSV's usual interactive dialog box, during global search-and-replace operations.

User-written global change program

Run a user-written LCHANGE "exit program" instead of BSV's usual interactive dialog box during search-and-replace operations. You can use a simple REXX (or VBScript or JavaScript) script to program complex replacement operations.
A sample exit program written in VBScript, sampleLCExitProg.vbs, is provided in the BSV installation directory.

Any changes made to your source files are entirely the responsibility of the provider of the exit program!

Classification functions

Categorize the information in your book as "concept", "task", or "reference".
Choose which division-levels you want to classify -- e.g. Parts, division 1s, 2s, 3s or all.
Classify a single file, or the whole book (you can stop at any point - changes up to that point are saved). Changes are reversible.

Classification is done from drop-down lists, by adding class attributes to divisions. Full information about each division is displayed.

The advantages of classifying from BSV are that you can quickly and easily identify the division-levels you want to classify (e.g. div 2s); that the correct tagging is entered automatically; and that only "approved" values can be entered -- the values in the lists.

Back to Home page