                                                                = Tricks for Editing a Document


* Introduction

  This file gives an introduction to the web-editing language. This 
  is supposed to be a simple set of rules that allow you to create
  documents without knowing HTML or any other type of 'markup' language.
  The document you are reading now is an example of a document that 
  has been written using these rules. 

  But Wait- before you think to yourself: "Im not interested in learning
  yet another / my first markup language. I just want to write some
  documents and publish them as web-pages". Before you say to yourself
  those words, be advised that this system was designed with you in mind.
  That is, you dont have to learn any rules at all in order to write 
  documents and publish them as web-pages. All you have to do is type.
  (Voice recognition integration is a possible future feature).

  For example, if you type the location of another web-page in your
  document, like this
  -->>
    www.geocities.com
  --<<
  It will be displayed in the web-page like this: www.geocities.com
  
  So the language rules only need to be learnt if you want to use 
  'special' features, like making section headings that get automatically
  put into tables of contents, or making lists which are numbered with
  numerals or with alphabetical characters.

  Another simple way to learn the rules of the language is to click on
  any of the web-pages which have a link which says something like
  'Edit this page' [self-edit-link]
  If you click on one of these links you will be transported to another
  webpage which contains the contents of the document displayed in a 
  'textbox' or 'textarea'. This is just a 'form' element which you can
  use to edit the contents.  When you have finished editing the contents
  of the document click on one of the buttons which says something like
  'save file'. Then click on the link which says 'View the web-page of
  this Document (!)' and then click the refresh button on your browser.

  (Note: this process will be streamlined soon so that not so many 
   clicks are required).
   

  

  See also the 'faq' link:///refurb/docs/system-faq.html
  and the 'document index' link:///refurb/docs/documents.html
  You can "edit this page" [self-edit-link]

* Sections and Headings in Documents
 
  To make the main heading for a document put an equals sign '=' as the 
  first character for the line.

  To make a section heading use a star character "*" as the first 
  character on the line. To see a practical example of this, click 
  on the 'Edit this page' link above. These section heading may be 
  collected automatically into a table of contents which is placed
  at the top (and maybe bottom) of the web-page and whose items
  are hyperlinks to the respective headings in the document. This is 
  designed to make it easy to write informative style webpages where
  the information is more important than the visual appeal of the 
  page. These sorts of pages may be useful when writing technical
  documentation (such as, for example, the current page).

  Originally, I used all Upper Case lines as section headings since they
  are easier to read in a text file, but it was easier to write the 
  transformation using the * character syntax. However at some stage 
  I will probably go back to the all upper case sytax in the future.

* Lists

  This system uses automatic transformations so that you dont have 
  to worry about HTML which is a very messy affair and tends to 
  interfer badly with the creative process of great minds. If you look
  at the text for one of the documents that already exist you will get
  an idea of how the text gets formatted when it is transformed
  to HTML and here is list of features
  
  To make an ordered list of things which are labelled with
  sequential number or letters type something like this
  -->>
     a- Go shopping
      - Buy some consumable items
      - Look at all the people going by
      - Think about why people drink alcohol
  --<<

    When you save this and look at it in the web page, you should see
    something like:
  
     a- Go shopping
      - Buy some consumable items
      - Look at all the people going by
      - Think about why people drink alcohol

  A blank line ends a list. To make an unordered list type
  use u- instead of a- To make a numbered list use 1- To make a list
  which has absolutely no marker use u--  I should say that this relies
  on css working in your browser. 

* Automatic Hyperlinks

  Text in the source document that looks like a URL is 
  automatically hyperlinked. for example, if you type:
  -->> http://wagga-cwc.org.au --<<
  it comes out like this http://wagga-cwc.org.au 

  Another trick is to enclose the URL in brackets like this 
  -->> [.http://wagga-cwc.org.au] --<< (leading dot to stop rendering)
  which should appear as a kind of footnote reference except that
  it isnt a footnote like this [http://wagga-cwc.org.au]

  Or you can type:
  -->>
    "The Mission Australia Work Center" http://wagga-cwc.org.au  or
    'The Mission Australia Work Center' http://wagga-cwc.org.au  
  --<<
  and it will come out like this "The Mission Australia Work Center" 
  http://wagga-cwc.org.au 

  To link to a local resource, (that is; a web-page or other file which
  is located on the same server as the page which you are editing) type:
  -->>
    link:///refurb/  or
    'The pc recycle site' link:///refurb/  
  --<<

  which in the HTML page it will look like this:
    link:///refurb/  or
    'The pc recycle site' link:///refurb/  

  All these types of linking mechanisms can be modified by putting 
  an exclamation mark in front of the URL part of the link. This 
  causes the linked to page or file to be opened in a new window.
  An example of this would be:
  -->>
   'Go to the Home Page' !link:///
  --<<

  This should result in the following: 
  'Go to the Home Page' !http://wagga-cwc.org.au

* Other patterns
 
  If you type -->> press the enter key --<< it should get turned into
  an HTML button which doesnt actually do anything but which is designed
  to make the document a little more interesting to read. 
  So for example you could type press the enter key
  Especially, I think this feature would be useful when writing instruction
  manuals  for the use of software. Actually, I wanted to create a document 
  type which would be called a howto and which would specifically cater
  for this type of information.
  
  If you type warning: or note: then these patterns get marked up 
  slightly differently to draw attention to themselves. This is a very
  english centric sort of thing, but I dont suppose it would be difficult
  to include patterns from other languages, link aviso: or avis:

  File names should look a bit different from other text. So if you type
   /path/to/a/file.html  then it should become some type of fixed pitch font
  which is served quite well by the <tt> and the <code> html tags.
  This is implemented.

  You can make something called ascii icons by typing something like
  -->> ascii-icon:spades http://www.google.com --<< and hopefully this 
  should get transformed into something like this
  ascii-icon:spades http://www.google.com 
  
  I dont know if this is really useful but I liked the idea at the time.
  The thing after the ascii-icon: pattern can be any html entity name or
  number. Another thing which is possible at the moment is
  the use of ascii function symbols which I misnamed as ascii-menu-items
  So if you type -->> [ascii-menu-item:search.] --<< then it should come
  out as [ascii-menu-item:search] (I put a dot it the above to stop it
  rendering)

  The supported keywords are search, view-file-lines, browse-folders,
  web-edit, file-edit, copy, ... Each of these functions does a specific
  thing with the file currently being edited. For example the copy
  function allows the current file to be copied or renamed. 

  The system also understands a special type of link which is the 
  self edit link. So if you type 
  -->> "edit page" [self-edit-link.] --<<
  (Extra dot to stop it rendering) Then this gets turned into
  a hyperlink with the text 'edit page' and which allows the user to
  edit the document using the webpad browser editor. For example:

  "edit page" [self-edit-link]


* How All This Works

  When you click save after editing a document, the new contents of the 
  document are sent back to the Web-Server by your web-browser. The 
  web-server saves the new contents of the file and also at the 
  same time creates an HTML file (web-page) by automatically transforming
  the text file which you have edited, using a set of simple 
  transformation rules. This web-page is given the same name as the 
  text document but with an HTML file name extension. So for example, if 
  you edit the file called 'wiki-language.txt', when you click save 
  a web-page is created which is called 'wiki-language.html'. Using your
  web-browser you can view either of the two files, but the HTML file
  will be more visually appealing and probably easier to use, since 
  it will contain hyperlinks and images.


* Technical Notes:

  The HTML generated is currently only compatible with the HTML 4 
  standard. This may be upgraded to XHTML in the future. The html could
  definitely be improved but at times it is very difficult to ensure
  that it is true XML since this system uses a simple regular expression
  parsing and transforming system. Since Regular expressions are 
  finite state machines without a stack it is impossible to parse 
  nested structures properly. To do this would require Backus Naur 
  Form grammers and to write the thing in something like Yacc and 
  Lex or their many variants. I would be interested in doing this, but
  probably wont, since regular expressions are so convenient.
  

* A Warning

  If you hit the escape key when you are editing the contents of a 
  document using the browser editor, you will probably lose all the 
  changes which you have made to the text (If you have not clicked the 
  save button at all). I will probably try to write some Javascript
  to prevent this frustrating event.


* Other Things

  'htp' http://htp.sf.net .This 
  seems to produce nice consistent looking pages. It calls itself
  an HTML pre-processor. But it doesnt eliminate the need for HTML entirely

  Est pgina est disponible en "Castellano" 
  link:///refurb/docs/wiki-language.es.html



[*document*]                                                                                                                                                                                        