[4991] in Athena Bugs
vax 7.0C: Scribe man page
daemon@ATHENA.MIT.EDU (drmorris@ATHENA.MIT.EDU)
Sun May 27 17:45:50 1990
From: drmorris@ATHENA.MIT.EDU
To: bugs@ATHENA.MIT.EDU
Date: Sun, 27 May 90 17:45:35 EDT
System name: tabetha
Type and version: CVAXSTAR 7.0C (1 update(s) to same version)
Display type: SM
What were you trying to do?
Read the scribe man page.
What's wrong:
It has inconsistant capitalization, doesn't list command line
options, doesn't list known bugs, doesn't give a version, doesn't list
the site file or help file, talks a little about Scribe formatting
commands without giving any real information, lists documentation
that doesn't exist (that I could find), and doesn't list documentation that
does exist. Specifically:
> SCRIBE(1) UNIX Programmer's Manual SCRIBE(1)
>
> NAME
> scribe - text formatter
>
> SYNOPSIS
> scribe file.mss
In Scribe version 7, the .mss is optional. The entire file is optional
(you can just type 'scribe'), if you want to go to a scribe command
line. There are many options on the command line such as -device (or
-dev), -document (or -doc), -hypvocab (or -hv), -hyd, -quiet (or -q),
-wordcount (or -word, -w), and -vocabulary (or -vocab, -voc, -v).
> DESCRIPTION
> scribe is a sophisticated text formatting program. In addi-
> tion to the simple formatting functions such as automatic
> paging with page numbers, headers and footers, and text jus-
> tification, scribe knows about many complex document types
> such as "reports" and "pocket guides" that it will automati-
> cally structure text to fit, including hyphenation, foot-
> notes, tables of contents, indexes, and bibliographies.
> Scribe also knows about different output devices, from the
> simple line printer to sophisticated laser printers. Scribe
> will adjust its output to take advantage of what power an
> output device can provide.
Scribe is not capitalized in the first two sentances, yet is capitalized
in the last two sentances. It should be consistent; I would argue that
it should be capitalized. This paragraph doesn't provide a reader with
much other than "Scribe can do some text formatting". A complete list
of document types and features later would be much more useful.
> The scribe command takes a file (usually with suffix .mss)
> that is full of scribe formatting commands, including an
> @device command that specifies the type of output device.
> Once invoked, scribe gives you a running account of what it
> is doing and the progress it is making on your file.
The line, "full of scribe formatting commands..." is quite useless. If
a reader doesn't know about them, this line simply says "Oh, yeah, you
can do that," without saying how. If a reader does know about them,
he/she deosn't need to read the sentence. Also, mentioning just one
command (especially one that students at Athena almost don't need to use
as we have almost all PS printers!) is not very helpful. Giving a list
of them, or not mentioning them at all and saying where to go for more
information would be better.
> Scribe writes its output to a file with the same name as the
> input file, and adds a three-character .extension indicating
> the type of output device it is meant to be printed on.
'PS' is three characters? How about a list of output devices or at
least the useful ones.
> Scribe can produce output files for a variety of devices
> such as the Information Systems Xerox 9700 laser printer and
> SIPB Apple Laser Writer.
True, but mentioning LNO3R's (or PostScript) would also be useful.
> FILES
> /usr/athena/scribe scribe binary
>
> /usr/athena/lib/scribe/database/* scribe database files
/usr/lib/scribe.sit, the Scribe "app-defaults" is missing.
/usr/athena/lib/scribe/scribe.hlp the Scribe help file, is missing.
> SEE ALSO
> printers(7)
>
> Athena documents, Essential Scribe, More Scribe: Report, and
> More Scribe: Thesis.
>
> SIPB documents, Using the Xerox 9700 from Project and Using
> the Laser Writer from Project
>
> Scribe User Manual, by Brian K. Reid and Janet H. Walker,
> Third Edition, 1980, Unilogic, Ltd.
>
> Scribe Pocket Reference, 1980, Unilogic, Ltd.
>
> Scribe Database Administrator's Guide, 1980, Unilogic, Ltd.
Doesn't mention More Scribe: Math, More Scribe: Resume, anything in
help, the fourth edition of the Scribe User Manual, or the version 5-7
supplements.
I could not find the SIPB documents in sipbsrc or sipb/doc, although
they still might be lurking somewhere.
> Printed 5/7/90 Release B--April 1987 1
Probably the reason why this man page has all these problems.
Does not mention known bugs, such as hangs on long texts and figures with
no returns, and core dumps on bad bib files.
What should have happened:
It should not have the above problems.
Please describe any relevant documentation references:
man 1 scribe
