| T.R | Title | User | Personal
Name | Date | Lines |
|---|
| 64.1 | 16-JAN-89 Baselevel | CLOSET::UTT | | Wed Jan 18 1989 10:48 | 81 |
| ****************************************************************************
LIMITED DISTRIBUTION
****************************************************************************
A new baselevel of the online bookbuilding tools for the DECwindows Bookreader
are available. To read books built with these tools, you must be running
DECwindows Field Test 2 Update or later (SDC version) software. Note that this
software is bundled with VMS V5.1 software: the savesets for this software,
printable files of the documentation, and the announcement memo are available
in:
VMSKITS::SYS$KITS:[VMS051...]
If you are running FT2 or earlier versions update) of DECwindows, the
bookbuilding tools are incompatible with that version.
In addition, to use these tools you must be running the SDC versions of VAX
DOCUMENT 1.1 and the internal 1.1 kit. The V1.1 kit is available in:
VAXUUM::KITS_:[DOCUMENT.V11]DOC011 (savesets A through D)
The internal kit is in:
VAXUUM::KITS_:[DOCUMENT.V11]DOCINT011 (savesets A and B)
These kits have been formally announced in Note 2.5 of the DOCUMENT notes
conference. You should refer to that note for additional information. Note
3.5 announces the availability of DOCUMENT V1.1 documentation.
You should also install the local kit announced in Note 9.3 of the
DOCUMENT notes file.
To install the bookbuilding tools you must restore the following saveset:
VAXUUM::KITS_:[DOCUMENT.V11]CUP$ONLINE_TOOLS.SAV
The following command line restores the saveset to your existing DOC$TOOLS
tree:
$ BACKUP CUP$ONLINE_TOOLS.SAV/SAV/SELECT=[DOC$TOOLS...] -
$_ dev:[DOC$TOOLS...]/NEW_VERSION
For details on coding SDML source files and generating online books, see
"Coding Documentation Source Files for the DECwindows Bookreader"
(16-JAN-89; this is a new version for this baselevel).
VAXUUM::KITS_:[DOCUMENT.V11]WRITER_GUIDELINES.PS
WRITER_GUIDELINES.DECW$BOOK (online version)
WRITER_GUIDELINES.DECW$BOOKSHELF (bookshelf
file for online version)
You should read this document carefully before processing your books for
the Bookreader.
Before processing your files for the Bookreader, process them for normal
hardcopy output to ensure that there are no coding problems with the files.
Make sure that any W-level errors are fixed before processing your files for
online output. In addition, please process your files using the /LIST/KEEP
qualifiers to the DOCUMENT command so that, if there is a problem, a listing
file and the interim files will be available to aid debugging.
Problems in building books, and questions and comments about the tools, should
be reported via a new notes conference set up for this purpose on VAXUUM:
ONLINE_BOOKBUILDING.
Known problems:
1. File names must be less than 30 characters.
2. Master indexes are not supported.
3. In a few cases, the text formatter has run out of memory while processing
books. These cases invariably involve very large documents with very large
numbers of tables and/or very large code examples. This problem is being
investigated.
If you have any problems copying files or restoring the saveset, please
let me know.
Mary
|
| 64.2 | March 20 Baselevel | CLOSET::UTT | | Mon Mar 20 1989 15:51 | 246 |
|
NEW ONLINE BOOKBUILDING TOOLS
A new baselevel of the online bookbuilding tools for the DECwin-
dows Bookreader is available. To read books built with these
tools, you must be running DECwindows Field Test 2 Update or
later (SDC version) software. Note that this software is bundled
with VMS V5.1 software: the savesets for this software, print-
able files of the documentation, and the announcement memo are
available in:
VMSKITS::SYS$KITS:[VMS051...]
If you are running FT2 or earlier versions update) of DECwin-
dows, the bookbuilding tools are incompatible with that version.
In addition, to use these tools you must be running the SDC
versions of VAX DOCUMENT 1.1 and the internal 1.1 kit. The V1.1
kit is available in:
VAXUUM::KITS_:[DOCUMENT.V11]DOC011 (savesets A through D)
The internal kit is in:
VAXUUM::KITS_:[DOCUMENT.V11]DOCINT011 (savesets A and B)
These kits have been formally announced in Note 2.5 of the
DOCUMENT notes conference. You should refer to that note for
additional information. Note 3.5 announces the availability of
DOCUMENT V1.1 documentation.
You should also install the local kit announced in Note 9.3 of
the DOCUMENT notes file.
To install the bookbuilding tools you must restore the following
saveset:
VAXUUM::KITS_:[DOCUMENT.V11]CUP$ONLINE_TOOLS.SAV
The following command line restores the saveset to your existing
DOC$TOOLS tree:
$ BACKUP CUP$ONLINE_TOOLS.SAV/SAV/SELECT=[DOC$TOOLS...] -
$_ dev:[DOC$TOOLS...]/NEW_VERSION
1
After the saveset is successfully restored, alter DOC$DESIGNS.DAT
and DOC$DESTINATIONS.DAT in DOC$LOCAL_FORMATS:, as follows:
o Edit DOC$DESIGNS.DAT to remove the current ONLINE doctype
definition. Include the ONLINE family definition from ONLINE_
DESIGN.DAT at the end of DOC$DESIGNS.DAT (doctype families
must be defined after all single-entry doctypes are defined).
o If you installed an earlier version of the online book-
building tools, you don't have to do anything with the
DOC$DESTINATIONS.DAT file.
If this is the first installation of the tools on this sys-
tem, APPEND BOOKREADER_DESTINATION.DAT to DOC$DESTINATIONS.DAT
in DOC$LOCAL_FORMATS.
If there is no DOC$DESTINATIONS.DAT in DOC$LOCAL_FORMATS,
RENAME BOOKREADER_DESTINATION.DAT to DOC$DESTINATIONS.DAT.
NOTE
You must be running VAX DOCUMENT on a VMS V5.0 system: the
online device converter does not run on earlier versions
of VMS.
1 New Features
The most significant new feature is the addition of a new hand-
book doctype and the creation of an ONLINE family of doctypes.
1.1 ONLINE Family of Doctypes
This baselevel includes support for a new doctype based on
the CUP_HANDBOOK doctype. There is now, therefore, an ONLINE
family of doctypes: ONLINE.REFERENCE and ONLINE.HANDBOOK. ON-
LINE.REFERENCE is the same as the previous ONLINE doctype. ON-
LINE.HANDBOOK includes supported for the <UNNUMBERED_HEADS>
tag and special support for syntax diagrams and other features
required for layered products documentation.
2
The command line is either:
$ DOCUMENT/CONTENTS/INDEX file-name ONLINE.REFERENCE BOOKREADER
or
$ DOCUMENT/CONTENTS/INDEX file-name ONLINE.HANDBOOK BOOKREADER
1.2 VOILA Keyword
The VOILA keyword is no longer supported in <FIGURE_FILE> tags.
1.3 <REFERENCE> Tags in Part Page Titles
Previous baselevels did not properly format part page titles
when <REFERENCE> tags were used, as documented in the VAX DOC-
UMENT User Manual. This has been fixed and those tags now work
correctly in part page titles.
1.4 Messages and Glossaries
The support for messages and glossaries has been refined some-
what based on experience with the VMS Messages Manual and Master
Glossary.
1.5 Online Popup Checking
The tag translator now checks for matching <ONLINE_POPUP>
/<ENDONLINE_POPUP> tags.
2 Known problems
1. File names must be less than 30 characters.
2. Master indexes are not supported.
3
3. In a few cases, the text formatter has run out of memory
while processing books. These cases invariably involve very
large documents with very large numbers of informal tables
and/or very large informal code examples. This problem is
being investigated. However, making such tables and examples
formal generally fixes the problem.
4. Extension tags are no longer recognized, except as no-ops.
Writing groups found that the font change used in the pre-
vious baselevel to flag extensions was not sufficiently vi-
sually distinctive. Support for extensions has been dropped
until a Bookreader enhancement can be implemented.
5. Problem in coding headers (including <FIGURE>, <TABLE>, and
<EXAMPLE> tags): In your source file, if you break the header
tag's arguments after the backslash, it will introduce a
carriage return that creates problems for online processing.
Either code the header tag all on one line, or break the line
before the backslash. For example:
Do NOT do this:
<HEAD1>(Imagine this Is a Very Long Title\<RET>
long_title)
Do this instead:
<HEAD1>(Imagine this Is a Very Long Title\long_title)<RET>
Or this:
<HEAD1>(Imagine this Is a Very Long<RET>
Title\long_title)
6. Until a future release of VAX DOCUMENT, other (hardcopy) doc-
types will not recognize the BOOKREADER keyword in <FIGURE_
FILE>, <ICON_FILE>, and <MARGIN_ICON> tags. Hardcopy doctypes
also will not recognize the <ONLINE_POPUP> and <EXTENSION>
tags.
4
To work around this limitation, the saveset which distributes
the current version of the online bookbuilding tools places a
file in DOC$LOCAL_FORMATS, called CUP$ONLINE_DEFS.GDX, that
you should include with the /SYMBOLS qualifier when you build
hardcopy books. For example:
$ DOCUMENT filename VMSREF LN03-
_$/SYMBOLS=DOC$LOCAL_FORMATS:CUP$ONLINE_DEFS.GDX
Writers in CUP/ZK, CUP/UKm, and other sites which use the
VMS_BOOKNAMES file (CUP$VMS_V50_BOOKNAMES.SDML) when they
build their books, should note that this destination is
included in that file. (The definitions in that file will
not prevent online books from building properly.)
5
|
| 64.3 | Release notes to the release notes... | VAXUUM::UTT | | Thu Mar 30 1989 20:09 | 22 |
| A couple of corrections to the previous notice about the March 20
baselevel:
1. The VMS and DECwindows software is on node VMSKIT (not VMSKIT*S*).
2. I accidentally omitted the pointer to 'Coding Documentation Source
Files for the DECwindows Bookreader':
VAXUUM::KITS_:[DOCUMENT.V11]WRITER_GUIDELINES.*
(Note that the LN03 version is missing the Bookreader interface
graphic.)
3. The notice states that ONLINE.HANDBOOK supports <UNNUMBERED_HEADS>.
This is not the case for this baselevel.
Apologies,
Mary
|
| 64.4 | Corrected Announcement of 19-April baselevel | NAVIGO::GRANT | I've saved $1896.00 since I quit smoking. | Fri Apr 21 1989 15:14 | 16 |
|
The latest ONLINE TOOLS saveset (19 April 1989 Baselevel) is now available.
See notes 64.2 and 64.3 for instructions and other information.
The save-set is located in:
VAXUUM::KITS_:[DOCUMENT.T12]CUP$ONLINE_TOOLS_T12.SAV
The differences that users will notice between the last release and this
release are minimal.
Please note that you must be running VAX DOCUMENT Version T1.2 and the internal
kit. Refer to the VAX DOCUMENT notes conference, topic 2.LAST for T1.2
installation information.
Wayne
|
| 64.5 | | CLOSET::UTT | | Wed May 03 1989 10:11 | 10 |
| It was brought to my attention yesterday that the T1.2 saveset puts 2
files in DOC$STANDARD_FORMATS that are older than the T1.2 versions of
these files. The files are TAG$SOFTWARE.STT and TAG$S_HANDBOOK.STT. I
do not believe there are substantial differences between the files;
however, you may want to delete the versions from the online saveset
and retain the newer versions (dated March 6, 1989).
Sorry for the inconvenience.
Mary
|
| 64.6 | Math Font Patch for Version T1.2 | NAVIGO::GRANT | I've saved $1906.00 since I quit smoking. | Fri May 05 1989 14:58 | 20 |
| In response to a problem reported in note 121, we are providing a
patch to the math fonts for the Online Bookbuilding Tools, Version T1.2.
If you are using Version V1.1 of the Online Bookbuilding Tools, this
patch is *NOT* required.
To install the patch, take the following steps:
1. Copy the saveset from:
VAXUUM::KITS_:[DOCUMENT.T12]FONT_PATCH.SAV
2. Restore the saveset:
BACKUP FONT_PATCH.SAV/SAVE DOC$ROOT:[000000...]*.*
Sorry for any inconvenience,
Wayne
|
| 64.7 | June baselevel of online tools | VAXUUM::UTT | | Tue Jun 20 1989 13:35 | 153 |
|
1 Location of Bookreader Software and Bookbuilding Tools
A new baselevel of the online bookbuilding tools for the DECwin-
dows Bookreader is available. To read books built with these
tools, you must be running DECwindows V1.0 (SDC version) or
later software. Note that this software is bundled with VMS V5.1
software: the savesets for this software, printable files of the
documentation, and the announcement memo are available in:
VMSKIT::SYS$KITS:[VMS051...]
In addition, to use these tools you must be running the SDC
versions of VAX DOCUMENT 1.2 and the internal 1.2 kit. The V1.2
kit is available in:
VAXUUM::KITS_:[DOCUMENT.V12.SOFTWARE]DOC012
(savesets A through D)
The internal kit is in:
VAXUUM::KITS_:[DOCUMENT.V12.SOFTWARE]DOCINT012
(savesets A and B)
These kits have been formally announced in Note 2.10 of the
DOCUMENT notes conference. You should refer to that note for
additional information.
To install the bookbuilding tools you must restore the following
saveset:
VAXUUM::KITS_:[DOCUMENT.V12.SOFTWARE]CUP$ONLINE_TOOLS.SAV
The following command line restores the saveset to your existing
DOC$TOOLS tree:
$ BACKUP CUP$ONLINE_TOOLS.SAV/SAV/SELECT=[DOC$TOOLS...] -
$_ dev:[DOC$TOOLS...]/NEW_VERSION
NOTE
You must be running VAX DOCUMENT on a VMS V5.0 system: the
online device converter does not run on earlier versions
of VMS.
2 For More Information
For details on coding SDML source files and generating online
books, see Coding Documentation Source Files for the DECwindows
Bookreader (June 19, 1989>; this is a new version for this
baselevel).
VAXUUM::KITS_:[DOCUMENT.V12.BOOKS]WRITER_GUIDELINES.PS
WRITER_GUIDELINES.LN03
WRITER_GUIDELINES.DECW$BOOK (online version)
WRITER_GUIDELINES.DECW$BOOKSHELF (bookshelf
file for online version)
(The graphics files are missing from the LN03 version.)
NOTE
You should read this document carefully before processing
your books for the Bookreader.
Before processing your files for the Bookreader, process them
for normal hardcopy output to ensure that there are no coding
problems with the files. Make sure that any errors are fixed
before processing your files for online output. In addition,
please process your files using the /LIST/KEEP qualifiers to the
DOCUMENT command so that, if there is a problem, a listing file
and the interim files will be available to aid debugging.
Problems in building books, and questions and comments about the
tools, should be reported via the notes conference set up for
this purpose on VAXUUM::ONLINE_BOOKBUILDING.
3 New Features
New features for this baselevel of the online bookbuilding tools
include:
o The online tools have been upgraded to run on VAX DOCUMENT
V1.2.
o Copyright page problems have been fixed.
o <MARGIN_NOTE> is now recognized in both doctypes.
o More "chunkiness": paragraphs, def_list items, subheads,
centered heads are now "chunks" and thus addressable from the
table of contents and index.
o Prototype master index support (ONLINE.MASTER_INDEX doctype)
o Ada documentation support (ONLINE.ADA doctype)
o Bug fixes, many of which were reported in the ONLINE_
BOOKBUILDING notes conference on VAXUUM.
4 Known problems
1. File names must be less than 30 characters.
2. Device and directory file specifications must not exceed 48
characters. The device converter will report an error message
and abort the bookbuild if the device and directory spec is
too long. Logical names are not a workaround to this problem
because they are expanded before the device converter is run.
3. In a few cases, the text formatter has run out of memory
while processing books. These cases invariably involve very
large documents with very large numbers of informal tables
and/or very large informal code examples. This problem is
being investigated. However, making such tables and examples
formal generally fixes the problem.
The V1.2 version of the text formatter plus the added "chunk-
iness" should alleviate this problem.
4. Extension tags are not recognized, except as no-ops. Writ-
ing groups found that the font change used in the previous
baselevel to flag extensions was not sufficiently visually
distinctive. Support for extensions has been dropped until
Bookreader V2.0, which will support extensions.
5. Problem in coding headers (including <FIGURE>, <TABLE>, and
<EXAMPLE> tags): In your source file, if you break the header
tag's arguments after the backslash, it will introduce a
carriage return that creates problems for online processing.
Either code the header tag all on one line, or break the line
before the backslash. For example:
Do NOT do this:
<HEAD1>(Imagine this Is a Very Long Title\<RET>
long_title)
Do this instead:
<HEAD1>(Imagine this Is a Very Long Title\long_title)<RET>
Or this:
<HEAD1>(Imagine this Is a Very Long<RET>
Title\long_title)
6. The <UNNUMBERED_HEADS> tag is a no-op online: sections will
always be numbered. This limitation will be in effect un-
til V2.0 of the Bookreader, which will use a new method of
creating hotspots that will accommodate unnumbered heads.
|
| 64.8 | bug fixes | CLOSET::UTT | | Wed Jul 12 1989 12:16 | 16 |
| There is a bug in the June baselevel that results in bad titles
in index popup menus (where an index entry points to multiple
chunks). A fix has been added to CUP$ONLINE_DEFS.GDX, which can
be copied from:
VAXUUM::KITS_:[DOCUMENT.V12.SOFTWARE]CUP$ONLINE_DEFS.GDX
Note that, as in previous releases of the online tools, you should
use the \SYMBOLS= qualifier to include this file when you process
books for hardcopy and for online doctypes. Among other things, it
ensures that tags and keywords are defined properly.
(Another bug in the June baselevel is that this information was
omitted from the documentation.)
Mary
|
| 64.9 | Aug 4 baselevel of online tools | VAXUUM::UTT | | Fri Aug 04 1989 10:42 | 161 |
|
1 Location of Bookreader Software and Bookbuilding Tools
A new baselevel of the online bookbuilding tools for the DECwin-
dows Bookreader is available. To read books built with these
tools, you must be running DECwindows V1.0 (SDC version) or
later software. Note that this software is bundled with VMS V5.1
software: the savesets for this software, printable files of the
documentation, and the announcement memo are available in:
VMSKIT::SYS$KITS:[VMS051...]
In addition, to use these tools you must be running the SDC
versions of VAX DOCUMENT 1.2 and the internal 1.2 kit. The V1.2
kit is available in:
VAXUUM::KITS_:[DOCUMENT.V12.SOFTWARE]DOC012
(savesets A through D)
The internal kit is in:
VAXUUM::KITS_:[DOCUMENT.V12.SOFTWARE]DOCINT012
(savesets A and B)
These kits have been formally announced in Note 2.10 of the
DOCUMENT notes conference. You should refer to that note for
additional information.
To install the bookbuilding tools you must restore the following
saveset:
VAXUUM::KITS_:[DOCUMENT.V12.SOFTWARE]CUP$ONLINE_TOOLS.SAV
The following command line restores the saveset to your existing
DOC$TOOLS tree:
$ BACKUP CUP$ONLINE_TOOLS.SAV/SAV/SELECT=[DOC$TOOLS...] -
$_ dev:[DOC$TOOLS...]/NEW_VERSION
NOTE
You must be running VAX DOCUMENT on a VMS V5.0 system: the
online device converter does not run on earlier versions
of VMS.
2 For More Information
For details on coding SDML source files and generating online
books, see Coding Documentation Source Files for the DECwindows
Bookreader (June 19, 1989>; this is a new version for this
baselevel).
VAXUUM::KITS_:[DOCUMENT.V12.BOOKS]WRITER_GUIDELINES.PS
WRITER_GUIDELINES.LN03
WRITER_GUIDELINES.DECW$BOOK
(online version)
WRITER_GUIDELINES.DECW$BOOKSHELF
(bookshelf file for online version)
(The graphics files are missing from the LN03 version.)
NOTE
You should read this document carefully before processing
your books for the Bookreader.
Before processing your files for the Bookreader, process them
for normal hardcopy output to ensure that there are no coding
problems with the files. Make sure that any errors are fixed
before processing your files for online output. In addition,
please process your files using the /LIST/KEEP qualifiers to the
DOCUMENT command so that, if there is a problem, a listing file
and the interim files will be available to aid debugging.
Problems in building books, and questions and comments about the
tools, should be reported via the notes conference set up for
this purpose on VAXUUM::ONLINE_BOOKBUILDING.
3 New Features
New features for this baselevel of the online bookbuilding tools
include:
o Copyright page problems have been addressed.
o Formatting problems due to paragraph chunks have been
addressed.
o Bug fixes, many of which were reported in the
ONLINE_BOOKBUILDING notes conference on VAXUUM.
4 Known problems
1. File names must be less than 30 characters.
2. Device and directory specification may not exceed 48
characters. An error message that device and directory
spec is too long will be reported. Actual filenames will
still have their 30 character limit. Logical names will not
alleviate this problem because they get expanded before the
device converter is run.
3. Device and directory file specifications must not exceed 48
characters. The device converter will report an error message
and abort the bookbuild if the device and directory spec is
too long. Logical names are not a workaround to this problem
because they are expanded before the device converter is run.
4. In a few cases, the text formatter has run out of memory
while processing books. These cases invariably involve very
large documents with very large numbers of informal tables
and/or very large informal code examples. This problem is
being investigated. However, making such tables and examples
formal generally fixes the problem.
The V1.2 version of the text formatter plus the added
"chunkiness" should alleviate this problem.
5. Extension tags are not recognized, except as no-ops. Writing
groups found that the font change used in the previous
baselevel to flag extensions was not sufficiently visually
distinctive. Support for extensions has been dropped until
Bookreader V2.0, which will support extensions.
6. Problem in coding headers (including <FIGURE>, <TABLE>, and
<EXAMPLE> tags): In your source file, if you break the header
tag's arguments after the backslash, it will introduce a
carriage return that creates problems for online processing.
Either code the header tag all on one line, or break the line
before the backslash. For example:
Do NOT do this:
<HEAD1>(Imagine this Is a Very Long Title\<RET>
long_title)
Do this instead:
<HEAD1>(Imagine this Is a Very Long Title\long_title)<RET>
Or this:
<HEAD1>(Imagine this Is a Very Long<RET>
Title\long_title)
7. The <UNNUMBERED_HEADS> tag is a no-op online: sections will
always be numbered. This limitation will be in effect until
V2.0 of the Bookreader, which will use a new method of
creating hotspots that will accommodate unnumbered heads.
8. Some online tags and keywords are not yet recognized in the
global tag set. DOC$LOCAL_FORMATS:CUP$ONLINE_DEFS.GDX,
therefore, is installed when the saveset is restored.
It can either be included directly using the \SYMBOLS=
qualifier on the command line or it can be includef using the
<INCLUDE> tag in the symbols file normally used to process
the book. This file ensures that online tags and keywords are
recognized for hardcopy bookbuild.
|
| 64.10 | Version 2 Bookbuilding Tools Available | NAVIGO::GRANT | I've saved $2166.00 since I quit smoking. | Wed Oct 18 1989 17:14 | 417 |
| __________________________________________________________________
1 Location of Bookreader Software and Bookbuilding Tools
Bookreader V2.0 Support Only: This baselevel of
the online tools supports only the V2.0 DECwindows
Bookreader (which runs only on DECwindows V2.0
software). Books built with these tools cannot be
viewed with the V1.0 Bookreader.
A new baselevel of the online bookbuilding tools for
the DECwindows Bookreader is available. To read books
built with these tools, you must be running DECwindows
V2.0 software. Note that this software is bundled
with VMS V5.3 software. For information about the
savesets for this software refer to topic 209.* in the
CLOSET::ONLINE_BOOKBUILDING conference.
In addition, to use these tools you must be running
the SDC versions of VAX DOCUMENT 1.2 and the internal
1.2 kit. The V1.2 kit is available in:
CLOSET::KITS_:[DOCUMENT.V12.SOFTWARE]DOC012
(savesets A through D)
The internal kit is in:
CLOSET::KITS_:[DOCUMENT.V12.SOFTWARE]DOCINT012
(savesets A and B)
These kits have been formally announced in Note 2.10
of the DOCUMENT notes conference. You should refer to
that note for additional information.
To install the bookbuilding tools you must restore the
following saveset:
CLOSET::KITS_:[DOCUMENT.V12.SOFTWARE]ONLINE_A012.SAV
The following command line restores the saveset to
your existing DOC$TOOLS tree:
$ BACKUP ONLINE_A012.SAV/SAV/SELECT=[DOC$TOOLS...] -
$_ dev:[DOC$TOOLS...]/NEW_VERSION
Note: You must be running VAX DOCUMENT on a VMS V5.0
system: the online device converter does not run on
earlier versions of VMS.
1
Note that both a new tag translator file and a new
message file are installed with this kit.
Two files are included in the kit that should be
used to modify two existing files. The two new files
are installed in the DOC$LOCAL_FORMATS directory.
The file ONLINE_DESIGNS.DAT should be appended to
the existing DOC$DESIGNS.DAT file. and the ONLINE_
DESTINATIONS.DAT file should be appended to the
existing DOC$DESTINATIONS.DAT file. The following
command lines will append the files:
$ APPEND DOC$LOCAL_FORMATS:ONLINE_DESIGNS.DAT -
$_ DOC$LOCAL_FORMATS:DOC$DESIGNS.DAT
$ APPEND DOC$LOCAL_FORMATS:ONLINE_DESTINATIONS.DAT -
$_ DOC$LOCAL_FORMATS:DOC$DESTINATIONS.DAT
If either DOC$DESIGNS.DAT or DOC$DESTINATIONS.DAT
do not already exist, the file provided with the kit
should be renamed. The following command lines will
rename the files:
$ RENAME DOC$LOCAL_FORMATS:ONLINE_DESIGNS.DAT -
$_ DOC$LOCAL_FORMATS:DOC$DESIGNS.DAT
$ RENAME DOC$LOCAL_FORMATS:ONLINE_DESTINATIONS.DAT -
$_ DOC$LOCAL_FORMATS:DOC$DESTINATIONS.DAT
A file containing a command procedure to define
logical names required by this version of the
bookbuilding tools is also provided. This file should
be added to the command procedure used to set up
the VAX DOCUMENT environment. (We recommend that it
not be added to DOC$STARTUP.COM since that file is
overwritten each time VAX DOCUMENT is installed.) The
file is named ONLINE_LOG_DEFS.COM and is placed in
DOC$LOCAL_FORMATS by the kit. To execute this command
procedure, use the following command:
$ @DOC$LOCAL_FORMATS:ONLINE_LOG_DEFS.COM
2
Note that the logical name definition for the message
file has been changed. The new definition is:
$ DEFINE DOC$MESSAGE DOC$LOCAL_FORMATS:DOC$MSG.EXE
This logical is also defined by executing ONLINE_LOG_
DEFS.COM.
A troubleshooting tool has been provided with
this kit. It is a tool that will provide valuable
information about a book file (.DECW$BOOK).
Information such as the book title, symbolic name,
build date, etc. will be displayed. To use this tool
you will first have to execute a command procedure
that defines 'BOOKINFO' as a foreign symbol. This
command procedure is located in DOC$LOCAL_FORMATS and
is executed by the following command:
$ @DOC$LOCAL_FORMATS:BOOKINFO_SETUP.COM
You would then type the following command to display
the file information:
$ BOOKINFO dev:[dir]BOOKREADER.DECW$BOOK
Title: "Using the Bookreader"
Symbolic Name: "VMS_DECW_BOOKREADER"
Build Date: 13-OCT-1989 10:18:57.62
Structure Level: 2.0
LMF Information
Product Name: "VAX-VMS"
Producer: "DEC"
Date: none
Version: 0
Book contains the following directories:
Contents
Index
Note that dev:[dir] represent the device and directory
where the book file is located.
3
__________________________________________________________________
2 For More Information
For details on coding SDML source files and generating
online books, see Coding Documentation Source Files
for the DECwindows Bookreader (June 19, 1989); this is
a new version for this baselevel).
CLOSET::KITS_:[DOCUMENT.V12.BOOKS]WRITER_GUIDELINES.PS
WRITER_GUIDELINES.LN03
(The graphics files are missing
from this version.)
WRITER_GUIDELINES.DECW$BOOK
(online version)
WRITER_GUIDELINES.DECW$BOOKSHELF
(bookshelf file for online version)
Note: You should read this document carefully before
processing your books for the Bookreader.
Before processing your files for the Bookreader,
process them for normal hardcopy output to ensure that
there are no coding problems with the files. Make sure
that any errors are fixed before processing your files
for online output. In addition, please process your
files using the /LIST/KEEP qualifiers to the DOCUMENT
command so that, if there is a problem, a listing
file and the interim files will be available to aid
debugging.
Problems in building books, and questions and comments
about the tools, should be reported via the notes
conference set up for this purpose on CLOSET::ONLINE_
BOOKBUILDING.
4
__________________________________________________________________
3 New Features
This baselevel of the online tools supports V2.0
of the Bookreader. If you are still using the V1.0
Bookreader, you should not install this kit until
you upgrade to the V2.0 Bookreader: the books you
build with this kit will not be readable by the V1.0
Bookreader. (Note that books built using the V1.0
online tools can be read by the V2.0 Bookreader,
although they may look somewhat different and will
not take advantage of new V2.0 Bookreader features and
bug fixes.)
The following summarizes the changes for the V2.0
format:
o Page width
The topic window is narrower in V2.0 so the control
window and the topic window would both fit on a 15-
inch monitor without overlap. The V2.0 books are
formatted for this narrower width. The V1.0 books
were formatted for a wider width. When V1.0 books
are viewed on the V2.0 Bookreader, it is possible
that they are wider than the topic window and thus,
the right side of some text may get clipped by the
narrower V2.0 window. The V2.0 Bookreader minimizes
this clipping by automatically scrolling V1.0
topics to the left, taking away some of the left
margin.
o Hotspot alignment
When V1.0 books are displayed on a 100-dpi (15-
inch) monitor with either the V1.0 Bookreader
or the V2.0 Bookreader, there is a problem with
hotspot outlines misaligning with the corresponding
text. This is because the font metrics are
different on the 75-dpi and 100-dpi monitors
(font metrics are not monitor independent!).
The V2.0 online tools fix this problem (although
5
some spacing problems remain due to the monitor-
dependent font metrics).
o Hotspot format
The V1.0 format required that hotspots be
rectangular. This sometimes forced hotspots with
long text to extend beyond the right border of the
topic window; it also prevented the use of long
text sections (such as header text) as hotspots.
The V2.0 online tools and the V2.0 Bookreader
permit hotspots to break across lines.
o Index granularity
The V2.0 format allows the index to point to
paragraphs. The V1.0 Bookreader only let the
index point to topics and subtopics. The finer
granularity of the index for V2.0 means that the
the reader goes directly to the relevant text
rather than to the beginning of a possibly lengthy
section of text.
o Performance
The V1.0 Bookreader dealt only with 75-dpi
monitors, so the V1.0 bookbuilding tools hardcoded
75-dpi font names. The V2 Bookreader must convert
all of these to the corresponding 100-dpi font
names before displaying on a 100-dpi monitor. This
means that V1.0 books will be displayed somewhat
slower by the V2.0 Bookreader than V2.0 books.
o Bitmap images on nonstandard monitors
V1.0 figures may not display correctly on monitors
other than 75- or 100-dpi. All V1.0 figures,
however, are displayed correctly on both 75- and
100-dpi monitors.
o Directories for figures, tables, and examples
6
In V1.0 books, the only way to get at the lists
of figures, tables, and examples was to scroll
to the bottom of the Table of Contents. On large
books, this could be cumbersome. The V2.0 books
give you separate directories for figures, tables,
and examples. These directories are available from
the View menu. (They are also still displayed at
the bottom of the Table of Contents.)
o Cumulative fixes in the bookbuilding tools
The V2.0 tools include all fixes made to the V1.0
tools over their lifetime. The current set of books
on the online CDROM offering were built at various
times during this time period. Some of the books
are as old as last February. Rebuilding these books
for V2.0 will pick up all these fixes and changes.
For all of these reasons, it is highly recommended
that books that have been issued on CD to date be
rebuilt as soon as possible for re-issue for the V2.0
Bookreader in January. In addition, rebuilding the
books will provide consistency for users. If some
books are in V2.0 format and some in V1.0 format,
the customer is likely to notice the differences and
wonder why some books have "problems" and others
don't, and submit needless QARs and SPRs about
nonexistent bugs. If received, such QARs and SPRs
will be reassigned to the writing groups responsible
for the documents cited in the reports.
Other new features for this baselevel of the online
bookbuilding tools include:
o Extension (<EXTENSION>(text) or <EXTENSION>
/<ENDEXTENSION> pairs) tags are now supported.
The Bookreader shades the text tagged as an
extension. The shading can be turned off and on
via the View pulldown menu on the text window.
7
o As mentioned, hotspots can now break across lines
and, as a result, the <UNNUMBERED_HEADS> tag is
supported and <REFERENCE>(arg\full) produces the
full reference as a hotspot.
The hotspots can be turned on and off via the View
pulldown menu on the text window.
o A set of tags for writing LMF (License Management
Facility) information into the online books has
been implemented.
o An ONLINE.SHELF doctype has been implemented to
structuring the online library and bookshelves at
the SDML level.
o Bug fixes, many of which were reported in the
ONLINE_BOOKBUILDING notes conference on CLOSET.
__________________________________________________________________
4 Known problems
1 File names must be less than 30 characters.
2 Device and directory specification may not exceed
48 characters. An error message that device and
directory spec is too long will be reported. Actual
filenames will still have their 30 character
limit. Logical names will not alleviate this
problem because they get expanded before the device
converter is run.
3 In a few cases, the text formatter has run out
of memory while processing books. These cases
invariably involve very large documents with very
large numbers of informal tables and/or very large
informal code examples. This problem is being
investigated. However, making such tables and
examples formal generally fixes the problem.
The V1.2 version of the text formatter plus the
added "chunkiness" should alleviate this problem.
8
4 Problem in coding headers (including <FIGURE>,
<TABLE>, and <EXAMPLE> tags): In your source file,
if you break the header tag's arguments after the
backslash, it will introduce a carriage return that
creates problems for online processing. Either code
the header tag all on one line, or break the line
before the backslash. For example:
Do NOT do this:
<HEAD1>(Imagine this Is a Very Long Title\<RET>
long_title)
Do this instead:
<HEAD1>(Imagine this Is a Very Long Title\long_title)<RET>
Or this:
<HEAD1>(Imagine this Is a Very Long<RET>
Title\long_title)
5 Some online tags and keywords are not yet
recognized in the global tag set. DOC$LOCAL_
FORMATS:CUP$ONLINE_DEFS.GDX, therefore, is
installed with the kit.It can either be included
directly using the \SYMBOLS= qualifier on the
command line or it can be included using the
<INCLUDE> tag in the symbols file normally used
to process the book. This file ensures that online
tags and keywords are recognized for hardcopy
bookbuilds.
6 The tag <VERTICAL_SPACE>(fill) in copyright pages
may cause text to be overwritten in some cases
(usually in long copyright pages).
9
|
| 64.11 | Correction | VAXUUM::UTT | | Mon Oct 23 1989 08:32 | 17 |
| As noted in note 64.10, under Known Problems, the file DOC$LOCAL_FORMATS:
CUP$ONLINE_DEFS.GDX should be referenced in or as a symbols file to
ensure that online tags and keywords are recognized globally. There is,
however, an error in the file distributed with the saveset released on
20 Oct. If you have installed that saveset, you should copy the file
CLOSET::KITS_:[DOCUMENT.V12.SOFTWARE]CUP$ONLINE_DEFS.GDX
and place it in DOC$LOCAL_FORMATS.
The saveset currently available in CLOSET::KITS_:[DOCUMENT.V12.SOFTWARE]
contains the correct version of CUP$ONLINE_DEFS.GDX, so you need not
recopy the above file if you are installing that saveset.
Apologies for any inconvenience,
Mary
|
| 64.12 | | VAXUUM::UTT | | Tue Oct 31 1989 14:48 | 24 |
| The VMS documentation group built their docset last week using the
LMF tags, the first really rigorous "field test" for these tags.
They found 2 bugs:
1. an unforseen interaction with the <title> tag in part pages
when <reference> is used with the part-part <title>, which
results in the LMF information *not* being written into the
book file.
2. a warning message about a truncated <counter> name. This message
is actually harmless and has no effect on the LMF information
being written into the book file (or on anything else in the book).
The first bug was fixed and the second was ameliorated and documented.
A new kit is available in KITS_:[DOCUMENT.V12.SOFTWARE] and new
documentation in KITS_:[DOCUMENT.V12.BOOKS]. The kit should be
installed per note 64.10. In addition, the CUP$ONLINE_DEFS.GDX
on that kit is corrected (see note 64.11), and the problem of
wide informal tables has been addressed (see note 218).
Mary
|