PHP Classes

File: phphelp.txt

Recommend this page to a friend!
  Classes of Mark Cole   PHP Online Help System   phphelp.txt   Download  
File: phphelp.txt
Role: Documentation
Content type: text/plain
Description: Plain text documentation
Class: PHP Online Help System
Get site help topics from file defined with macros
Author: By
Last change:
Date: 10 years ago
Size: 34,756 bytes
 

Contents

Class file image Download
=================================================================================================================================== PHPHelp - A simple class to facilitate context sensitive help for websites. Version 1.0.0 Author: Mark Cole Copyright 2014 Mark Cole. Requires: PHP Version 5.1.2 or later. Released under the GNU General Public Licence http://www.gnu.org/licences/gpl.html This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. The complete distribution package for PHPHelp consists of the following files. phphelp.class.php ... The PHPHelp class itself. helpdocs.php ........ Example script that displays the documentation. phphelp.hxt ......... PHPHelp documentation pn PHPHelp file form to be viewed using helpdocs.php snippets.txt ........ Example "snippets" file also used by helpdocs.php phphelp.txt ......... Plain text version of the documentation. All of the above are Copyright Mark Cole, 2014 and are released under the same GNU licence as phphelp.class.php and should be included in any modified package that you distribute. Also in the complete package is LICENCE.TXT, the GNU General Public Licence and this too must be included in any modified distribution. Note: PHPHelp and its examples and documentation were written on a Windows XP box (developed with php 5.4.15/Apache 2.4.4) I apologise for any file encoding problems that may occur for users of other OS's. PHPHelp has been tested with Linux (PHP 5.3.28/Apache 2.3). =================================================================================================================================== PHPHelp Documentation - Page 1 ============================== Introduction ------------ PHPHelp is a simple but hopefully effective class for implementing basic context sensitive help on a website. It was born of a need I had to provide comprehensive help for a community website I was building. This is a complete rewrite of that original script with what I hope are useful additions such as Macros and Variable Substitutions, automatic linking (well, semi-automatic) and some other bits. PHPHelp does not display help, that's up to you. What it does do is provide a comprehensive set of help file features to facilitate the creation of attractive and even, in a small way, dynamic help topics, find and format those topics as needed and return the topic you want ready to be displayed. I hope that someone else will find it useful. The best way to view the documentation for PHPHelp is to put the included phphelp.class.php, helpdocs.php, phphelp.hxt and snippets.txt in a directory on your server and browse to helpdocs.php. That way you not only get to see the documentation but PHPHelp in action. Failing that this is a text version of the same documentation. Index Basic PHPHelp Usage .... 2 Help file Format ....... 3 Topic Links ............ 4 Macros ................. 5 User Defined Macros .... 6 The $snippet Macro ..... 7 Variable Substitution .. 8 Escape Sequences ....... 9 PHPHelp Methods ........ 10 PHPHelp Variables ...... 11 PHPHelp Constants ...... 12 To Do................... 13 PHPHelp Documentation - Page 2 ============================== Basic Usage ----------- First, create your help files. See page 3 for information on the Format of Help Files ---------------------------------- Help File Example----------------------------------------------- #Example help file help.txt :topic1 This is Topic One <p> Here is some help for something\b What to say, umm, nope, cant't think of any more\b </p> :topic2 This is Topic Two <p> Completely out of ideas for example text for this.\b Probably have to resort to Lorem ipsum for later examples! </p> --------------------------------------------------------------------------------------------------- Once you have a help file to play with you can retrieve topics from it very simply, as in the following example script. --------------------------------- PHP Script Example ---------------------------------------------- <?php require_once 'phphelp.class.php'; $help=new phphelp('/pathto/myhelp.txt'); $topic=$help->help('topic1'); if ($topic) { echo "<h1>$topic[0]</h1>"; echo $topic[1]; } else { echo "Help topic not found<br>"; if ($help->error) echo "Error=".$help->errorInfo; } ---------------------------------------------------------------------------------------------------- Of course you might want to dress up the output a bit! PHPHelp Documentation - Page 3 ============================== Help file Format ---------------- PHPHelp help files are plain text files containing topic blocks written as HTML. Each Topic starts with a topic name and, optionally, a title. The topic name is identified by a preceding colon like so :mytopic and ends at the first whitespace character (ie. a space or a newline). The title if given is separated from the topic by one or more spaces and continues to the end of the line. :mytopic This is My Topic or, for those who like their examples to be more traditional... :foo bar Topic names are case sensitive so: :MyTopic and :mytopic are two different topics. Next comes the text of the topic which ends at the next topic or the end of the file. There is no size limit on topics (apart memory of course). In addition to text topic blocks can contain links to other topics, Macros, built in and those which you can define yourself (see pages 5,6), variables (see page 8) and escape sequences. You can also embed text snippets (blocks of often used text) in a topic using the $snippet macro (see page 7). Here is an example of a simple help file with two topics ------------------------------------- Help File Example-------------------------------------------- # Example of a simple help file # Lines starting with a hash are comments except when inside a topic block :topic1 This is Topic One Here is some help about topic one If there was more to say about it I'd say it! : :topic2 This is the Second Topic <p> Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. <p> ----------------------------------------------------------------------------------------------------- One little trick - if you begin a topic title with a star "*" then that topic will be excluded from the list produced by the topics() method (see Public Methods). This can be of use if, for example, you are including a glossary in your help file and don't want glossary topics to show up in a list of all topics. ------------------------------------- Help File Example-------------------------------------------- :submit *This will not appear in the list returned by phphelp->topics() The Submit button sends the contents of a form back to the Website for processing.\bClick the Submit button when you are satisfied that you have completed the form.\b\b See also Cancel ----------------------------------------------------------------------------------------------------- Note that although the colon ":" is a special character used to identify a topic name you can also, as in the example above, use it simply to separate topics and make your help file more readable. Of course you can also include as many blank lines as you like since this is HTML output. Including Files --------------- You don't have to have all your topics in one help file, you can use the "include" and "includerole" keywords to include other files. The include and includerole keywords are always lowercase. include other.txt This will tell PHPHelp include the named file (other.txt in the example) when searching for topics. The include keyword is only valid outside of a topic block but other than that can appear anywhere in a file. If you include a full path for the include file then that is used. If you only specify a file name then it is assumed that the file resides in the same directory as the main help file. The second form of include is includerole <role> <file>. includerole will include a file only if the current users role as set by you when you instantiated the help object, matches that specified in the includerole option. Examples: includerole administrator /help2/adminhelp.txt includerole guest /help/guesthelp.txt includerole 200 /help/privs200.txt and if phphelp was instantiated with $help=new phphelp("help.txt","guest") then the guest help will be included. Part of the usefulness of this is that you can have one help file containing general help and then include specific files that expand on options that might be available only to certain users. Note also that if you have two topics with the same name then only the first will be found which means that it is possible to use this "conditional" include to override a later topic for certain users. PHPHelp Documentation - Page 4 ============================== Topic Linking ------------- In any help system you are likely to want links between topics. Of course you can put these in the usual way eg. <a href="morayball.org/help?topic=atopic">See here for details<a> but this is hard work so PHP provides a short form for you @{topic:Title}. So the link to the next topic in this help can be written as @{macros:Macros} which saves quite a bit of typing... The URI used for links is created at instantiation by taking _SERVER['SCRIPT_URL'] or _SERVER['REQUEST_URI'] (if SCRIPT_URL is not there) and adding the constant HELP_QUERY_TOPIC (which defaults to 'topic'). If this method does not produce the URI that you need you can set phphelp->linkURI to what you need. You should set it to a valid URI complete with a query name and "=" sign. EG: "my.domain.com/help.php?topic=" PHPHelp Documentation - Page 5 ============================== Text Macros ----------- PHPHelp Text Macros are simple macros that insert dynamic text into your topic. Macros are referenced by name and macro names are case sensitive. All macro names are prefixed by a @ sign (like variables in PHP) If a macro accepts arguments then these are enclosed in brackets. String arguments should be quoted with double quotes ("like so") although a one word string (ie. with no spaces can be unquoted. Numeric arguments can be quoted or not. Where a Macro takes no arguments or arguments are optional (for example the @date macro) you can either add empty brackets or not as you like. However you should note that if arguments are optional then empty brackets are treated as an empty string. A macro and its arguments must all be on the same line. You cannot, as you can with a function call in PHP, get away with splitting a macro call over more than one line. For example, the following are all valid calls to the @date macro.. @date("d/m/Y H:i") = 01/05/2014 20:46 @date() = May 1, 2014 (the date macro assumes an empty string as argument means "use the defaults" @date = May 1, 2014 while these are not valid. @date('d/m/Y H:i') (wrong sort of quotes) @date( "d/m/Y H:i" ) (Spans more than one line) A few simple macros are built into PHPHelp but, with a few exceptions, they are pretty pointless and serve only as demonstrations should you wish to extend the class. @date ----- @date[(string format)] Inserts the current date. Optionally a format string can be specified. Date formats are as used for the PHP date() function (see PHP Manual - Date Function) If "format" is not given the date is is formatted as: May 1, 2014. With the appropriate format string @date will of course also give you the time but there is also a @time macro (see below) @snippet -------- @snippet([string name]|[string file,string name]) @snippet inserts a block of text (or "snippet") from a file into the current topic. @snippet has its own topic on page 6 @time ----- @time[(string format)] Inserts the current time. Mainly here as a short-form since @date can provide both date and time. Optional format string is as used for the PHP date() function (see PHP Manual - Date Function) If "format" is not given the time is is formatted as: 20:46:33. With the appropriate format string @time will of course also give you the date! The other built in macros are: @hostname --------- Inserts your host name (from _SERVER[SERVER_NAME]) eg: morayball.org @clienthost ----------- Gives the host name of the client. clientip -------- Gives the IP address of the client: 84.92.57.136 You can also add you own "user-defined" macros by writing a PHP function to return a value and registering it with PHPHelp. User-defined Macros are dealt with in the next section. See also: Variable Substitution Macro Errors ------------ Assuming that the variable phphelp->ignoreErrors is set false (the default) then when an error occurs while PHPHelp is interpreting a macro (and here I mean a syntax error in the macros arguments) you will see an error message displayed in place of the help topic you were expecting. The error message will tell you the nature of the error and the file and line where it occurred. It is important to note that macros in a line are interpreted right to left so that if you have more than one error you will see what you would expect to be the last one first. The syntax errors detected by PHPHelp for user-defined macros are limited to such things as missing quotes, commas or closing brackets. @macro(bad arg") will produce this error: Expected "," or closing ")" whereas @macro(badarg") will be accepted as one argument, the string badarg" This is because the first example is seen as one argument - "bad" and PHPHelp will expect that it will be followed either by a comma and another argument OR by a closing bracket. The simplistic method of parsing used by PHPHelp can lead to odd errors if you ask too much of it. The best bet is simply to wrap all arguments in quotes. PHPHelp Documentation - Page 6 ============================== User-Defined Macros ------------------- You do not have to extend the class just to add macros, all you need to do is write a callable function in your own script that returns a string value, call PHPHelp->registerCallbackMacro() with the name of the function and thereafter whenever you use that function name as a macro in a help topic PHPHelp will call your function and insert the string it gets into the text. PHPHelp checks for user-defined macros before checking for its own built in macros so a user defined macro can override a built in one. You function can accept any number of arguments but be aware that the syntax check in PHPHelp is limited to spotting malformed arguments (such as missing a quote) so it's up to you to make sure that you pass the right number of arguments when you call a macro (the usual warnings will appear in PHP's error log). If your function requires NO arguments there is no need to put empty brackets after its name when you call it. @mymacro is fine instead of @mymacro(). Note also that empty brackets are treated as one argument consisting of an empty string so mymacro() translates as mymacro(""). Example: ----------------------------------- User-Defined Macro Example - PHP Code-------------------------- <?php require_once("phphelp.class.php"); function username() { return $_SESSION['username']; } $help=new phphelp('help.txt'); $help->registerCallbackMacro('username'); --------------------------------------------------------------------------------------------------- and now you can write topics that include @username as part of the text. :contents Help Contents <p>Hello @username, the following are the main help topics.</p> ...and so on Macro arguments can themselves contain macro calls so that the result of one macro can be the argument to another but note that the text your function returns cannot itself contain macro references (well, it can but they will not have any effect) but it CAN contain the link "macro" @{link:title} which WILL be converted to a proper link. One example of the use of user-defined macros appears on every page of this help that you are reading. The links at the top of each page Back to Index and at the bottom of each page Next Topic and Back to Index are generated by a user-defined macro. This is the help file entry for the topic you are currently reading... :macros Text Macros @indexlink("") <p> PHPHelp Text Macros are simple macros that insert dynamic text into your topic. Macros are referenced by name. All macro names are prefixed by a @ sign (like variables in PHP)... ...and so on... </p> @indexlink("@{snippet:The @Snippet Macro}") and in the helpdocs.php script.. function indexlink($s) { if ($s) return '<div style="float:right">@{phphelp:Back to Index}</div><div>Next Topic: '.$s.'</div>'; else return '<p style="text-align: right;">@{phphelp:Back to Index}</p>'; } It is worth noting that the User Defined Macro mechanism also works for PHP built in functions. If you register the name of a PHP function with PHPHelp you can then use it from within a help topic. For example: $help->registerMacro('substr'); :example Example Topic This uses the substr function to say <strong>@substr("Hello World",0,5)</strong> Will produce the following: This uses the substr function to say Hello The use of PHP functions as macros in this way has not been extensively tested and indeed I'm not sure how useful it is, but it can be done. PHPHelp Documentation - Page 7 ============================== The @snippet Macro ------------------ This macro will insert a block of text (or "snippet") from help file into a topic. It is used to insert snippets of text that appear regularly. By default snippets are taken from a file called "snippets.txt" which is expected to reside in the same direcory as your help file, However, you can change that by specifying a different file when you call the @snippet macro or by setting your desired file path in PHPHelp->snippetFile. Snippets are blocks of text that have the same format as help topics (and, indeed the @snippet macro will happily insert a complete topic (without title) if you ask it to since the same method that reads topics is used to read snippets. Because of this snippets can themselves include macros and, therefore, other snippets. If you use nested snippets beware of infinite loops (eg. snippet one includes snippet two which includes snippet one). Granted that is not a likely scenario but it is possible. To include a snippet in a topic call @snippet with the name of the snippet and, optionally the file that contains it. @snippet([name]|[path,name]) EG: Include my snippet @snippet("mysnippet") here and another @snippet("/help/mysnippets.txt","mysnippet") here. Examples. Using the default snippet file: ---------------------------------- Example snippet.txt file ---------------------------------- :copyright <p style="position: relative; text-align:center; font-weight: bold: font-size: 8pt"> All content Copyright 2014 the foo organisation. </p> ---------------------------------------------------------------------------------------------- -------------------------------------- Example help file ------------------------------------- :foo Yes, this is an Example Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip @snippet("copyright") :bar Another Topic More stuff ----------------------------------------------------------------------------------------------- Click here to see the result. Specifying a snippet file: -------------------------- ----------------------------------------- Example help file ----------------------------------- :bar The Snippet Macro This here is an example that shows how to use snippets. Today we will be taking our snippet from a named file. @snippet("/help/mysnippets.txt","copyright") :foobar Another Topic More stuff ----------------------------------------------------------------------------------------------- There is nothing to stop you keeping your snippets in the same file as your help topics and, for convenience, setting the default snippet file to the same as the help file: --------------------------------------------- PHP Example ------------------------------------- <?php require_once 'phphelp.class.php'; $helpfile='/pathto/myhelp.txt'; $help=new phphelp($helpfile); $help->snippetFile=$helpfile; //use the same file for help topics and snippets ----------------------------------------------------------------------------------------------- However, if your main help file is large it's probably better to use a separate snippets file simply to save PHPHelp searching through so much text each time a snippet is referenced. PHPHelp Documentation - Page 8 ============================== Variable Substitution --------------------- Variable Substitution works in much the same way as it does in PHP Strings but is not as sophisticated. In order to use a PHP Variable in your help text you must first register it with PHPHelp using registerVar registerVar(string name,mixed $Var) ----------------------- PHP example ---------------------------- $example = "This is an example of variable substitution."; $help=new phphelp($helpfile); $help->registerVar('example',$example); ---------------------------------------------------------------- Then you can use the variable in help files in the normal way: -------------------------------------- Example help file ------------------------------------- :varsubexample Example Variable Substitution \t<strong>The variable \$example says: $example</strong> ---------------------------------------------------------------------------------------------- Things to remember when using variable substitution: 1) The parsing for variable substitution is very simplistic and easily confused!. 2) Use curly-brackets around variable names if the variable name is embedded in a word otherwise it will not be matched. EG: "this is an embedded $varname" will not work with a variable named $var "this is an embedded {$var}name will" I don't know when that would be useful but there it is... 3) Variables can be used as arguments to macros 4) If you use a variable as an argument to the @{link} macro you need to double the closing curly bracket because the brainless parser will eat it (told you it was easily confused). Use @{topic:$var}} 5) Use \$ to escape the dollar sign if you don't want to substitute it. But that only matters if the variable exists (ie. has be registered with registerVar()). There is no need to escape dollar signs otherwise (though it would be a good practice to do so). 6) The name you pass to registerVar() does not have to be the same as the name of the variable that you are registering, it can be anything you like as long as you always refer to the variable by that name in your help files. $help->registerVar('foo',$bar); ... :topic Some Topic Here is the value of $foo (displays value of $bar). There is a second way to do variable substitution. It only works for global variables, and only for simple variables not arrays, but it does not require you to register the variable through registerVars(). This is a method that was left over from an earlier version of PHPHelp before "proper" variable substitution was added. Simply prefix the name of a GLOBAL variable with the macro prefix (@) and (if it exists in $GLOBALS) the value of the variable will be substituted: -------------------------- Example help file --------------------------- :atopic This is a variable from $GLOBALS ... @$somevar ------------------------------------------------------------------------ PHPHelp Documentation - Page 9 ============================== Escape Sequences ---------------- PHPHelp recognises a few escape sequences which it will interpret when parsing a help file. These escape sequences are also interpreted when used in the values returned by user-defined macros. With the exception of \" these escape sequences are NOT interpreted when used in macro arguments. \@ Escapes the @ (macro prefix) character. @ must be escaped if it is not followed by a space or a number otherwise PHPHelp will think it is a macro name. \: Escapes the : (topic prefix) character. The colon only needs to be escaped if it occurs as the first (first non-space) character on a line. \" Escapes a double quote in macro arguments eg @macro("Say "hello" world") \\ Escapes the escape character. \$ Escapes the $ (variable prefix) dollar sign. Some escapes useful in HTML \t TAB Translates to four non-breaking spaces (&nbsp) Provides a quick and dirty way of indenting text. Don't expect it to behave in HTML like a proper TAB, its only really useful to indent the start of a line. \b Translates to HTML line break (<b />). Saves a bit of typing.. \< Escapes the less-than sign for HTML (outputs &lt;) \> Escapes the greater-than sign for HTML (ouputs &gt;) Miscellaneous Escapes \r Carriage Return \n Line Feed These two are included for completeness but since help files are usually HTML they are seldom likely to be much use! PHPHelp Documentation - Page 10 =============================== Public Methods -------------- PHPHelp has four public Methods including the constructor. __construct(string $helpfilePath[,string $role=""]) Initialize the object. $helpfilePath path of help file. If help file has INCLUDE (or INCLUDEROLE) files they are assumed to be in the same directory as given in $helpfilePath $role Current users (clients) "role". This is a crude "access control" facility to allow appropriate topics to be displayed depending on the users role on the site. $role can be anything appropriate to your site - a string or a number as long as it can be used to match the argument used for INCLUDEROLE instructions in a help file. For more details and examples see Help file Format function help(string $topic) Returns an array containing the specified topic, if it is found in the help file. The returned array has this format: array[0] contains the topic title. array[1] contains the topic text. If the topic is not found or a fatal error occurs (typically "Help file not found") then an empty array is returned which you can trap with: if (!$topic=$help->topic('topic)). Thus you can code as follows: <?php require_once 'phphelp.class.php'; $help=new phphelp('/pathto/myhelp.txt'); $topic=$help->help('index'); if ($topic) { echo "<h1>$topic[0]</h1>"; echo $topic[1]; } else { echo "Help topic not found<br>"; if ($help->error) echo "Error=".$help->errorInfo; } In the event of a fatal error (such as "Help file not found") the variable phphelp->error will be TRUE and phphelp->errorInfo will be set to the reason. If the error is simply "Topic not found" then phphelp->error will NOT be set. Therefore: Empty return array + phphelp->error == true means a file error Empty return array with !phphelp->error == false means topic not found. Note that although errors may occur in macro calls these are considered non-fatal and (unless phphelp->ignoreErrors is set true) an error message will be returned as the topic text (instead of the actual content of the requested topic). EG: PHPHelp: Callback function for macro "indexlink" was not found. (File: /help/help.txt, line: 440) or PHPHelp: Macro syntax - expecting "," or closing ")". (File: /help/help.txt, line: 529) This should aid debugging of help files. It is probably better to set $ignoreErrors to TRUE for production sites so that users will at least see the help topic, albeit perhaps with some bits missing. When $ingnoreErrors is TRUE the macro that caused the error is seen just as it appears in the raw text of the topic and no error is displayed. function topics([boolean $sort=true]) Returns a multi-dimensional indexed array containing a list of all (see note 1 below) topics in the current help file. If sort is TRUE (which is the default) the array is sorted by Topic Title. If FALSE then topics appear in the array is in the order they were found. The text of topics is not included. The array has the following format: array[][topic][title][link] Thus: array[0][topic] contains the name of the first topic array[0][title] contains the title of the first topic array[0][link] contains a ready to use link to the topic array[1][topic] contains the name of the second topic array[1][title] contains the title of the second topic (..) and so on.. Using this you can easily produce an index or table of contents by simply displaying all of the [link]'s in a foreach loop (or build your own links using [topic] and [title]. 1) Topics with no title are, by default, excluded from the list. If you want them included set $includeUntitled=true. Topics where the title begins with a start (*) will always be excluded from the list. 2) If $sort is TRUE then duplicate topics will be removed but if $sort is false then any duplicates will remain. function registerCallbackMacro(string $macroname) Registers a user-defined macro (see User Defined Macros for details). Returns: void EG: $help->registerCallbackMacro("mymacro"); function registerVar(string name, mixed $var) Registers a variable (by reference) for use in variable substitution (see Variable Substitution for details). "name" is the name by which you will refer to the variable in help files. "$var" is the actual PHP variable which name references. The name you pass as parameter one does not have to be the same as the name of the variable passed as parameter two as long as it IS the name used to refer to the variable in help files. You can include a leading $ or not as you wish.... $help->registerVar('$myvar',$myvar); and $help->registerVar('myvar',$myvar); are equivalent (unless, of course, you were using double-quotes around the name!). Returns: void PHPHelp Documentation - Page 11 =============================== Public Variables ---------------- boolean $error Set TRUE if an error occurs. The error message will be in $errorInfo. This is only really of use for fatal errors the only one of which is "Unable to read help file" string $errorInfo Reason for error string $snippetFile Default file used for $snippet() macro if no path is given in the arguments. boolean $ignoreErrors Ignore non-fatal errors (macro errors mostly). If set then no error message will be displayed and parsing the help topic continues. Default setting: FALSE string $linkURI Default link uri formed from current URI using $_SERVER[SCRIPT_URL] or $_SERVER['REQUEST_URI'] with a query variable name appended (using the constant phphelp::HELP_QUERY_TOPIC) + an "=" sign ready to append a topic name when a link is needed. It will look something like "mydomain.com/script.php?topic=" The _SERVER variables available to PHP depend on server configuration and cannot be guaranteed so if PHPHelp is not producing appropriate links when you use @{topic:Title} to make a link you can set this to something that works for your system. You should set it to a valid URI complete with a query name and "=" sign. EG: $help->linkURI="my.domain.com/help.php?topic="; $linkURI does not include the request method (eg. "http://") but you can add it if you wish. boolean $includeUntitled Include untitled topics in the list returned by topics() As untitled topics are generally snippets this is FALSE by default. PHPHelp Documentation Page 12 ============================= PHPHelp Constants ----------------- These constants can be changed if you really need to but be aware when changing HELP_MACRO_CHAR or HELP_TOPIC_CHAR there maybe ramifications when changing to or from a PCRE meta character. There are notes in the code. const HELP_COMMENT_CHAR = '#' Character used to prefix comment lines in help files. const HELP_MACRO_CHAR = '@' Character used to prefix text macro names in help files. const HELP_TOPIC_CHAR = ':' Character used to prefix a help topic. const HELP_QUERY_TOPIC = 'topic' Query String variable name used when generating links. PHPHelp Documentation Page 13 ============================= Things to do in Version Two --------------------------- Indexed help files: PHPHelp is not really aimed at massive sites with thousands of visitors so the fact that it searches through the whole help file to find a topic is not especially problematical, still it would be nice if it could build and use an index. Macro handling could be improved, especially more intelligent handling of parameters. .