🚀 go-pugleaf

In article <1993Jan4.200343.20281@texhrc.uucp> mjz@mjzsgi.Texaco.COM (Michael Zeitlin) writes:
>   Anyone use Insight for their own documentation....
>   Is there any info on how to use Insight for that purpose..
>
>   Insight is quite nice....i just assume use it for our own
>   "stuff"

Me too.  It's really nice, and seems like an ideal place for me to put our
on-line documentation as well.

-Andy

Andy Poling                              Internet: andy@jhunix.hcf.jhu.edu
UNIX Systems Programmer                  Bitnet: ANDY@JHUNIX
Homewood Academic Computing              Voice: (410)516-8096    
Johns Hopkins University                 UUCP: uunet!mimsy!aplcen!jhunix!andy

In article <1993Jan4.200343.20281@texhrc.uucp>, mjz@mjzsgi.Texaco.COM
(Michael Zeitlin) writes:
|> 
|>    Insight is quite nice....i just assume use it for our own
|>    "stuff"

Thanks for the compliment.  Our first release of InSight is meant as
a base level of functionality that we can build on for future versions.
With the InSight Viewer bundled with all machines we now have a base
for putting more documents online.  In the future we will add more 
functionality to the viewer and tools for helping users get documents
into InSight.

The InSight Viewer is based on a 3rd party toolkit from Electronic Book
Technologies, Inc. for displaying the books.  The format of the books 
InSight reads is an SGML file compiled using EBT's SGML compiler.  SGML
stands for Standard Generalized Markup Language and is a language for
tagging the structure of a document based on a DTD (Document Type 
Definition).

Adding books to the current version of InSight is not a trivial task.
Your "stuff" must be converted to SGML then compiled using EBT's tools.
We currently translate our books from Frame to SGML using a translator
from another 3rd party vendor named Avalanche.  Our process is 
semi-automated but specific to the SGI environment.  We have a group in 
CSD that is translating files from ascii to SGML for the Support bookshelf
but the files are semi-structured already.  We do not yet have a general 
purpose tool for incorporating arbitrary ascii text files into InSight.

The translation of a book from whatever format you author it in into 
SGML can either be done by yourself, or a service bureau.  Passage 
Systems, Inc. was formed partially for this purpose.  There also exist 
other companies that build translation filters from various formats to 
SGML.

We do hope that 3rd parties, OEM's, and ISV's will decide to put their 
documentation for their products online in InSight.  There are many 
advantages besides having a common means of accessing all the information,
the ability to query across all books, and the ability to link from one 
book to another.  Another key feature is that 3rd parties can write their 
book once for InSight and then take that same compiled book with EBT's
DynaText browser and deliver the same book on other platforms.  EBT's 
DynaText browser runs on a wide variety of platforms including Sun, DEC,
HP, and Windows.

I realize that this isn't an answer to the question of "How do I get my
documents online in InSight?" But before I write a lengthier reply I'd
like
to find out what kind of information you really want or need.

	Victor Riley
	InSight Engineer
	var@sgi.com

Insight is a wonderful concept, that's the way documentation ought to
be presented. Who needs paper anyway...

The format of the SGML documents should be published and accessible
though, so that everyone can add books without having to use external
service bureaus. If the format is closed, Insight might suffer the same
fate as the license server.

The license server was also an interesting idea, but it was sold in a
way that makes it unusable for anyone except SGI. The license server
developer's tools are $10k on my list, and I am not aware of a single
third-party software that uses it (undoubtedly there are some (Frame?),
but it certainly hasn't become the universally accepted way of selling
software). In fact, the company I work for has looked at it, shaken its
collective head, and written a proprietary license server.

Wouldn't it be great if everything - third-party software manuals, TeX
manuals, Webster's (I can dream, can I?), even /usr/man, and of course
the jargon file :-) - would be available as InSight books? Let's hope
legal obstacles won't prevent that.

BTW, is there a way to show the pictures directly in the document, the
way NeXT's digital librarian does it, rather than to hide them in an
icon? Optionally, maybe?

Thomas
-- 

--
Thomas Driemeyer        thomas@bitrot.in-berlin.de        voice: +49 30 8924936

In article <1993Jan10.215534.7994@bitrot.in-berlin.de>,
thomas@bitrot.in-berlin.de (Thomas Driemeyer) writes:
|> Insight is a wonderful concept, that's the way documentation ought to
|> be presented. Who needs paper anyway...
|> 
|> The format of the SGML documents should be published and accessible
|> though, so that everyone can add books without having to use external
|> service bureaus. If the format is closed, Insight might suffer the same
|> fate as the license server.
|> 

SGML is an international standard, I can't remember the ISO number it's
been 5 years since I looked at it.  It is also very large and complex,
which is probably why specialist bureaus exists.

if you can get hold of it, the current "Personal Computer World" has an
article on, it doesn't go into much technical depth - I think the aim is
explain how important this is going to be - for instance, from 1995 you
won't get a US defence contract unless your documentation is in SGML.

Andrew

In article <1993Jan10.215534.7994@bitrot.in-berlin.de>,
thomas@bitrot.in-berlin.de (Thomas Driemeyer) writes:
|> The format of the SGML documents should be published and accessible
|> though, so that everyone can add books without having to use external
|> service bureaus. If the format is closed, Insight might suffer the same
|> fate as the license server.

As Andrew also said in his followup, SGML is an international standard
If you would like the SGML standard it is ISO 8879 and can be ordered
from any member body of the ISO.  For a very good reference look at
"The SGML Handbook" by Charles Goldfarb.  Charles was the editor of the
SGML standard.

Now if you are refering to us publishing our DTD (Document Type Definition)
then give us a chance.  We just released the first version and are already
working on the second version.  We will release the DTD and other tools
at a later date.  For those not familiar with SGML, the DTD defines the
structure of a document, not the content of the document.  Our books are
instances of our DTD.

|> Wouldn't it be great if everything - third-party software manuals, TeX
|> manuals, Webster's (I can dream, can I?), even /usr/man, and of course
|> the jargon file :-) - would be available as InSight books? Let's hope
|> legal obstacles won't prevent that.

We hope to see alot of 3rd party manuals and man pages and other books
available within InSight over the next several years.  

|> BTW, is there a way to show the pictures directly in the document, the
|> way NeXT's digital librarian does it, rather than to hide them in an
|> icon? Optionally, maybe?

Yes, in version 2 of the product.

	Victor Riley
	InSight Engineer

[Thomas Driemeyer]
:
|   The format of the SGML documents should be published and accessible
|   though, so that everyone can add books without having to use external
|   service bureaus. If the format is closed, Insight might suffer the same
|   fate as the license server.

I don't know anything useful about Insight, and was alerted to this
message, but at least I know about SGML.

SGML is an International Standard (ISO 8879), and has been since 1986, and
has been one of ISO's best selling standards.  So "the format of the SGML
documents" is at least partially easily available.  The standard, however,
is not the whole story.  An SGML document conforms to a document type
definition (DTD), and it's really the DTD that defines the names of the
elements (information containers) in the document and their meaning, since
SGML does not specify processing in any way.  The language is "only" a
means to represent a structure of nested information containers as a string
of characters (file, if you want); the rest is up to an application of SGML
to a specific kind of structure.  The good news is that the DTD must be
available with all SGML documents conforming to them, so somewhere on the
system, there should be a concise description of each element, and how they
interrelate, usually in the form of the SGML "document type declaration":
look for the string "<!DOCTYPE" and see what it references.

For more information, see comp.text.sgml, or mail me.

Hope this helps.

Best regards,
</Erik>
--
Erik Naggum                 ISO  8879 SGML                    +47 295 0313
Oslo, Norway                ISO 10744 HyTime
<erik@naggum.no>            ISO  9899 C                 Memento, terrigena
<SGML@ifi.uio.no>           ISO 10646 UCS             Memento, vita brevis

In article <1993Jan10.215534.7994@bitrot.in-berlin.de>, thomas@bitrot.in-berlin.de (Thomas Driemeyer) writes:
|> Insight is a wonderful concept, that's the way documentation ought to
|> be presented. Who needs paper anyway...
|> 

I like Insight and am chomping at the bit for the day when all of our
documentation is in an online form so I don't have to hunt for manuals
when a customer calls and so, maybe, the customers won't have to call
support because they found the answer themselves using the fast search
capabilities of Insight.

However, my tongue in cheek response as to why paper manuals are still
nice to have/not obsolete -- it's a little difficult to take your IRIS
to the WC with you for some casual manual reading.  And, your spouse
would probably kick you out of bed if you tried to drag your IRIS into
bed to do some latenight manual reading.  True, these would be less of
an issue if we had a laptop IRIS but since such doesn't exist, it is
to our advantage that you can print out interesting chapters from Insight.
Besides, if the WC isn't well stocked, that paper manual could come in
handy just like the old Sear Robuck catalog of years past.  :^)
(My apologies if anyone is offended by toilet humor.)