User
Manual Home
General
-------
This
web-based application will allow you to create documents of your choice, revise
them as frequently as you would like, view all revisions in HTML format and
store them for later work. You may also search across documents for keywords
(bottom box). There is also search for document name (top box), if you know any
part of the name. This includes a regex search
Navigation
----------
The
home screen is a simple form with one data input line called: My topic, and two
controls: 1) View/Edit option (only one can be selected at a time) and 2)
"revision" check box. When "revisions" is checked, it is
intended to view only, so even if you have selected Edit + revisions, your next
screen presents the revisions for the topic entered, for the purpose of view
only.
In
addition to selecting topic by typing its name, you may select a topic that was
recently edited, via the drop-down box which is underneath the "Topic
Name" box.
The
recent edit list gets updated after a new revision of a topic is saved (or a
brand new topic with its first revision of course).
If
there is a topic in the Topic Name box, and the user selects from the 'recent'
list, the topic from the recent list will be displayed, and upon return 'home',
that newly selected topic will be displayed in the Topic Name input box. The
same is true for edit. In other words, selecting from the 'recent' list takes
precedence over the value entered in the topic name box.
There
is another option, which is the SEARCH option. On the right hand-side of the
screen you can type a keyword in the text box and hit the <SEARCH>
button.
Another
way to select a topic, is to choose it from the 'Popular topic' list and press
GO. That can also be combined with View/Edit or revisions (usage is on the
screen)
One
more item is the Photo upload button. This button takes the user to a very
simple screen (HTML based) that allows to upload photos from the user's PC to
the server.
DATA
persistence
----------------
I
try not to disturb the user by forcing him/her to enter data unnecessarily, so
for that reason, many times data values are carried between screens. For
instance, if we perform a search across topics and return HOME, the last
searched keyword is still displayed in the search box. There are too numerous
instances of this type to mention in this small handbook, however, by using the
application, it will become apparent that this convenient feature is there.
HOME
screen
-----------
The
possible actions are:
will display
--------------------------------------------------------------------------------------------------------------------------
a.
View + existing topic
Hit <submit> | HTML of the most recent revision
b.
View + none existing topic
Hit <submit> | error message
b.
Edit + existing topic
Hit <submit> | Text (edit) of the most recent rev.
c.
Edit + none existing topic
Hit <submit> | Edit screen with empty text-area
d.
view + existing topic + check mark in 'revisions' Hit <submit> | Revisions list screen, to choose
e.
View or Edit + topic selected from Recent Edits Hit <submit> | Either Edit screen or view
f.
Enter a keyword in the search field
Hit FIND
| HTML page with all links to topics
|
where the keyword is found.
g.
View or Edit + topic selected from popular list
| Either Edit screen or view for the
and press: GO
| topic selected from the list
h.
A topic from the popular list + revision checked
| Revisions list screen, to choose
i.
Upload photos
| screen to facilitate photo upload
j.
Existing topic and Hit <delete>
| Warning screen with OK or Cancel [OK deletes entire topic]
VIEW
screen
-----------
This
screen will show the text of the topic after all the interpretations discussed
in the Edit screen, including the showing of images, bulleted lists etc. This
screen has a button that allows the user to switch into 'Edit' mode, for the
currently viewed document. We can also cancel from this screen and that takes
us back to the home page.
EDIT
screen
-----------
There
are several conventions that allow the user to create various text (and image)
effects. As per the initial rules, the symbols & < and > are
converted to their HTML counter-parts. In order to make text bold, we have to
surround it by asterisks: *bold text* and to italicize text we surround it by
underscores: _This will show in italics_
A
blank line gets interpreted into a <p></p> HTML tags. In order to create a heading
the line must start with three dashes, followed by 1 to 3 'plus' signs,
followed by a space. Whatever comes after, on the same line is used as the
heading. The number of pluses determines the size of the text, where 1 is the
largest (H1), so: ---+ Heading will be interpreted as:
<H1>Heading</H1>
Any
reference to a topic that already exists (if any word in the content of a topic
is a name of another topic), when viewing the page, that becomes a link, by
which we could 'jump' to the view of that particular topic.
Bulleted
list - in order to create a bulleted list, the user would designate a symbol
that looks like this :x: , where x
can be 'c' (for circle), 'd' for disc or 's' for square. Those are the
different symbols that can be used for the bulleted list. That sequence is on a
separate line from other text. The following lines will each be a bullet and
the list ends by having two slashes at the beginning of another new line. For
example:
:d:
Tough
economic times
World
depression
social
clashes
//
Interpretation
.
Tough economic times
.
World recession
.
social clashes
Image
support - In order to enter an image into a document, the code that needs to be
added is :img:url:here comes the
complete url of the image: (and
ends with a coon)
Example
:img:url:https://cs.nyu.edu/~js3104/cgi-bin/unixtool/images/j.jpg:
PREVIEW
screen
--------------
This
screen is displayed if after editing a topic the user selects 'preview'. It
displays the text of the topic just edited with all the HTML interpretation (as
described in the view page) and allows 3 actions: (1) cancel - Goes back to the
'edit' screen with the text intact in the text area box. (2) save Ð will save a
new revision of the topic to the database. (3) save + provide an e-mail in the
text box, will both save the revision and send an e-mail notification about the
topic being edited to the address specified.
REVISIONS
screen
----------------
If
the user checked off 'revisions' on the home page, a screen (this one) would be
displayed, in which the topic is a 'read only' field and on the right hand side
of the page, all the revisions of that topic, numbered from the highest
(latest) revision down to zero (first revision).
On
this screen there are three possible functions. The first is selecting one
revision, and hitting 'view'. This will get that specific revision and will
display it on a page called: REVISION VIEW. The button ÔrevisionsÕ from this
page, will bring us back to the list of revisions (REVISIONS page), from which
the user can select another revision to view.
The
second function, allows us to select two revisions (if there are), and hit
'compare' , and this will bring us to a page that compares the two selected
revisions side by side. See more on that in the 'COMPARE' screen description.
No more than two revisions can be selected for comparison.
The
third function is DELETE a revision. Select one or more revisions (any that's
on the list) and press the delete button. If there are more revisions left for
this topic, the page automatically updates the new list and their numbers to
reflect the new number of revisions left. If, on the other hand, no more
revisions are left, the topic is also removed and the application goes back to
the home page, announcing the topic name that has been discarded.
Note
that I do not update the 'recent edit' list upon delete. This is by design not forgetfulness,
as many other apps (like MS Word), leave the history of documents opened. I do,
however keep the recent list 'clean' of duplicates, and it contains up to 6
entries.
COMPARE
screen
--------------
This
page is activated when we compare two revisions of the same topic, as discussed
under the REVISIONS screen.
It
presents that two selected revisions, the older on the left and the newer on
the right with their corresponding revision number (human readable not EPOCH
time).
At
the bottom of the page, an 'ed' script is added such that basically it can be
run to move from the older revision to the newer. I used this method as a
concise way to present the changes between revisions, granted those changes are
not so dramatic (but more subtle such as versions of program codes).
SEARCH
functions
-----------------
The
search takes the keyword and does a 'generic' search. In other words, even if
the keyword is part of a word (string), that would be considered a match.
It
searches across all topics and each and every revision of every topic (which
can help identify at what point this text was added to the topic).
It
returns back the topic and revision in which the keyword has been found. It
also returns all the lines in which it appears (perhaps an overkill for a
common search). It also returns the number of times a match occurred in the
particular topic and for that revision.
The
ranking of the search is simply by number of matches of the keyword
(descending). I give more importance to documents where the keyword appears
more than others (as do many search engines).
The
displayed search, contain links to the appropriate topic and its relevant
revision, so the user can immediately view that page.
If
we follow one of the links of the search, it will bring us to the
"revision view" because the search is refined to the level of
revision. In that case, after viewing the 'found' topic/revision, upon
'cancel', the app would take us back to the list of revisions for the same
topic. To view another topic/revision found through the search, we can always
hit the browser's "back" button, as is the case with Google search.
The
other type of search (with the top box) is in case the user remembers only part
of the topic's name. This search will bring back a list of links to topics with
names similar to the searched for string. If the user is familiar with regular
expression, this becomes a powerful tool. For instance, to view a list of all
topics type: .* (all topics with
zero or more characters as a name).
DELETE revisions
I
allow the user to delete any revision of any topic (1 or more at a time). This
feature is also on the screen called REVISIONS and described in more detail
above.
DELETE entire topic
This
option lets you (from the home page), delete an entire topic with all its
revisions with one single operation. Since this is a powerful and potentially
destructive (if erroneous), a confirmation screen is given. The confirmation
allows the user to change her/his mind or to confirm the deletion.
Most POPULAR (viewed) topics
The
way this feature works, on the home page there is a drop-down box, which
displays the topic that has been viewed the most, a space, and the number of
times the topic has been viewed.
The count of the views starts from 0 (in the spirit of Unix again), 0 means it
has been viewed once.
I
consider viewing in two cases: (1) view is requested specifically (not preview
before save), and (2) A request to view a specific revision has been made.
If
the user presses the arrows, a list opens, and the list shows the topics in
order of popularity of viewing (always accompanied by the number of times
viewed). This list is dynamic and gets updated right after the viewing and
returning to the home page.
The
user can then select either Edit or View to go to the appropriate screen as
described above. The user may also choose to check revisions for the popular
topic selected and that, as expected, will display the revision list screen.
E-mail notification
I
provide an optional input text field on the preview screen, right before an
update is made to a new topic or a new revision of an existing topic. Since it
is optional, I do not verify or validate this e-mail address, and I use
/usr/bin/sendmail for this.
PHOTO Upload
A
simple button on the home page takes us to an even simpler form that allows
uploading a photo from the local PC to the server's images folder.
Miscellaneous
1)
Does not allow to save the same revision more then once.
2)
Providing a 'reset' button to erase the last thing typed before preview has
been requested on
the EDIT page.
3)
When a topic is viewed, on the top right hand corner the last modification
date/time is
displayed.