none
authorPeterThoeny <PeterThoeny>
Sat, 1 Feb 2003 12:46:00 +0000 (12:46 +0000)
committerPeterThoeny <PeterThoeny>
Sat, 1 Feb 2003 12:46:00 +0000 (12:46 +0000)
TWiki/IncludeTopicsAndWebPages.mdwn
TWiki/TWikiInstallationGuide.mdwn
TWiki/TWikiTemplates.mdwn
TWiki/TWikiTopics.mdwn

index 8b96732..02e80bc 100644 (file)
@@ -1,6 +1,6 @@
 # <a name="Include Topics and Web Pages Usi"></a><a name=" Include Topics and Web Pages Us"></a> Include Topics and Web Pages Using <code>**%INCLUDE\{...\}%**</code> Variable
 
-Use the <code>**%INCLUDE\{...\}%**</code> variable to embed the content of another topic or web page inside a %WIKITOOLNAME% topic. The whole content or only parts of a page can be included.
+Use the <code>**%INCLUDE\{...\}%**</code> variable to embed the content of another topic or web page inside a %WIKITOOLNAME% topic. The whole content or only parts of a page can be included. If needed, set a proxy server in [[TWikiPreferences]].
 
 <div>
   <ul>
index fa1ba3f..3b6f3cf 100644 (file)
@@ -14,7 +14,6 @@
         </li>
         <li><a href="#Additional Server-Level Options"> Additional Server-Level Options</a><ul>
             <li><a href="#Enabling Authentication of Users"> Enabling Authentication of Users</a></li>
-            <li><a href="#Adding a New Web"> Adding a New Web</a></li>
           </ul>
         </li>
         <li><a href="#TWiki File System Info"> TWiki File System Info</a></li>
@@ -222,24 +221,6 @@ With your new TWiki installation up and running, you can manage most aspects of
 - Edit the [[TWikiPreferences]] topic in the TWiki:TWiki web to set access privileges.
 - Edit the [[WebPreferences]] topic in each web, if necessary: set access priviliges.
 
-<a name="CreateWeb"></a>
-
-### <a name="Adding a New Web"></a> Adding a New Web
-
-To create a new web:
-
-1. **Create** a new web data directory under `twiki/data` and check the file permission of the directory.
-  - Use a name consisting of characters `A..Z` , `a..z` but **_not_** in [[WikiNotation]]. (The name should start with one (or more) uppercase letters, but have no uppercase letters after the first group -- if it starts with a lowercase letter or is a [[WikiWord]], some features of TWiki will not work as expected.)
-2. **Copy** all files from the `twiki/data/_default` directory to the new data directory, preserving the original files' owner, group and permissions (on Unix, use `cp -p`). The data files must be writable by the owner the CGI scripts are running on (usually, `nobody`).
-  - %T% **HINT:** You can set permissions of `.txt` and `.txt,v` files to `-rw-rw-rw-` (666) and then edit the topic using your browser; RCS will restore the file permissions correctly when saving the topic.
-3. **Add** the new web to the web list (visible in the upper right corner of each topic) by editing the site-level preferences, [[TWikiPreferences]]:
-  - Add the new web to the `%WIKIWEBLIST%` variable.
-4. **Update** the web settings by editing the WebPreferences topic of the new web:
-  - Customize the `%WEBTOPICLIST%` variable to contain the web-specific links you prefer.
-  - Set the WEBBGCOLOR variable to a color. The number represents the unique color for the web.
-  - Set Plugins, access privileges, custom variables, other web-level options (ex: `%WEBCOPYRIGHT%` can be set for an individual web).
-5. **Test** the new web: view pages, create a new page.
-
 That's it for a basic new web set-up!
 
 Optionally, you can also:
index 52a2042..f67a4a7 100644 (file)
@@ -8,6 +8,7 @@
             <li><a href="#Master Templates"> Master Templates</a></li>
             <li><a href="#HTML Page Templates"> HTML Page Templates</a></li>
             <li><a href="#Template Topics"> Template Topics</a><ul>
+                <li><a href="#Edit Template Topics and Variabl"> Edit Template Topics and Variable Expansion</a></li>
                 <li><a href="#Template Topics in Action"> Template Topics in Action</a></li>
               </ul>
             </li>
@@ -150,6 +151,44 @@ All template topics are located in the TWiki web. The [[WebTopicEditTemplate]] c
 2. WebTopicEditTemplate in the current web
 3. WebTopicEditTemplate in the TWiki web
 
+#### <a name="Edit Template Topics and Variabl"></a> Edit Template Topics and Variable Expansion
+
+The following variables get expanded when a user creates a new topic based on a template topic:
+
+> <table border="1" cellpadding="0" cellspacing="0">
+>   <tr>
+>     <th bgcolor="#99CCCC"><strong> Variable: </strong></th>
+>     <th bgcolor="#99CCCC"><strong> Description: </strong></th>
+>   </tr>
+>   <tr>
+>     <td><code>%DATE%</code></td>
+>     <td> Current date, e.g. <code>29 Jun 2010</code></td>
+>   </tr>
+>   <tr>
+>     <td><code>%WIKIUSERNAME%</code></td>
+>     <td> User name, e.g. <code>Main.admin</code></td>
+>   </tr>
+>   <tr>
+>     <td><code>%URLPARAM{"name"}%</code></td>
+>     <td> Value of a named URL parameter </td>
+>   </tr>
+>   <tr>
+>     <td><code>%NOP%</code></td>
+>     <td> A no-operation variable that gets removed. Useful to prevent a SEARCH from hitting an edit template topic; also useful to escape a variable like <code>%URLPARAM%NOP%{...}%</code></td>
+>   </tr>
+>   <tr>
+>     <td><code>%NOP{ ... }%</code></td>
+>     <td> A no-operation text that gets removed. Useful to write-protect an edit template topic, but not the topics based this template topic. See notes below. Example:%BR% <code>%NOP{%BR%   * Set ALLOWTOPICCHANGE = Main.TWikiAdminGroup%BR% }%</code></td>
+>   </tr>
+> </table>
+
+**_Notes:_**
+
+- Unlike other variables, `%NOP{ ... }%` can span multiple lines.
+- The scan for the closing `}%` pattern is "non-greedy", that is, it stops at the first occurance. That means, you need to escape variables with parameters located inside `%NOP{ ... }%`: Insert a `%NOP%` between `}` and `%`. Silly example: `%NOP{ %GMTIME{"$year"}%NOP%% }%`.
+
+All other variables are unchanged, e.g. are carried over "as is" into the new topic.
+
 #### <a name="Template Topics in Action"></a> Template Topics in Action
 
 Here is an example for creating new topics based on a specific template topic:
@@ -273,4 +312,4 @@ With URL: <code>**.../bin/oops/Sandbox/TestTopic2?template=oopstest&amp;param1=W
 
 - A drawback of referring to a master template is that you can only test a template from within TWiki, where the include variables are resolved. In the previous system, each template was a structurally complete HTML document with a `.tmpl` filename extension - it contained unresolved `%VARIABLES%`, but could still be previewed directly in a browser.
 
--- [[PeterThoeny]] - 23 Jul 2001 <br /> -- [[MikeMannix]] - 14 Sep 2001 <br /> -- TWiki:Main/DavidLeBlanc - 11 Mar 2002
+-- [[PeterThoeny]] - 01 Feb 2003 <br /> -- [[MikeMannix]] - 14 Sep 2001 <br /> -- TWiki:Main/DavidLeBlanc - 11 Mar 2002
index 16699f8..5351a62 100644 (file)
-# <a name="TWiki Topics"></a> TWiki Topics
+# <a name="TWiki Topics"></a><a name=" TWiki Topics"></a> TWiki Topics
 
 <div>
   <ul>
-    <li><a href="#TWiki Topics"> TWiki Topics</a><ul>
-        <li><a href="#Topic Features"> Topic Features</a></li>
-        <li><a href="#How to create and edit a topic"> How to create and edit a topic </a></li>
-        <li><a href="#How to attach files and use othe"> How to attach files and use other features</a></li>
-        <li><a href="#How to rename, move or delete a"> How to rename, move or delete a topic</a></li>
-      </ul>
-    </li>
+    <li><a href="#Characteristics"> Characteristics</a></li>
+    <li><a href="#Creating and editing topics"> Creating and editing topics</a></li>
+    <li><a href="#Other features"> Other features</a></li>
+    <li><a href="#Renaming, moving or deleting top"> Renaming, moving or deleting topics</a></li>
+    <li><a href="#Reviewing and Reverting"> Reviewing and Reverting</a></li>
   </ul>
 </div>
 
-The basic building block of a TWiki site is called a **_topic_**, identified by a unique, hopefully descriptive, [[WikiWord]] title. It may seem easier just to call them pages - but when you've used TWiki for a while, the difference is obvious. In the end,
+The basic building block of a TWiki site is called a **_topic_**, identified by a unique, hopefully descriptive, [[WikiWord]] title. It may seem easier just to call them pages, but specifically a topic is the content of a page. The distinction seems small but will become more important as your skill using TWiki increases. [[TWikiSites]] are built using topics.
 
-## <a name="Topic Features"></a> Topic Features
+## <a name="Characteristics"></a> Characteristics
 
-A TWiki topic is a self-contained information unit rich in features. Each topic has:
+A TWiki topic is a rich information unit. **Each** topic has:
 
-- a [[WikiWord]] title that lets you:
+- name
   - instantly identify what the topic is about
-  - link to it from other topics just by typing it in
-- an [[edit link|Main/WebHome#PageBottom]] to a collaboration area where you can:
+  - link to it from other topics just by typing it in it's [[WikiWord]]
+- content
+  - edited by simply clicking the [[edit link|Main/WebHome#PageBottom]]
   - enter plain text, leaving a blank space between paragraphs like email (all you need)
-  - use simple TWiki shorthand to represent complex HTML and special TWiki tags
-  - include links to other topics, Web sites, images, sound files, or anything else you can put on a regular Web page, using easy shorthand
-  - do all of that within your browswer, with no HTML editor, just simple codes and a handy pop-up quick reference panel
-- extra [[Web forms|TWiki/TWikiForms]] option:
+  - enter simple TWiki shorthand to represent complex HTML and special TWiki tags
+  - enter HTML if you are familiar with it
+  - include links to other topics, URLs, Web sites, files, images, sounds, or anything else you can put on a regular Web page
+  - handy pop-up quick reference
+  - do all of this through whatever web browswer you are familiar with
+- [[access control|TWiki/TWikiAccessControl]]
+  - independently determine who can see, edit, rename, move or delete topics
+  - set permissions by individual users and user groups
+  - over-ride topic, TWiki web or site
+- revision control
+  - topic changes are automatically saved
+  - efficiently stores every change made to the original version
+  - lets you compare and retrieve changes between any two versions, or review them all
+  - displays any previous version as a regular Web page or as raw topic text
+- TWiki web
+  - a TWiki organizational unit to which the topic belongs
+  - relevant when searching for a topic, referencing it or typing in it's URL
+- meta-data
+  - hidden contextual data stored within each topic.
+  - parents
+    - automatically links a new topic as the "child" of the topic it was created from
+    - hierarchical, parent-child navigation
+    - allows manual assignment of parent topic from a list of all topics in the local web
+    - offers navigation by topic parents
+- backlinks
+  - named referred-by (Ref-By)
+  - lists all topics that reference the current topic
+
+Features that can be used by topics and sites include:
+
+- skins
+  - fully configurable look and feel for all topics
+  - default and user selectable per session
+- plug-ins
+  - new feature packages
+  - developer community evolving existing and new capabilities
+- add-ons
+  - enhanced capability without an interface to users
+- [[FileAttachment]]
+  - upload files through your browser to the TWiki server
+  - attach any type of file (documents, images, applications) for viewing online, storage or sharing downloads with others
+  - upload revisions of existing files with automatic backup of all previous revisions
+- formatted search
+  - embedded searches of topics, data and meta-data, optional regular expressions
+  - custom formatting for outputting lists or tables, optional layout, headings, summary, etc.
+- variables
+  - similar to a command line context with site wide and locally defined variables
+  - over-ride topic, TWiki web or site
+- [[forms|TWiki/TWikiForms]]
   - store database-style info alongside the free-form topic content
+  - accesses meta-data
   - use text fields and boxes, radio buttons, pulldown selector menus, checkboxes
   - create your own forms to tag topics to later search, sort and display
-- a [[FileAttachment]] feature that lets you:
-  - upload files through your browser to the TWiki server
-  - attach any type of file (documents, images, applications) for viewing online, storage or sharing downloads with others
-  - upload revisions of existing files with automatic backup of all previous versions
 - [[TWiki Skins|TWiki/TWikiSkins]] to customize the look of headers and footers when topics are converted to Web pages for display:
   - apply skins across an entire TWiki web, or to a single displayed page
   - use included skins and easily create new ones
   - try the <code>**[Printable]**</code> skin below: stripped down headers and footers suitable for clean hard copy
-- browser-based controls for [[renaming, moving, and deleting|Main/WebHome#RenamingTopics]] topics:
+- [[renaming, moving, and deleting|Main/WebHome#RenamingTopics]]
   - rename a topic and automatically update all of the links to it, site-wide
   - move a topic from one TWiki web to another
   - safely delete a topic to a special Trash web (invisible, but recoverable from the Web server if necessary)
-- flexible [[access control|TWiki/TWikiAccessControl]]:
-  - independently determine who can see, edit, rename, move or delete topics
-  - set permissions by individual users and user groups
-- RCS revision control to automatically save all topic changes:
-  - efficiently stores every change made to the original version
-  - lets you compare and retrieve changes between any two versions, or review them all
-  - displays any previous version as a regular Web page or as raw topic text
-- a referred-by search that list all topics that link to a particular topic
-- hierarchical parent-child topic navigation:
-  - automatically links a new topic as the "child" of the topic it was created from
-  - allows manual assignment of parent topic from a list of all topics in the local web
-  - offers navigation displays, by topic parent, or by related topic
 - many more features...
 
-The configuration of your TWiki site and your personal user account determine which of these features are installed and available to you.
+The configuration of your TWiki site, skins and your personal user account can modify the way these features are used and presented to you.
 
 <a name="EditingPages"></a>
 
-## <a name="How to create and edit a topic"></a> How to create and edit a topic
+## <a name="Creating and editing topics"></a> Creating and editing topics
 
-Making it incredibly easy for you to add and edit information on existing topics, create new topics, and link all TWiki topics, is a TWiki main function.
+A primary purpose of TWiki is to make it incredibly easy for you to add and edit information on existing topics, create new topics, and link between TWiki topics.
 
-- **To modify a topic**, click the <code>**Edit**</code> link at the left of the toolbar at the bottom of every page. An editing window appears. Type away. Use the [[GoodStyle]] and [[TextFormattingRules]] links to get pop-up window help.
+- **To modify a topic**: click the <code>**Edit**</code> link in the toolbar at the bottom left of every page (using the Default skin). An editing window appears. Type away. Use the [[GoodStyle]] and [[TextFormattingRules]] links to get pop-up window help.
   - Click <code>**Preview Changes**</code> to see how your edit looks.
   - Click <code>**Save Changes**</code> to save.
 
-- **To add a new topic**, the simplest way is to type a new [[WikiName]] on an existing topic, while you're in edit mode. When the topic is saved, the new name will appear highlighted, with a **?** at the end: click the **?** and a new edit window appears. Enter, preview and save as usual. The new topic now exists.
+- **To add a new topic**: the simplest way is to type a new [[WikiName]] in an existing topic, while you're in edit mode. When the topic is saved, the new name will appear highlighted, with a **?** at the end: click the **?** and a new edit window appears. Enter, preview and save as usual. The new topic now exists.
   - Go back to the topic where you started, and you'll see the **?** has disappeared, and your [[WikiWord]] name is now a regular link. Type it anywhere on any topic in that web, and it will be turned into a link.
   - %H% **One little links rule: each topic, and its [[WikiWord]] link, belong to one unique web only.** To link _between_ webs, you must first enter the topic's web name. <br />**_Example:_** This is [[TWikiTopic]], in the <code>**TWiki**</code> web, so that's all you need to type on any topic in this web. But to link to [[TWikiTopics]] from a topic in the <code>**Main**</code> web, you have to type <code>**TWiki.TWikiTopics**</code> - <code>**Webname.TopicName**</code>. It's easy.
 
+Another way to add a topic is to type a new topic name in the Go box or an unknown topic URL. You can type in either a [[WikiName]] to create the topic in the current web or Web.TopicName to create a topic in a different web than the current page. Topics created with the Go box or URLs do not have parent meta-data defined.
+
 <a name="OtherFeatures"></a>
 
-## <a name="How to attach files and use othe"></a> How to attach files and use other features
+## <a name="Other features"></a> Other features
 
 The color-coded toolbar at the bottom of every topic displays a series of links, including:
 
 - <code>**[Attach]**</code> - pops a new screen for [[FileAttachments]]
-- <code>**[Ref-By]**</code> - displays all the TWiki topics with links to the topic you're on
-- <code>**[Diffs]**</code> - generates a page showing every change made to the topic you're on, with names, dates, and changes made
-- <code>**r1.3 | &gt; | r1.2**</code> _(ex)_ - some specific previous version stuff that you can check out on your own
-- <code>**[More]**</code> - opens up a whole new screen of additional controls
+- <code>**[Ref-By]**</code> - displays all the TWiki topics with links to the current topic
+- <code>**[Diffs]**</code> - generates a page showing every change made to the current topic, with names, dates, and changes made (diffs)
+- <code>**r1.3 | &gt; | r1.2**</code> _(ex)_ - view most recent revision and changes
+- <code>**[More]**</code> - opens up a new screen containing additional controls
 
-It looks like a lot - it is a lot, and there's more. BUT, it's all simple, flexible, and optional - the only way to confuse yourself or your site set-up and users is by using features you really don't need. Unlike the usual expensive, complex collaboration and project management packages, TWiki is fully functional and effective just by typing in text and making [[WikiWord]] links. All the rest is there only if you need it!
+It looks complicated, but the basics you need to begin with are very simple to use. The flexible and optional features are ready when you care to learn about them - the only way to confuse yourself or your site set-up and users is by using features you really don't need. Unlike the usual expensive, complex collaboration and project management packages, TWiki is fully functional and effective just by typing in text and making [[WikiWord]] links. All the additional features are there, but only if you need them!
 
-- Most controls are **self-explanatory**, and also include instructions and help links.
-- **Experiment**. You can always <code>**Cancel**</code> or go Back whenever you like.
-- Get **in-depth info** from the [[complete documentation|TWiki/WebHome]], including the User's Guide and Configuration Manual and TWiki Reference.
+- Some controls are self-explanatory and also include instructions and help links.
+- **Experiment**. You can always <code>**Cancel**</code> an edit or (using revision control) go Back whenever you like.
+- Get **in-depth info** from the [[complete documentation|TWiki/WebHome]], including the User's Guide, Configuration Manual and TWiki Reference.
 
 <a name="RenamingTopics"></a>
 
-## <a name="How to rename, move or delete a"></a><a name="How to rename, move or delete a "></a> How to rename, move or delete a topic
+## <a name="Renaming, moving or deleting top"></a> Renaming, moving or deleting topics
 
-You can now rename, move and delete individual topics from your browser. All three options are available by clicking <code>**More**</code> on the control strip at the bottom of every page. The access settings for a topic, web or entire site may be disabled for one or more of the three options, depending on your site set-up and personal permissions. In any case, all three are similar and extremely easy to use.
+You can rename, move and delete individual topics by clicking <code>**More**</code> on the control strip at the bottom of every page. The access settings for a topic, web or entire site may be disabled for one or more of the three options, depending on your site set-up and access permissions.
 
 1. Go to the top you want to change, click <code>**More &gt; Rename/move**</code>
 2. **To move or delete:** select the target web (<code>**Trash**</code> to delete)from the pull-down menu (otherwise, leave on the current web)
@@ -106,6 +137,20 @@ You can now rename, move and delete individual topics from your browser. All thr
 
 %H% Deleting means moving a topic to the Trash web. Since all webs share the one Trash, name conflicts may come up.
 
+<a name="RevisionRollback"></a>
+
+## <a name="Reviewing and Reverting"></a> Reviewing and Reverting
+
+RCS revision control automatically saves all topic changes. To look at earlier versions of a topic, click on `Diffs` link in topic commands. If you would like to revert to an earlier version or reclaim part of an earlier version, just copy from the old topic revision to the current topic revision. This is a step by step set of instructions:
+
+1. In the `Diffs` view, take note of what version of the topic you want to reclaim and then return to `View`.
+2. Select `More` in the topic commands.
+3. Under "View previous topic revision," enter the version number you want to reclaim and check "raw text format." Then click on "View revision."
+4. Select either the portion of that version you want to reclaim or the entire text of the topic if you want to revert completely to that version. Select `Copy` under your browser's `Edit` menu.
+5. Return to the most recent version of the topic and select `Edit` from the topic commands.
+6. Either paste in the portion of the topic you wish to reclaimed or replace the entire text with the text you copied from the earlier version.
+7. Preview and save the topic.
+
 See: [[ManagingTopics|Main/TWikiDocumentation#Managing_Topics]] for more details.
 
--- [[MikeMannix]] - 12 May 2002
+-- [[MikeMannix]] - 22 May 2002 %BR% -- [[GrantBow]] - 17 Jan 2003 %BR%