Firefox PHP

A first crack at user documentation

Posted by Scott Sneddon 
Well, after letting the discussion of documentation for users ferment a little, I've take the first stab at a help file. I'll include it in the body of my next message, but I'll make a few comments here first.

I went the "put it all in one file" route. While this wasn't my preference, it seemed to be what most people thought would be reasonable, and it made getting started easier.

I've made the documentation a php file so that we can include header and footer calls so that the documentation looks like all you other phorum pages.

Eventually I'd like to replace my text links with the appropriate php variables like lPreplyMessage, so that as this changes, or is replaced by icons etc, the help file will be customized to your site, and stay up to date.

I haven't included any images of phorum in action, since I wasn't sure how best to do this, since given how customizable phorum is, my images might not look like yours. So I kept it to words.

Next I'll be adding some docs for the admin functions, and some evangelical words about the world-changing nature of open-source projects.

We need to figure out how to incorporate this into phorum itself. I'd suggest (humbly of course) that there should be a link to the help script on every page in phorum (even if it's only a link to the table of contents). You can get more specific with links to specific anchors within the html (like phorumhelp.php#searching could be the link put into the searching page).

This help file is in english (which is but one of the languages being used for phorums).

I'll offer to be a temporary editor of the help file if people want to contribute sections for the various other functions of phorum (especially the administative functions). I'll include them, and give it a consistent look-and-feel.

It's a start.....

Scott Sneddon
phorumhelp.php
February 11, 2002 03:33PM

<head>
<title>Phorum Help</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</head>

<body bgcolor="#FFFFFF">
<p><?php
include "./common.php";
include phorum_get_file_name("header");
?> </p>
<h1><a name="TOC"></a>Phorum Help</h1>
<blockquote>
<p><a href="#Intro">Introduction</a></p>
<blockquote>
<p><a href="#phoorumlisting">Forum listings, forums versus folders</a></p>
</blockquote>
<p><a href="#ViewingForums">Viewing forums</a></p>
<p> <a href="#ViewThread">Viewing an individual discussion</a></p>
<p><a href="#addtoforum">Adding to a forum</a></p>
<blockquote>
<p><a href="#newtopic">Starting a new thread</a></p>
<p><a href="#addattachment">Attachments</a></p>
<p><a href="#replying">Adding to a thread (replying)</a></p>
</blockquote>
<p><a href="#searching">Searching the forums</a></p>
</blockquote>
<h2><a name="Intro"></a>Introduction</h2>
<p>Forums are also know as threaded discussion groups. Forum contributors post
new topics for discussion in a given forum, and other contributors can respond
to these topics. The term &quot;threaded&quot; refers to the fact that when
someone responds to a forum posting, their response is kept with the original
posting. So, unlike when using e-mail to carry on a group discussion, where
replies to e-mails are scattered throughout your &quot;In-Box&quot; in a threaded
discussion group, the postings on a given topic are kept together thus making
it easier to follow the &quot;thread&quot; of a discussion. A &quot;thread&quot;
refers to an original posting on a given topics, along with all the responses
to that posting. In addition to following a discussion, some forums allow contributors
to add a file, or &quot;attachment&quot; to their posting, and in this way forums
can be used as a means of sharing files, and sharing work. The team of programmers
that has developed the Phorum program uses forums to share ideas and computer
code that results in the evolution of the program itself. Many others use forums
for web-based special interest groups, while others use them to help manage
projects that have many contributors. Forums allow a discussion among members
of a team to be seen by all the members of the team. The forums are also searchable,
which makes forums well suited to getting up to speed on a given topic of interest.</p>
<p><a name="phoorumlisting"></a>Forums tend to be arranged in hierarchies much
like Internet news groups (another form of threaded discussions). Thus, within
a forum on travel, there might a general travel forum, and special interest
forums on eco-tourism, cruises, etc.. Within cruises, there might be forums
on Caribbean and Alaskan cruises. This hierarchy is reflected in the Phorum
program by individual forums, and &quot;folders&quot;, which themselves can
contain forums or further sub-folders. When a forum is listed, the number of
postings to that forum is shown, along with the date of the most recent posting;
a brief description of the purpose of the forum is also listed. Folders have
a description of the forums contained in the folder, you need to click on the
folder to see what forums it contains</p>
<p>In this document, text that appears in quotation marks, and is blue (e.g. &quot;<font color="#0000FF">This
Text</font>&quot;) is meant to correspond to an option that appears on the screen,
and is either a clickable link, or a menu/checkbox etc. This is to be distinguished
from actual links within this document which help you move about in this help
file (e.g. the <a href="#TOC">Table of Contents</a>).</p>
<h2><a name="ViewingForums"></a>Viewing Forums</h2>
<p>To see the topics being discussed in an individual forum, click on the forum
in the forum listing. The forum is shown either in a &quot;Collapsed&quot; view
(where only the first posting of each topic is show), or in an &quot;Threaded&quot;
view (where the topics and the replies to the topics are shown). Topics are
listed with the most recently modified topics at the top of the list, and older
topics sorted below. An old topic may appear at the top of the list if a contributor
has recently responded to that posting. In the &quot;Collapsed&quot; view of
the forum, the subject of the first posting of the thread is given, along with
the number of replies in the thread and the date of the most recent posting
in the thread. </p>
<p>In the &quot;Threaded&quot; view of the forum, the replies to each topic are
listed beneath it in a hierarchical relation. In this view the subjects of the
postings are listed along with the author and date of each posting. For example,
if Bill posts a new topic, and Jean replies to Bill, her posting will appear
beneath Bill's message. We have the beginnings of a thread. Now, Sandra might
also respond to Bill's original posting, and her response would appear beneath
Jean's in the thread. If later Jim adds a posting responding to what Jean had
said, his posting would appear not at the bottom of the list, but tucked underneath
Jean's posting. As the thread develops you can see visually who is responding
to the original posting, and who is responding to the responses. In this way
the &quot;Thread&quot; visually represents the thread of the discussion. You
can switch between &quot;Threaded&quot; view and &quot;Collapsed&quot; views
by clicking on the &quot;<font color="#0000FF">View Threads</font>&quot; or
&quot;<font color="#0000FF">Collapse Threads</font>&quot; link at the bottom
of page.</p>
<p>There is a limit to the number of threads and topics that will be listed on
a single page, and earlier discussions can be viewed by clicking the &quot;<font color="#0000FF">Older
Messages</font>&quot; link.</p>
<p>The &quot;<font color="#0000FF">Go to Top</font>&quot; link takes you up a
level in the hierarchy, from say the &quot;Alaskan Cruise&quot; forum up the
the&quot; Cruises&quot; folder.</p>
<p>The &quot;<font color="#0000FF">New Topic</font>&quot; link is how you start
a new discussion thread in this forum (See <a href="#addtoforum">Adding to a
Forum</a>).</p>
<p>The &quot;<font color="#0000FF">Search</font>&quot; link allows this or all
the forums to be searched for keywords (See <a href="#searching">Searching Forums</a>).
</p>
<p align="right"><a href="#TOC">Table of Contents</a></p>
<h2><a name="ViewThread"></a>Viewing a Discussion Thread</h2>
<p>To view a thread click on the subject for that thread when viewing the forum.
You can view the thread in two ways, either in a &quot;Flat&quot; view or a
&quot;Threaded&quot; view. In the &quot;Flat&quot; view the responses to the
original topic are listed in chronological order. In this view you can read
through all the responses to the original posting in sequence, but you lose
the &quot;Threaded&quot; character of the discussion, since some of the later
responses may not refer to the original posting but to comments made by others
who replied earlier. In our previous example the &quot;Flat&quot; view would
show Bill's post, followed by Jean's, then Sandra's, and finally Jim's posting.
Jim's posting is at the bottom, because it was posted last, but it actually
is referring to Jean's posting, which is further up in the list. </p>
<p>Bill</p>
<p>-- Jean</p>
<p>-- Sandra</p>
<p>-- Jim</p>
<p>To maintain the relationship between the posts (who was replying to whom),
use the &quot;Threaded&quot; view. In this view, the order of the posts would
be different, with Jim's posting tucked underneath Jean's posting, since Jim
was commenting on what Jean had said.</p>
<p>Bill</p>
<p>-- Jean</p>
<p>---- Jim</p>
<p>-- Sandra</p>
<p>When viewing a thread you can switch between these two views by clicking on
the &quot;<font color="#0000FF">Flat View</font>&quot; or &quot;<font color="#0000FF">Threaded
View</font>&quot; link.</p>
<p>You reply to a given message by clicking on the aptly named &quot;<font color="#0000FF">Reply
to This Message</font>&quot; link (see the <a href="#replying">adding to a discussion</a>
section).</p>
<p>In threaded view, use the &quot;<font color="#0000FF">Next Message</font>&quot;
and &quot;<font color="#0000FF">Previous Message</font>&quot; links to move
forward and backward within the thread. The message you are viewing will be
shown in black in the threaded view, the other messages in the thread will be
highlighted as links.</p>
<p>Use the &quot;<font color="#0000FF">Newer Topic</font>&quot; and &quot;<font color="#0000FF">Older
Topic</font>&quot; links to move to news and older postings in this forum.</p>
<p>Click the &quot;<font color="#0000FF">Go to Top</font>&quot; link to return
to the listing of threads in this forum</p>
<p align="right"><a href="#TOC">Table of Contents</a></p>
<h2><a name="addtoforum"></a>Adding to a Forum</h2>
<h3><a name="newtopic"></a>Starting a new discussion topic.</h3>
<p>When viewing a forum, or an individual discussion thread, you can start a new
topic for discussion by clicking on the &quot;<font color="#0000FF">New Topic</font>&quot;
link. This will put up a form for you to fill out. You will need to enter your
name, and your e-mail address; this will allow people to reply to you by mail
if they wish. You are required to enter a subject for your message. The subject
should be something informative, so that it can be picked out from a list with
many postings. Try to avoid subjects like &quot;Help&quot; or &quot;A Question&quot;,
since people will have to look into your message to see if it is something that
they can help with. </p>
<p><a name="addattachment"></a>If the forum allows attachments, there will be
a space for the attachment file name, and a &quot;<font color="#0000FF">Browse</font>&quot;
button. If you want to post an attachment file click on the browse button, and
find the file on your computer. Attachments are a great feature of forums, but
they must be used with care and consideration. Posting large attachments will
take up space on the server, and can be a way for open forums to be attacked
(which is why most open forums don't allow attachments). Posting attachments
made with programs that other users don't have doesn't really serve the purpose
of sharing information, since the other users won't be able to open your file.
Finally, for your browser to know what type if file the attachment is you will
have to adhere to certain naming conventions. You will have to end your file
name with a three-letter extension that specifies the file type. Some of the
supported file-types are shown below (others may have been added to your forum
by your administrator).</p>
<table width="75%" border="1">
<tr>
<td><b>File Type</b></td>
<td><b>Required file name extension(s)</b></td>
</tr>
<tr>
<td>Plain Text</td>
<td>default if no extension is given</td>
</tr>
<tr>
<td>Acrobat Portable Document Format </td>
<td>.pdf</td>
</tr>
<tr>
<td>Microsoft Word Document</td>
<td>.doc</td>
</tr>
<tr>
<td>Microsoft Excel Document</td>
<td>.xls</td>
</tr>
<tr>
<td>GIF image</td>
<td>.gif</td>
</tr>
<tr>
<td>PNG image (GIF alternative)</td>
<td>.png</td>
</tr>
<tr>
<td>JPEG image</td>
<td>.jpg, .jpeg, .jpe</td>
</tr>
<tr>
<td>TIFF image</td>
<td>.tif, .tiff</td>
</tr>
<tr>
<td>XML</td>
<td>.xml</td>
</tr>
<tr>
<td>MPEG video</td>
<td>.mpeg, .mpe, .mpg</td>
</tr>
<tr>
<td>Quicktime video</td>
<td>.qt, .mov</td>
</tr>
<tr>
<td>Microsoft video</td>
<td>.avi</td>
</tr>
</table>
<p>Once a message with an attachment has been posted, the file is uploaded to
the server, and there is no need to keep it in a particular place on your hard
drive. People are not seeing the copy of the file on your computer (which they
wouldn't have access to), so if you make revisions in the file you'll have to
post that new file as a follow-up to you own message.</p>
<p>There is a text area for you to enter your message. What you type here becomes
what is called the &quot;body&quot; of your message, and is what people will
see when viewing your thread. This text is also searchable, so you might want
to put keywords at the bottom of your message so that it will show up when searched
using those keywords.</p>
<p>If this feature is enabled for your forum, you'll see a checkbox to e-mail
replies to this thread to your e-mail address. This is very useful for being
notified when someone replies to your message. The e-mail that gets sent to
you says that someone has replied to your message, and it also contains a link
that will allow youto jump straight from you e-mail, to your thread in the forum.</p>
<p>Finally, there is a button labeled &quot;Post&quot; for submitting or posting
your message to the forum. When you post your message, you will be taken back
to <a href="#ViewingForums">viewing the forum</a> with your message at the top
of the list.</p>
<p align="right"><a href="#TOC">Table of Contents</a></p>
<h3><a name="replying"></a>Adding to a discussion topic (Replying).</h3>
<p>When viewing a discussion topic (a thread), each individual message (posting)
will have a link after it labeled &quot;<font color="#0000FF">Reply to This
Message</font>&quot;. This link will take you to a form very similar to that
for adding a new discussion topic (<a href="#newtopic">see above</a>). The principle
difference between replying and posting a new topic is who your message will
be displayed. We discussed <a href="#ViewingForums">above</a> how messages are
displayed in a hierarchical fashion. Which message you reply to will determine
where in the hierarchy you new message will appear. If you would like to add
your comments to those of other respondents, you should probably click on the
&quot;Reply to This Message&quot; link associated with the first posting in
the thread (the posting that started the discussion). In this case your posting
will appear at the bottom of the list in threaded view, indicating that you
are the most recent person posting in response to the main topic. However, if
there is a particular respondent's posting that you'd like to comment on, then
you should click on the &quot;<font color="#0000FF">Reply to This Message</font>&quot;
link associated with that response. In this way, you are creating a sub-thread
within the main thread. In this case your posting will appear in the middle
of the threaded view, beneath the respondent's post that you wished to comment
on. </p>
<p>For an explanation of the fields in the form, and advice about attachments
see the section on <a href="#newtopic">starting a new discussion</a> above.</p>
<p align="right"><a href="#TOC">Table of Contents</a></p>
<h2><a name="searching"></a>Searching forum discussions</h2>
<p>The discussions in a forum can be searched in much the same way as using a
search engine. You enter one or more keywords to search for, and the forum is
searched for these keywords; the results are given in the order of how well
they match your keywords.</p>
<p>There are several options that dictate how your search gets done. You can limit
the search to just a single forum, or to all the forums on the server using
the drop-down menu options &quot;<font color="#0000FF">Search This Forum</font>&quot;
or &quot;<font color="#0000FF">Search All Forums</font>&quot;. You can limit
your search to just the most recent postings, or to all the postings using the
drop-down menu options &quot;<font color="#0000FF">Last 30 Days</font>&quot;,
&quot;<font color="#0000FF">Last 60 Days</font>&quot;, &quot;<font color="#0000FF">Last
90 Days</font>&quot;, &quot;<font color="#0000FF">All Dates</font>&quot;. You
can select whether &quot;<font color="#0000FF">All Words</font>&quot;, &quot;<font color="#0000FF">Any
Words</font>&quot; or just your &quot;<font color="#0000FF">Exact Phrase</font>&quot;
need to match using the drop-down menu with those names. Finally, you can determine
which part or parts of a posting will be searched using the &quot;<font color="#0000FF">Author</font>&quot;,
&quot;<font color="#0000FF">Subject</font>&quot; and&quot; <font color="#0000FF">Message
Body</font>&quot; checkboxes.</p>
<p align="right"><a href="#TOC">Table of Contents</a></p>
<p>&nbsp;</p>
<p><?php
include phorum_get_file_name("footer");
?></p>
</body>
Re: phorumhelp.php
February 12, 2002 11:33AM
I've added this help script to my own phorum installation, and I recommend the following approach for incorporation into future releases of phorum.

1) I've saved the above php script in phorumhelp.php

2) I've added the variable

$lHelp = "Help";

to the /lang/english.php file

3) I've added the variable

$PHORUM['help_page'] = 'phorumhelp';

to the admin/settings/forums.php file

I've then used calls to addnav() to add a Help option to the following navigation bars.

4) in index.php: add at end of navigation section
// add help menu
addnav($menu,$lHelp,"$help_page.$ext");

//////////////////////////
// END NAVIGATION //
//////////////////////////

5) in list.php: add after the "New Topic" section
// New Topic
addnav($menu1, $lStartTopic, "$post_page.$ext?f=$num$GetVars");

// Help Menu
addnav($menu1,$lHelp,"$help_page.$ext#ViewingForums");

6) in read.php: add before search link
// Help
addnav($menu1,$lHelp,"$help_page.$ext#ViewThread");

// Search
addnav($menu1, $lSearch, "$search_page.$ext?f=$num$GetVars");

7) in search.php: after Go To Top
// Go To Top
addnav($menu, $lGoToTop, "$list_page.$ext?f=$num$GetVars");
// Help
addnav($menu,$lHelp,"$help_page.$ext#searching");


I continue to work on the content of the help file, and will post new versions here.

Scott Sneddon
<b>Re: phorumhelp.php</b>
February 15, 2002 03:58PM
<b>Re: phorumhelp.php</b>
February 16, 2002 04:36AM
<HTML>ok, i fixed it up a bit :)</HTML>



Brian - Cowboy Ninja Coder - Personal Blog - Twitter
<b>Re: phorumhelp.php</b>
February 18, 2002 03:34PM
<HTML>any comments???</HTML>



Brian - Cowboy Ninja Coder - Personal Blog - Twitter
curious_cat
Re: phorumhelp.php
February 22, 2002 12:11AM
also i added



<h2><a name="markup"></a>Accepted Markups instead of HTML</h2>

<li><i> Create a url that is linked.</i>
<br>[www.realm.com]
<p> </p>
<li><i> Link text a url to [www.realm.com<];
<br>WebSite
<p> </p>
<li><i> Create a linked email address</i>
<br>email@address.com
<p> </p>
<li><i> Create an image tag that will show that image.</i>
<br>
<p> </p>
<li><i> Makes the text bold, underlined, or italicized.</i>
<br>Bold Text
<br>Underlined Text
<br>Italicized Text
<p> </p>
<li><i> Center text </i>
<br>
Centered Text

<p> </p>
<li><i> This will indent the text inside the tags.</i>
<br>
Quote

Does this quote text?
<p> </p>
<li><i> Phorum will also automatically link urls that are inside <>.</i>
<br> &#60;[www.realm.com];
what happened to phorumhelp.php?

I take it that
include "./common.php"; defines the function
include phorum_get_file_name("header");

So there is no user documentation unless you've installed phorum?

You might want to try another approach to putting up some explanation of what phorum actuaklly IS.
Re: A first crack at user documentation
July 21, 2002 11:09PM
it just needs to include a header, so it would look "blended" in.



Brian - Cowboy Ninja Coder - Personal Blog - Twitter
My only comment would be to add a section on the installation of postgresql - I believe everyone needs to know they need to change the db name at the top of common.php to postgresql65 manually and that otherwise the installation process will stop with a blank screen after the database selection. They might also need to change the postgresql startup script (esp on Redhat) to add the -i option so that internet socket connections are allowed- otherwise they'll receive a strange message indicating that the installation script can't contact the database even though they might be able to access it via psql.

Justin
What happened to phorumhelp.php indeed. After putting some effort into user documentation (not installation instructions), and describing in detail how to implement these in phorum, I've seen no indication that this has been added to the phorum distribution.

User help is important, there should be a help link on every page in phorum.

What has happened to a phorum-wide user documentation? Has someone developed a better approach to helping new users understand how to use (not install) phorum?

Scott Sneddon
hans-jürgen
Re: A first crack at user documentation
February 08, 2003 06:07AM
Scott Sneddon wrote:

> What happened to phorumhelp.php indeed. After putting some
> effort into user documentation (not installation instructions),
> and describing in detail how to implement these in phorum, I\'ve
> seen no indication that this has been added to the phorum
> distribution.
>
> User help is important, there should be a help link on every
> page in phorum.

Hi Scott, I would just like to thank you for your efforts. :-) I suggested implementing your help script to [www.audiocoding.com] to the admin today, and hopefully he will do so. By the way, why do the smilies no longer turn into icons automatically with v3.4?

Re: A first crack at user documentation
February 08, 2003 12:29PM
I don't know what you are talking about with the smilies.
it depends on the way they were implemented before on "your" phorum. it only worked through the replace-plugin or with own hacking so you'll have to transfer your configuration to the new version too.

hans-jürgen
Re: A first crack at user documentation
February 09, 2003 04:49AM
ts77 wrote:

> it only worked through the replace-plugin or with own
> hacking so you\'ll have to transfer your configuration to the
> new version too.

Thanks. By the way, will the user help page from Scott be implemented in a new version of Phorum maybe?
First of all - thanx for the program. I saw it, got it and put it to work in a few minutes.

But it is also true, that somebody needs to work more on the documentation.
It was very nice when it self asked that I changed permissions on a file. But it did not tell me where that file was to be found ( - or for the beginners how to do this at all).
For the beginners it might also need some more info on how to make the database, but that was ok for me.

.tom Vilmer Paamand
Re: &lt;b&gt;Re: phorumhelp.php&lt;/b&gt;
July 27, 2003 11:21AM
Vulpes wrote:

> <HTML>[phorum.org];
>

I'm getting a 404 on that. Where is it now?

Hi,

This is great, but I believe you also need to add the line
// help file $PHORUM['help_page'] = 'phorumhelp';
to the forums.bak.php file.
Sorry, you do not have permission to post/reply in this forum.