[8] in Open-Software-Foundation-News
November Doc (and DCE Doc) SIG Minutes
daemon@ATHENA.MIT.EDU (hal@osf.org)
Wed Jan 19 15:15:10 1994
Resent-From: Bill Cattey <wdc@MIT.EDU>
Resent-To: osf-news-mtg@menelaus.LOCAL
Date: Mon, 17 Jan 94 15:16:42 -0500
From: hal@osf.org
To: sig-doc@osf.org, sig-dce@osf.org
Cc: tony@osf.org, jeanette@osf.org
Reply-To: hal@osf.org (Hal Lichtin)
Better late than never:
The OSF DOC SIG met on Wednesday, November 3, and Thursday, November 4 in
Boston at the World Trade Center. The November 3 session devoted to DCE
documentation. The November 4 session was devoted to OSF documentation in
general, including a report from Prentice-Hall and a discussion of SGML
conversion. Thanks to Margaret Taft of Hewlett-Packard, who provided much
of the input to these minutes. The delay in making them available was not
hers.
Following is the list of the attendees from the DCE SIG Meeting.
Name Company Name
Email Address Telephone
-------------------------------------------------------------------------------
THE FOLLOWING ATTENDED BOTH DAYS:
Kathy Digan Tandem / OSF
digan@osf.org (617)621-8735
Jane Wyman Tandem
wyman_jane@tandem.com (408)285-2266
Diana Goldfarb Digital
goldfarb@terse.enet.dec.com (508)486-5047
Mary Grinham Digital
grinham@terse.enet.com (603)881-2113
Wayne L. Wohler IBM
wohler@vnet.ibm.com (303)924-5943
Mike Leandertz IBM
leandertz@vnet.ibm.com (416)448-3501
Bob Mathews OSF
rom@osf.org (617)621-8790
Anthony Fiore OSF
tony@osf.org (617)621-8939
Hal Lichtin OSF
hal@osf.org (617)621-8809
Nancy Paisner Hitachi
nancy@hi.com (617)890-0444
Katie Kean Transarc
kt@transarc.com (412)338-4447
THE FOLLOWING ONLY ATTENDED THE FIRST (DCE) DAY:
Kerry Raymond CRC for Distributed Systems Technology
kerry@dstc.edu.au +61 7 365-4321
Brian Collins Stratus Computer, Inc
Brian_Collins@vos.stratus.com (508)460-2721
Rich Salz OSF
rsalz@osf.org (617)621-7253
Steve Bertrand SNI
bertrand@sni-usa.com (617)273-0480
Bill Leddy HAL
leddy@hal.com (512)794-2855
Margaret W. Taft H.P.
mwt@apollo.hp.com (508)436-5882
Dave Robinson Digital
drobinson@tuxedo.enet.dec.com (508)486-5284
Valerie Dwyer OpenVision
valerie@grf.ov.com (508)839-9776
THE FOLLOWING ONLY ATTENDED THE SECOND DAY:
Eve Maler Digital
maler@zk3.dec.com (603) 881-0310
Lee Fogal Digital
fogal@zk3.dec.com (603) 881-1446
Alan Houser Hewlett-Packard
arh@ch.hp.com (508) 436-4926
Gregory Doench Prentice Hall
ggd@prenhall.com (201) 816-4114
Rich Nollman SNI
rnollman@sni-usa.com (617) 354-7959
Carl Scholz OSF
scholz@osf.org (617) 621-8996
Fred Dalrymple OSF
fred@osf.org (617) 621-8855
DCE WORKING GROUP MEETING (11/3/93)
INTRODUCTION
The first part of the meeting consisted of attendees introducing themselves
and describing their company's strategy for creating DCE documentation. Here's
a summary of the documentation strategies of the companies that attended:
Transarc delivers the guides but not the reference manuals (which consist
of manpages). Transarc plans to deliver the documentation in a
hypertext form when SGML versions of the manuals are available.
Tandem will not have a DCE product until 1994; they plan to deliver DCE
documentation on CD-ROM. Tandem delivers all documentation on
CD-ROM, only providing hard copy to customers who demand it.
Only a few customers want printed manuals
Stratus has not yet released a DCE product; when they release one in 1994,
they will use Prentice-Hall documentation and release notes.
University of Queensland (Australa) uses DCE extensively in post-graduate
courses. They require printed books for their purposes.
Siemans/Nixdorf uses Prentice-Hall documentation and release notes. They
write at most 2 documents per DCE release, App Dev Guide and Admin
Guide supplements.
Hal Computer Products does not have a released DCE product yet, but they do
have all of the DCE documentation online, complete with a hypertext
browser.
DEC distributes books as both hardcopy and online, including all of the
Prentice-Hall and O'Reilly books.
Hewlett-Packard delivers all of the OSF DCE documentation except
for volume I of the System Administration manual and the
User's Guide. HP delivers only release notes and man pages
online but wishes to deliver all manuals on CD-ROM. HP also
documents value-added DCE products, one of them online only.
IBM has DCE on several platforms. For AIX, IBM distributes one hard
copy book and the rest on CD-ROM. For MVS and OS400, IBM
Toronto rewrites the DCE books for a non-UNIX audience.
They've also created a messages guide for the approximately
4,000 DCE messages. IBM Toronto is moving towards softcopy
documentation.
OSF was represented by Tony Fiore, director of documentation, Hal Lichtin,
section manager for DCE and DME documentation, and Bob
Mathews, project leader for DCE 1.1 documentation.
OpenVision is a new startup; they were basically collecting information.
There was a side discussion of who, if anybody, needs a copy of the DCE AES; the
conclusion was experts only.
DCE 1.0.3 DOCUMENTATION UPDATE
The latest schedule for DCE 1.0.3 is
Core components released 12/93
Distributed File Service (DFS) Released 1/94
NOTE: The DCE 1.0.3 RELEASE IS NOW AVAILABLE.
The focus of DCE 1.0.3 is defect resolution, performance improvements,
and new platform support (including HP-UX on a 700); there is a minimal
number of new features.
Prentice-Hall will not publish 1.0.3 versions of the DCE manuals. OSF
will distribute a complete documentation tree for DCE 1.0.3 with changes
marked with change indicators. The DCE 1.0.3 distribution tape includes
updated documentation specifications for DCE 1.1 books.
NOTE: THE 1.0.3 TAPE DOES NOT INCLUDE CHANGE BARS IN THE BUILT (PostScript,
ASCII) VERSIONS OF THE BOOKS. HOWEVER, IF YOU DOWNLOADED DCE 1.0.3 FROM
THE ELECTRONIC RELEASE AREA DURING APPROXIMATELY THE FIRST WEEK AFTER 1.0.3
WAS MADE ELECTRONICALLY AVAILABLE, YOU RECEIVED A VERSION THAT DID HAVE
CHANGE BARS IN THE OUTPUT. THIS ERROR WAS CORRECTED AND BOTH THE TAPE AND
ELECTRONIC RELEASE AREA HAVE THE CORRECTLY BUILT VERSIONS. THE SOURCE
VERSIONS OF THE BOOKS WERE CORRECT AT ALL TIMES.
The major documentation enhancements for DCE 1.0.3 include
o Over 174 documentation defects resolved
o Rewrite of the dce_config chapters in Volume I of the
System Administration Guide
o Enhancements to GDS documentation, including online help
o Significant editorial changes to the Administration Guides
(made in preparation for Prentice-Hall Publication)
o RPC internals documentation added to the Technical Supplement
PRENTICE-HALL PUBLICATIONS
The AES (Application Environment Specification) for DCE RPC is
in print.
The DCE Administration Guide, Volume 2 -- Core Services is in print.
The DCE Administration Guide, Volume 1 -- Introduction was at the printer
at the time of the meeting. It is now available.
The DCE Administration Guide, Volume 3 -- Extended Services was at PH
at the time of the meeting. It is now available.
Additional AES volumes are in various states
Distributed Time Service has been accepted by X/Open; it will
be published with Directory Services
Directory Services was reviewed by X/Open; comments are being
incorporated.
Security Services and Threads Services are under development.
Work has not yet started for the DFS volume.
Prentice-Hall will publish new editions of DCE books for DCE 1.1.
(Prentice-Hall will continue to make pre-1.1 books available.)
NOTE: Published books will be available sometime AFTER DCE 1.1 is
released. Hal Lichtin's guesstimate is that printed books
will be available 4 - 6 months after software release.
Prentice-Hall has Japanese and German translations of Introduction to
DCE in progress.
O'REILLY AND ASSOCIATES PUBLICATIONS
O'Reilly has plans to translate its DCE books into Japanese; "Understanding
DCE" is available in French.
O'Reilly is revising "Writing DCE Applications" to include information about
using Directory Services and Security Services. The revised book will be
availible in Q1 1994.
O'Reilly has published "Distributing Applications Across DCE and Windows
NT" (preliminary copies were available at the time of the meeting; it is
now generally available). O'Reilly has under development a book on DCE
system administration (will be task-oriented).
DCE 1.1 TECHNICAL OVERVIEW
DCE 1.1 will include a number of technical changes including
o Simplified system administration through dcecp (DCE Control
Program) and dced (DCE Daemon). dcecp performs many functions
of the existing control programs (rpccp, cdscp, rgy_edit,
acl_edit, dtscp); dced replaces the rpcd, sec_clientd and other
daemons and provides additional information and management facilities.
o Improved security via the DCE Audit Subsystems developed by
IBM
o Serviceability
o Performance
o Code cleanup
o Integration
o Internationalization
o Improved test coverage
o Convenience functions
o Many component-specific enhancements
dcecp has a significant impact on documentation.
DOCUMENTATION ENHANCEMENTS FOR DCE 1.1
New documentation for DCE 1.1 consists of
o Introduction and Style Guide volume for the
Application Development Guide
o OSF DCE Troubleshooting Guide
Administration Documentation will require extensive changes because of
dcecp and dced. dced and dcecp concepts will be added to Volume 1 of the
System Administration Guide. This may create a problem because a number of
vendors, including HP, do not distribute volume 1 because they have
platform-specific procedures for install and configuration. One solution
may be to move the discussion of dce_config to an Appendix. DEC, among
others, distribute vloume 1 regardless of the fact that DEC users don't use
dce_config. About 50% of the current administration guide will be
rewritten.
NOTE: FOLLOWING THE SIG DISCUSSION AND CONSIDERATIONS AT OSF, OSF DECIDED
TO INCLUDE THE SUBSTANTIVE PART OF THE DCED and DCECP DOCUMENTATION IN THE
CORE VOLUME (VOL 2.)
The Application Development Guide will have three volumes: Introduction and
Style Guide; RPC, Threads, Time, and Security Services, and Directory
Services (CDS and GDS). DFS information will not be published in the
Prentice-Hall books; it will be moved to the "Technical Supplement".
Licencees can redistribute this information, if they wish.
The User's Guide will be revisited, and may be dropped.
SEE DISCUSSION BELOW
The Technical Supplement will be clearly divided into a tree
that can be redistributed and one that can't.
ISSUES AND DISCUSSION
The last 45 minutes of the meeting were devoted to a discussion of a number
of issues. There was not obvious consensus on these issues. OSF (Hal
Lichtin) will send email by the end of November to the SIG mailing list
that will propose resolutions and ask for comments. The primary issues are
o dcecp uses a Tools Command Language (TCL) developed by
Prof. Ousterhout of Berkeley. TCL is designed to be
extensible. Should TCL be described in DCE documentation?
The Representaive from Hal Computers thought that
TCL might create support problems. Nancy Paisner of Hitachi
stated that the vendors should decide if users should
get the extensibility information. The sense of the meeting
was that extensibility information should not be in the
Prentice-Hall books.
(THE NOTES IN ALL CAPS CONSTITUTE OSF's RESPONSE AND RESOLUTION OF THESE
ISSUES.)
OSF WILL PROVIDE DCECP DOCUMENTATION, NOT TCL DOCUMENTATION. THERE WILL BE
SOME NECESSARY OVERLAP, AND WE WILL NOT TRY TO HIDE TCL. WE WILL PRESENT
AS MUCH TCL SYNTAX AS IS NECESSARY TO USE DCECP. WE WILL PROVIDE
INFORMATION ON WRITING DCECP SCRIPTS. HOWEVER, WE WILL ASSUME THAT ANYONE
WHO WISHES TO DO SIGNIFICANT WORK ON EXTENDING DCECP FUNCTIONALITY HAS
ACCESS TO TCL DOCUMENTATION, AND WILL POINT TO PUBLISHED DOCUMENTATION ON TCL.
o There needs to be a defined obsolescence policy for OSF
documentation; OSF will propose one. (For example, acl_edit
will be present at DCE 1.1, but shouldn't be used. Should
the manpages be distributed? Should they be marked obsolete?)
Margaret Taft of HP suggested that some warning should
be given about removing documentation (and calls), such
as a statment that they should be used at this release
and will be removed at the next release. There was some
agreement with this postion. There was also some discussion
about the best way to indicate in the reference page that
the call was obsolete, becuase programmers don't read the
entire reference page (instead they check a particular option
or parameter). No one had a good solution.
AS OF THIS DATE WE HAVE PARIALLY ADDRESSED THIS ISSUE. WE WILL INCLUDE
ALL REFERENCE PAGES AT 1.1. WE HAVE NOT YET DETERMINED WHETHER TO MARK
THEM AS OBSOLETE OR OBSOLECENT. WE WILL REMOVE ALL OLD GUIDE DOCUMENTATION
WHERE THERE IS A NEW "BETTER" WAY OF DOING SOMETHING (E.G., VIA dcecp).
o There was a fair amount of discussion about the User Guide.
The audience is unclear. Many users seem to ignore it.
HP stated that the auidence for the Users Guide is programmers
and others who need to perform light-weight system administration
tasks and who don't need or want to use the System Adminsitration
Guide. There was some discussion that the manual should
just disappear -- that it should be released one more time.
OSF will make a proposal about its future. One possible solution
is to discontinue the User's Guide, but to create a DCE commands
manual, with all commands (system administration, programming (IDL,
etc), and "user" (kinit, etc.)) in one place. Another possible
solution is to distribute the User's Guide information into
existing manuals. A number of people thought that it would
be a mistake to document part of dcecp in the User's Guide and
part of it in the System Administrator's Guide.
OSF DETERMINED TO DISCONTINUE THE USER'S GUIDE. WE WILL PUT THE COMMANDS
IN THE ADMINISTRATOR'S (OR COMMAND) REFERENCE AND WILL PUT ALL RELEVANT
INFORMATION IN EITHER THE ADMINISTRATOR'S GUIDE (MOST OF IT) OR THE
INTRODUCTION TO DCE. THE DFS INFORMATION IN THE USER'S GUIDE AND REF WILL
BE MOVED TO THE INTRO TO DCE AND THE NEW DFS ADMIN GUIDE AND REF.
MISCELLANEOUS WORKING GROUP INFORMATION
Katie Kean of Transarc will resign the DCE Doc working group chair at the
end of the year. There will probably be 2 or more co-chairs. Mike
Leandertz of IBM Toronto was nominated; Jane Wyman of Tandem was willing to
help if there were meetings on the West Coast. Mike has now officially
volunteered for the position and will act as chair for the next meeting of
the group.
The next meeting may be at the same time as the meeting of the DCE SIG,
scheduled for March on the West Coast. Mike will be sending out an inquiry
to determine if there is sufficient interest to hold such a doc meet.
----------------------------------------------------------------------------
GENERAL SESSION -- 11/3/94
The general session of the DCE doc SIG covered three main topics: OSF
documentation status, Prentice hall documentation, and SGML tools and
transition plans.
OSF DOCUMENTATION PLANS: MOTIF and DME
Thursday's session began with Hal Lichtin and others speaking about the
OSF's documentation plans for Motif and DME (Distributed Management
Environment).
DME 1.0 (Distributed Services) documentation consists of:
Introduction to DME
DME System Administrator's Guide and Reference
DME Application Developer's Guide and Reference
Release Notes
These documents would be included on the DME release tape and would not
be published by Prentice Hall.
SINCE THE MEETING THE OSF EDUCATION GROUP HAS DETERMINED THAT IT WILL MAKE
DME DOCUMENTATION SETS AVAILABLE, AND MAY ALSO MAKE THE INTRODUCTION TO DME
AVAILABLE AS A SEPARATELY ORDERABLE ITEM. WE WILL ANNOUNCE THE DETAILS
WHEN THE BOOKS BECOME AVAILABLE. (NOT COVERED IN THE MEETING, BUT THE
EDUCATION GROUP WILL ALSO BE SELLING COMPELETE SETS OF THE DCE 1.0.3
DOCUMENTATION.)
The Motif discussion included a description of the work being done on the
Motif 2.0 documentation set. This work includes a complete rewrite of the
Style Guide and a new Widget Writer's Guide.
The Style Guide work is an effort between OSF and IBM to improve PC style
and Motif style convergence, with IBM writing the common base. OSF will
then incorporate Motif-specific changes, provide the checklist and
illustrations, and do any Motif-specific editorial work.
The Revision D of the Motif AES has been submitted to X/OPEN and was
included on the Motif Beta tape.
The Widget Writer's Guide and Reference contains both Guide and Reference
sections in a single book. The book is intended for non-source licensees
who are writing their own widgets and includes documentation of Traits, _Xm
functions, Primitive and Manager internals, Exm widgets, and foundry
widgets.
The Programmer's Reference, Programmer's Guide, and User's Guide are all
being updated with documentation of new Motif 2.0 functionality, including
several new widgets and internationalization enhancements. The guide
documents will also have a certain amount of cleanup work.
OSF's SGML EFFORT
Fred Dalrymple of the OSF spoke about OSF's conversion to SGML. The
conversion is occurring in three steps:
1. Define DTDs
2. Create tools and a tools environment
3. Convert existing docs to SGML
OSF is currently completing step 2.
The following are OSF's plans for providing SGML versions of the DCE
documentation:
- Machine-converted SGML at DME 1.0 (Q3 93). The machine-converted
SGML is not "supported;" its quality depends on the robustness
of the converters and the quality of the original SML markup
(i.e. markup that breaks rules of SML semantics probably won't
convert very well).
- DCE 1.1 will have a similar treatment. Machine-converted SGML
will be included at Beta and on the release tape. Supported DCE
SGML source will be provided sometime after the DCE 1.1 release.
[OSF is currently looking into whether this schedule can be
shortened.]
Fred commented about documentation interoperability and exchange, stating
that OSF believes that the ultimate documentation interoperability solution
lies in source conversion. OSF has written documentation conversion tools,
including an OSF DTD to SML translator and a DTD-to-DTD converter. The
terms under which these will be distributed, however, is an open issue that
OSF is working on resolving.
One of the questions from the audience asked which authoring tool(s) OSF
uses for authoring in SGML. Fred preceded his answer with a disclaimer
that he was telling us only for our information and was not endorsing a
particular tool. OSF is using Arbortext, off-the-shelf, with the OSF DTDs.
Arbortext requires another file, known as a FOSI (Format Output
Specification Instance) to produce formatted output. Fred said that the
OSF would be willing to supply both their DTDs and FOSI files to those who
request them.
Fred noted that Arbortext is not a true WYSIWYG system (it has a previewing
feature, but it does not do real-time WYSIWYG). Fred said that this was
desirable for the OSF's writers, because there is no single specific output
format (hardcopy, online) nor page layout (for example, the hardcopy
page size could be 6x9, 8.5x11, or the European A4 size). The OSF's
writers pay attention exclusively to document semantics, and leave the final
formatting to the formatting tools.
OSF STYLE GUIDE
Hal Lichtin spoke very briefly about the OSF documentation style guide. He
said that this book had not been actively worked on recently, but hoped
that the effort would continue sometime in the next few months. The style
guide, however, does not currently have a schedule.
OSF and PRENTICE-HALL
Greg Doench of Prentice Hall spoke about Prentice-Hall's publishing
process. He stated that PH intends to provide an online version of the OSF
books it publishes, probably in a SGML-based format. This effort does not
currently have a publicly-announced schedule.
Greg indicated that documentation work such as OSF's is a relatively new
endeavor for Prentice Hall, and that Prentice Hall has built up a group to
meet such needs. He also indicated that Prentice Hall has made, and is
interested in making, specific arrangements with licensees to meet their
publication needs, including printing versions of OSF documents that are
not identical to the Trade versions.
The Current Prentice Hall publication plans at OSF are as follows:
OSF/1
Design of the OSF/1 Operating System is now available
OSF/1 1.2 User's Guide is available
1.2 Administration's/Command/Programmer's Reference are at Prentice Hall
Prentice Hall will not publish OSF/1 1.3 documentation
DCE
See the notes for 11/3.
Motif
Motif 2.0 documents, including the Widget Writer's Guide and Reference
will be published by Prentice Hall.
