 =  All About Adding Comments To Web Pages

INTRODUCTION

  On a number of Ella Associates Web pages you may find a couple of 
  boxes at the end of the page which allow you to enter text. You may also
  see a link at the top of the page saying 'add a comment etc to this document'
  (As in this page itself, if you are reading the HTML version)
  This document states how to use those boxes to add a comment or other 
  type of text to the page. Its very basic. This document (if you are reading
  the HTML version) also contains an example and demonstration of the 
  'add comment' functionality. To use it just click on the link above.
  
  If you want to practice making comments using the comment system, this
  is a good page to do it on. Also to practice the tricks mentioned below.
  But it really doesn't matter.

HOW TO USE THE ADD COMMENT BOXES

  This may seem pretty obvious but I will spell it out anyway.  Click on the link
  at the top of the page which says something like
    'add a comment etc to this document'
  or else page down to the very end of the web-page.

  In the big box which is labelled 'Your Comment' or something similar, type the
  text which you would like to add to the page.

  You dont have to type the date, since it will be added automatically

  In the smaller box, type you name or some signature by which people can
  recognise you. 

  Click the button which is labelled 'Submit your comment' or something similar.
  
  The text you entered will be added to the bottom of the document and will
  be viewable by anyone else who views the page. 
  Thats it.

  If you're just itching to try this out, go to the bottom of the page you
  are reading now (if your reading the HTML version) and knock yourself out.
  (Its an Australian expression meaning, 'go hard')

A FEW INTERESTING TIPS

  If you are making a long contribution to a document, there are some tricks
  you can use to make what type into the 'comment box' become nicely formatted
  when your contribution is viewed in a web-browser.

  For example:
  
   if you type in the comment box a line that is all capital letters, like this...
   MY BOGUS SECTION HEADING                                              o
   
   [actually I cheated by putting a little 'o' at the end of line. Dont do this
   and dont put any punctuation in the heading either. Thankyou]
   then that line will be interpreted as a 'section heading' for the document
   and will be listed in the table of contents like this: 

   MY BOGUS SECTION HEADING
  
   (ignore the previous heading, we're still in the 'INTERESTING TIPS' secion)

   Also:
   If you are typeing some text which you want to appear exactly as you type
   it in the final output (in other words the 'end of lines' will be exactly
   where you put them), then you should surround that text with the  --&gt;&gt;
   and  --&lt;&lt; text on lines by themselves. Heres an example. If you type
   the following into the 'comment box',
      -->>
.      --&gt;&gt;
	this
	  is some
	    very special
	      text
.      --&lt;&lt;
      --<<
    then, when the web-page is generated, it will look like this:
      -->>
	this
	  is some
	    very special
	      text
      --<<
    
    (I have cheated by putting a 'dot' at the very beginning of the first lines.
    dont do this, it will stop the trick from working)
    But if you didn't surround the text with those funny arrows the text would
    appear in the generated web-page like this:
      -->>
	this is some very special text
      --<<
     Approximately, although I'm not really sure exactly how it would
     appear.

    Another tip: If you want a url that you type in your comment to be
    automatically 'hyperlinked' in the resulting HTML page you should type
    it with an "http://" at the front of the URL, like this
    
    -->>
      http://my.interesting.place/
    --<<
    If you do this then when your comment is added and viewed in a web
    browser it will look like this
      http://my.interesting.place/

    And the [*] characters at the front of the URL are a hyperlink to that
    URL (web-page). A quick tip about the tip. Dont put a dot at the end
    of the URL like this
    -->>
      http://this.is.wrong/.
    --<< 
    because it will confuse my dodgy scripts into thinking that the dot
    it part of the URL and therefore the hyper-link will not work
    
    Thats it for the tips. See ya.

COMING SOON

  A super duper bells and whistles system that will allow for more sofisticated
  comments and discussions. Thankyou Steven Spielberg for giving me my
  first break.

TECHNICAL NOTES

  There are two scripts which work in conjunction (but don't have to). These are:
  'plaintext2html-forum.sh' which takes a plain text file, such as the present
  one (if you are viewing the plain text version) and transforms in into a
  'marked-up' or 'formatted' html file. Also this script inserts an HTML form
  in the outputted html page and some links to that form. This form allows the
  document to be submitted to a cgi script known as 'add-comment' which is at
  http://ella-associates.org/cgi-bin/add-comment

  This cgi script inserts the comment written by the user into the text file
  and then regenerates the HTML page based on that text file again using
  'plaintext2html-forum.sh'. The add-comment script then displays the resulting
  Html.

  The idea behind this script is to allow the true 'data' source to be a text
  file. It is envisioned that the text file will be edited by hand as well as
  through the script.

  This script was written as a prototype for a more capable and better
  'collaboration' system for 'ella associates'. This system would use a more robust
  web application serving architecture such as JSP or PHP or Java Servelets rather
  than the rather dodge-brothers approach employed here.  The script currently
  is written as a Bash Shell script which is not fantastic from a security or
  other point of view.

  For more detailed instructions as to how the scripts work, please see the
  documentation headers in the scripts themselves.

  from within the vim text editor (on the local server) you can generate the 'forum html', that is
  the type of web-page you are currently viewing (if you are looking at the
  HTML version), by simply typing ",5" that is comma five. This command generates
  the required HTML from what ever text file you are currently editing.
  
COMMENTS

  Added by: [anonymous], on Thursday, 15 May 2003, 09:18 PM

more tests 

  Added by: [anonymous], on Thursday, 15 May 2003, 09:15 PM

this is appearing 

  Added by: [anonymous], on Thursday, 15 May 2003, 09:14 PM

I wonder if the 'result message' will be inserted 

  Added by: [anonymous], on Thursday, 15 May 2003, 09:12 PM

I wonder if the 'result message' will be inserted 

  Added by: [anonymous], on Thursday, 15 May 2003, 09:11 PM

I wonder if the 'result message' will be inserted 

  Added by: [anonymous], on Thursday, 15 May 2003, 09:06 PM

testing the comment script. A comment is being added 
 but not the text. Got rid of 'fromdos' 

  Added by: [anonymous], on Thursday, 15 May 2003, 08:51 PM

 

  Added by: [anonymous], on Thursday, 15 May 2003, 11:28 AM

 

  Added by: mjb, on Friday, 18 April 2003, 05:54 PM

I have thought about adding a 'contribution title' box to the add comment
script, but considering that no-one uses this comment facility any way,
I probably won't 

  Added by: mjb, on Tuesday, 15 April 2003, 06:00 PM

Here I am attempting to add a comment from Netscape 4.61 Perhaps it passes
form values in some truly odd and  strange way. I dont know 
  Added by: [anonymous], on Saturday, 12 April 2003, 02:57 PM

Well, this test script does / appear to / be working \ but what about
.. @!@$##$^$#%&$%&*^*()^&() strange characters? thats the  question

  Added by: [anonymous], on Saturday, 12 April 2003, 02:59 PM

Its nice to see that weird characters don't kill this script but a comma in the
user name will muck up the formatting of the "Added by" line. See the line
immediately below this for an example of what happens. Its not too catastrophic

  Added by: my name, contains, commas, but why?, on Saturday, 12 April 2003, 03:00 PM

Here is the comma in username test

  Added by: the author, on Saturday, 12 April 2003, 03:01 PM

This comma in the user name is a problem in the script 'plaintext2html-forum.sh'
with the way that that script recognizes comments

  Added by: m.j.b, on Saturday, 12 April 2003, 03:26 PM

It may be interesting to see if anyone does actually use  this system. I think
there will be considerable resistance to it and this is my argument with nick. Yes
it would be nice to have  a powerful well designed system with threading and
a Mysql database and the ability to make coffee as well. But, from a practical
point of view, isn't more realistic to wait to see if people really are going to
use something like this before you build some massive and possibly time consuming
system.   Some people say, built it and they will come but personally in the world
of information tech, I dont think that is quite true. The horse may be lead to
the water but how do you force it to drink? I do not think it is the role of the
programmer to try to dictate to the user how to use a system, or even what sort
of system to use. The programmer must provide options and choices and a gentle
interface which does not scare the user away.

  Added by: mjb, on Saturday, 12 April 2003, 04:03 PM

I wonder if Navigator 4.61 can deal with the slightly dodge html which 'add-comment'
produces. That is, the script puts some body text before the header and hopes
that the  browser will render it.

  Added by: m.bishop, on Saturday, 12 April 2003, 04:08 PM

The answer to the above question was yes. Netscape 4.61, does render the
dodge HTML. The script provides a message to the  user telling them if what
they tried to add to the document was successsfully added or not. This
message actually gets put right after the first <html> tag, so in front
of the header and <body> tag. Never the less all the main browsers seem
to know  what to do with it. I dont know how.  For a longer discussion of
web-collaboration software, of which this is a fairly limited example, please
see http://www.ella-associates.org/alexis-info/resources.html which contains a
link to a doc called something like  'web collab software'

  Added by: mjb, on Saturday, 12 April 2003, 06:02 PM

At the moment the script destroys all the 'paragraphs' that a user types. That
is, everything is mashed together in one big  paragraph. This is a problem
with my script. I could try using a todos | fromdos | etc pipeline which
might solve the problem 
