dickie@schaefer.math.wisc.edu (Garth Dickie) (12/09/90)
I am considering putting together an application designed for the rapid
presentation of programmer's documentation using very little memory, and would
like to have people's thoughts on the matter.
RATIONALLE:
I prefer to have documentation available online for use while programming.
I believe this is fairly common among people who have programmed on a unix
machine (comments?). Programmer's documents for the macintosh currently are
available online mostly in wordproccessor formats. The apparent reason for
this is that people wish to have pretty hardcopy. This is a pain for several
reasons. First, I don't own MacWrite, and don't want to; neither do I own Word
(blech!). Conversion to your native wordprocessor format is fine if you have
one that can do so quickly, while preserving all of the pretty formatting that
exists in the original. I have yet to see a wordprocessor which can really
claim to do this, and in fact some large documents cause WordPerfect and/or
FullWrite to hang forever -- this sucks. Secondly, wordprocessors eat memory
for breakfast, lunch, and dinner, with snacks in between. I don't usually have
the memory for one while programming, as compilers w/debuggers tend to do the
same. I would like to remedy at least part of this problem.
PROPOSED DESIGN GOALS
The primary goal is the presentation of documentation, without using excess
memory or time, in a convenient, legible manner. As there will normally be no
need to edit the documents, the presentation program need have no editing
capabilities beyond selection and copying. Thus there must be associated
software to produce these documents. (More on this later). It must be
possible to include PICTs in the stream of text, if this is to be useful for
TechNotes. Also, there must be a way of distinquishing code examples from
explanatory text.
I am unsure about whether to include printing in the primary goals. This
is intended for the on-line use of documentation, not for printing lovely
hardcopy. However, it would seem shortsighted to leave this out.
As a secondary goal, I am interested in being able to display only one set
of code examples. For example, I might wish to read a TechNote with only the
code examples written in C visible, with an option to display them in Pascal
instead, or to display the complete text.
Also as a secondary goal, it would be convenient to be able to search for
strings in either the text as a whole or only the code examples.
PROPOSED USER INTERFACE
In this age of MultiFinder, a DA is out of the question. I would prefer
the standard document-oriented application interface, but with a much-simpler
File menu. Of course the full Edit menu is only provided for in-layer DAs, as
Undo, Cut, Paste, and Clear would never be available.
File: Open.../Close/-/Page Setup.../Print.../-/Quit
Edit: Undo/-/Cut/Copy/Paste/Clear/-/Select All Code
Find: Find.../Find Again
Code: C Examples/Pascal Examples
Rather than full styles, it would make sense to simply display all normal
text in one font, all code in another. As this is primarily for on-line use,
the natural choices would be Geneva and Monaco, both 9pt. This may be too much
of a restriction. Pictures as used in the TechNotes appear only centered on
their own line. This also simplifies many things in the programming model, but
DTS would have us listen only to the user, so is this too restrictive? Most
text could be forced to left-justification, if every picture was given a
one-line title centered with it, and perhaps in boldface.
User selection must be allowed for copying of code examples. So to what
extent should selection be allowed? There is a clear model for selecting a
block containing text, code, and pictures, but what goes into the clipboard on
export? I would like to restrict an individual (possible discontinuous)
selection to consist of either all text, all code, or a single picture, but as
with removing printing, this could be considered pedantic/short-sighted.
IMPLEMENTATION
Most of this part is fairly trivial for the display application, given no
memory constraints. However, I would like to constrain memory usage to perhaps
only 32K. This is simplified quite a bit by the fact that there is no editing
going on. Thus it would be permissible to have a line index at the head of the
file, and to never load more than the blocks needed. Similarly, PICTs can be
read piecewise from a file using a GetPicProc. Given a directory of the data
fork listing text blocks, PICTs, and tuples of parallel code blocks, display
becomes fairly easy, especially if the index is by (32-bit) vertical coordinate.
ASSOCIATED TOOLS
The major sticking point is coercion of documents into this format. It is
within the goals to allow separate utilities for conversion; in fact, this
would be the best division of tasks, and could allow the conversion engines to
be ported to unix for fast conversion before download. However, it is not
enough to convert only from publicly documented interchange formats, as the
documents in question are distributed in wordprocessor formats for programs
which are unavailable. This is where I get stuck. I can see how to use
the decoded information to decide what is code and what is not, given that
there is a font change or something of the sort, etc, and could write an engine
to convert a stream of 'text, font change, text, PICT, ...' into the desired
format; I just don't really want to wade through internal formats for programs
which are not readilly available to me given only documents whose contents I
can guess.
THE POINT OF THIS ARTICLE
Is there something out there which already accomplishes this? If not, are
there people interested in helping to design a file format, etc? Are there
people interested in writing conversion programs? Comments on all aspects are
welcome, to the address below; I will summarize to the net given any response.
--
-------------------------------------------------------------
Please insert :-) where appropriate for prevention of flames.
Garth A. Dickie dickie@macduffe.math.wisc.edu