[Fusionforge-commits] r15537 - branches/Branch_5_1/src/docs

Roland Mas lolando at fusionforge.org
Mon May 21 11:40:10 CEST 2012


Author: lolando
Date: 2012-05-21 11:40:09 +0200 (Mon, 21 May 2012)
New Revision: 15537

Added:
   branches/Branch_5_1/src/docs/README.html-elements
   branches/Branch_5_1/src/docs/README.html-utils
Removed:
   branches/Branch_5_1/src/docs/README.html:elements
   branches/Branch_5_1/src/docs/README.html:utils
Log:
Renamed doc files to avoid potentially unsafe characters in filenames

Copied: branches/Branch_5_1/src/docs/README.html-elements (from rev 15536, branches/Branch_5_1/src/docs/README.html:elements)
===================================================================
--- branches/Branch_5_1/src/docs/README.html-elements	                        (rev 0)
+++ branches/Branch_5_1/src/docs/README.html-elements	2012-05-21 09:40:09 UTC (rev 15537)
@@ -0,0 +1,142 @@
+Documentation of new HTML element creation functions
+────────────────────────────────────────────────────
+
+Functions defined in src/www/include/html.php → available: always.
+
+
+‣ Element emission functions (do not echo anything)
+
+
+• string html_eo(string $name, optional(empty) array $attrs)
+
+	html_eo('b')
+	⇒ '<b>'
+
+	html_eo('td', array('colspan' => 2))
+	⇒ '<td colspan="2">'
+
+	html_eo('div', array('class' => array('ff', 'important')))
+	⇒ '<div class="ff important">'
+
+	html_eo('img', array(
+		'src' => '…',
+		'ref' => false,
+		'class' => array(),
+		'alt' => "",
+	    ))
+	⇒ '<img src="…" alt="">'
+
+  Generate an XHTML E̲lement O̲pen tag for $name, with attributes
+  defined by key/value pairs properly inserted. Attribute values
+  are coerced into strings from integers (by casting) or arrays
+  (by concatenating the array elements with spaces); if the value
+  is === false or an empty array (count($attrs[n]) == 0), the
+  attribute is not output at all, but for empty values it is; see
+  the img example (admittedly bad, you’d use html_e() for "img").
+
+• string html_e(string $name, optional(empty) array $attrs,
+    optional(empty) string $content, optional(true) bool $shortform)
+
+	html_e('br')
+	⇒ '<br />'
+
+	html_e('a', array('href' => '/foo.php?a=1&b=2'), 'täxt')
+	⇒ '<a href="/foo.php?a=1&b=2">täxt</a>'
+
+	html_e('script', array(
+		'type' => 'text/javascript',
+		'src' => '/js/foo.js',
+	    ), "", false)
+	⇒ '<script type="text/javascript" src="/js/foo.js"></script>'
+	/* needed because <script ... /> does not work */
+
+	html_e('tr', array(), html_e('td', array(), 'bla'))
+	⇒ '<tr><td>bla</td></tr>'
+
+  As with html_eo() the first two arguments define the tag to open.
+  The third argument will be placed between the opening and closing
+  tags but – in contrast to attribute values – not entity-encoded.
+  If the third argument is empty, either a self-closing (default)
+  tag, or, if the fourth argument is false, an open-close sequence,
+  is emitted.
+
+
+‣ Autoclose stack functions
+
+	$spos = html_ap();
+	$s = html_ao('p');
+	if ($foo) {
+		$s .= html_ao('strong');
+	}
+	$s .= html_ao('a', array('href' => '/'));
+	$s .= somefunc();
+	$s .= html_ac($spos);
+	⇒ '<p><strong><a href="/">somefuncreturnvalue</a></strong></p>'
+	⇒ '<p><a href="/">somefuncreturnvalue</a></p>'
+
+• integer html_ap(void)
+
+  Return the a̲utoclose stack’s current p̲osition.
+
+• string html_ao(string $name, optional(empty) array $attrs)
+
+  Works the same as html_eo() but pushes $name onto the a̲utoclose
+  element stack when o̲pening it.
+
+• string html_ac(integer $spos)
+
+  Return a set of closing elements until the a̲utoc̲lose stack
+  has reached the position it had when html_ap() returned $spos.
+
+  If $spos === false: an empty string is returned, for html_aonce().
+
+  If $spos < current stack position, an Exception is raised.
+
+• string html_aonce(ByRef integer $sptr, string $name,
+    optional(empty) array $attrs)
+
+	$spos = false;
+	foreach ($row in $rows) {
+		echo html_aonce('table');
+		echo html_e('tr', array(), html_e('td', array(),
+		    util_html_secure($row['data'])));
+	}
+	echo html_ac($spos);
+	⇒ ''  // if $rows is empty
+	⇒ '<table><tr><td>content1</td></tr><tr><td>content2</td></tr></table>'
+
+  If $sptr is not false, do nothing. Otherwise, set it to
+  the current html_ap() then do html_ao($name, $attrs).
+
+  This function can easily be used to open an enclosing element
+  with mandatory inner elements, such as a table, only once except
+  if no table row were to be generated.
+
+‣ Autoclose stack copy functions
+
+	$spos = html_ap();
+	echo html_ao('tr', array('bgcolor' => '#FF0000'));
+	echo html_ao('td');
+	echo "content 1";
+	$scopy = html_a_copy($spos);
+	echo html_ac($spos);
+	echo html_e('tr', array(), html_e('td', array(), "intermediate"));
+	echo html_a_apply($scopy);
+	echo "content 2";
+	echo html_ac($spos);
+	echo html_a_apply($scopy);
+	echo "content 3";
+	echo html_ac($spos);
+
+	⇒ <tr bgcolor="#FF0000"><td>content 1</td></tr>
+	  <tr><td>intermediate</td></tr>
+	  <tr bgcolor="#FF0000"><td>content 2</td></tr>
+	  <tr bgcolor="#FF0000"><td>content 3</td></tr>
+
+• opaque html_a_copy(integer $spos)
+• string html_a_apply(opaque $scopy)
+
+  Before autoclosing the stack down to a level $spos, you can
+  retrieve a copy of the stack in an opaque format, which can
+  later be used to (re-)open the same elements, with the same
+  attributes, even in a different nesting state.

Copied: branches/Branch_5_1/src/docs/README.html-utils (from rev 15536, branches/Branch_5_1/src/docs/README.html:utils)
===================================================================
--- branches/Branch_5_1/src/docs/README.html-utils	                        (rev 0)
+++ branches/Branch_5_1/src/docs/README.html-utils	2012-05-21 09:40:09 UTC (rev 15537)
@@ -0,0 +1,102 @@
+Documentation of common HTML utility functions
+──────────────────────────────────────────────
+
+Functions defined in src/common/include/utils.php → available: always.
+
+
+• string util_html_encode(string $s)
+
+	util_html_secure('a=1&b=2')
+	⇒ 'a=1&b=2'        // HTML-encoded
+
+	util_html_secure('a=1&b=2')
+	⇒ 'a=1&amp;b=2'    // changed!
+
+  Encode a string for use in XHTML even if it is already encoded.
+
+• string util_html_secure(string $s)
+
+	util_html_secure('a=1&b=2')
+	⇒ 'a=1&b=2'    // HTML-encoded
+
+	util_html_secure('a=1&b=2')
+	⇒ 'a=1&b=2'    // unchanged
+
+  Encode a string for use in XHTML if it is not already encoded.
+  (So, if you use this for output sanitising, other than a slight
+  performance penalty no harm is done if the output was already
+  sane.)
+
+• string util_unconvert_htmlspecialchars(string $s)
+
+	util_unconvert_htmlspecialchars('a=1&b=2')
+	⇒ 'a=1&b=2'    // unchanged
+
+	util_unconvert_htmlspecialchars('a=1&b=2')
+	⇒ 'a=1&b=2'    // HTML-decoded
+
+  Undo util_html_encode; be careful, this can decode partially.
+
+
+• string util_gethref(optional(false) string $baseurl,
+    optional(empty) array $args, optional(true) bool $ashtml,
+    optional('&') string $sep)
+
+	util_gethref("/x.php", array(
+		'foo' => 'a+b&c',
+		'bar' => 'd+b&e',
+	    ));
+	⇒ "/x.php?foo=a%2Bb%26c&bar=d%2Bb%26e"
+
+	util_gethref("/x.php", array(
+		'foo' => 'a+b&c',
+		'bar' => 'd+b&e',
+	    ), false);
+	⇒ /x.php?foo=a%2Bb%26c&bar=d%2Bb%26e
+
+	util_gethref("/x.php", array(
+		'foo' => 'a+b&c',
+		'bar' => 'd+b&e',
+	    ), true, ';')
+	⇒ "/x.php?foo=a%2Bb%26c;bar=d%2Bb%26e"
+
+  Construct an URI for use with util_make_url, session_redirect,
+  html_e('a', array('href' => …)), and similar. The first argument
+  ($baseurl) is passed through as-is but, if falsy, defaults to
+  getStringFromServer('PHP_SELF'); the arguments (both keys and
+  values) are urlencoded (entries while values is false are not
+  emitted at all) and appended, with a question mark in front and
+  the $sep separator in between.
+
+  If $ashtml is true (default), the result will then be run through
+  util_html_encode; set this to false when using in html_e href as
+  value (since html_e will html-encode itself).
+
+• string util_make_url(string $path)
+
+	util_make_url('/foo.php?a=1&b=2')
+	⇒ 'https://forge.domain.com/fusionforge/foo.php?a=1&b=2'
+
+  Return an absolute URI for the path in question, containing the
+  system-defined protocol, hostname and (if defined) webroot prefix.
+
+  Both html-encoded and not html-encoded return values of util_gethref
+  are safe to pass as arguments, if their baseurl was only a path.
+
+• integer|false util_nat0(ByRef string $s)
+
+  If and only if $s is the normalised positive integer (ℕ₀)
+  representation of a number, return that number; false otherwise.
+  Limited by system constraints, i.e. usually [0;2³¹-1].
+
+
+‣ common non-HTML utility functions
+
+
+• mixed util_ifsetor(ByRef mixed $val, optional(false) mixed $default)
+
+  If isset($val), return $val, otherwise (no warning) $default.
+
+• string debug_string_backtrace(void)
+
+  Return the current debugging backtrace as string.

Deleted: branches/Branch_5_1/src/docs/README.html:elements
===================================================================
--- branches/Branch_5_1/src/docs/README.html:elements	2012-05-21 09:23:21 UTC (rev 15536)
+++ branches/Branch_5_1/src/docs/README.html:elements	2012-05-21 09:40:09 UTC (rev 15537)
@@ -1,142 +0,0 @@
-Documentation of new HTML element creation functions
-────────────────────────────────────────────────────
-
-Functions defined in src/www/include/html.php → available: always.
-
-
-‣ Element emission functions (do not echo anything)
-
-
-• string html_eo(string $name, optional(empty) array $attrs)
-
-	html_eo('b')
-	⇒ '<b>'
-
-	html_eo('td', array('colspan' => 2))
-	⇒ '<td colspan="2">'
-
-	html_eo('div', array('class' => array('ff', 'important')))
-	⇒ '<div class="ff important">'
-
-	html_eo('img', array(
-		'src' => '…',
-		'ref' => false,
-		'class' => array(),
-		'alt' => "",
-	    ))
-	⇒ '<img src="…" alt="">'
-
-  Generate an XHTML E̲lement O̲pen tag for $name, with attributes
-  defined by key/value pairs properly inserted. Attribute values
-  are coerced into strings from integers (by casting) or arrays
-  (by concatenating the array elements with spaces); if the value
-  is === false or an empty array (count($attrs[n]) == 0), the
-  attribute is not output at all, but for empty values it is; see
-  the img example (admittedly bad, you’d use html_e() for "img").
-
-• string html_e(string $name, optional(empty) array $attrs,
-    optional(empty) string $content, optional(true) bool $shortform)
-
-	html_e('br')
-	⇒ '<br />'
-
-	html_e('a', array('href' => '/foo.php?a=1&b=2'), 'täxt')
-	⇒ '<a href="/foo.php?a=1&b=2">täxt</a>'
-
-	html_e('script', array(
-		'type' => 'text/javascript',
-		'src' => '/js/foo.js',
-	    ), "", false)
-	⇒ '<script type="text/javascript" src="/js/foo.js"></script>'
-	/* needed because <script ... /> does not work */
-
-	html_e('tr', array(), html_e('td', array(), 'bla'))
-	⇒ '<tr><td>bla</td></tr>'
-
-  As with html_eo() the first two arguments define the tag to open.
-  The third argument will be placed between the opening and closing
-  tags but – in contrast to attribute values – not entity-encoded.
-  If the third argument is empty, either a self-closing (default)
-  tag, or, if the fourth argument is false, an open-close sequence,
-  is emitted.
-
-
-‣ Autoclose stack functions
-
-	$spos = html_ap();
-	$s = html_ao('p');
-	if ($foo) {
-		$s .= html_ao('strong');
-	}
-	$s .= html_ao('a', array('href' => '/'));
-	$s .= somefunc();
-	$s .= html_ac($spos);
-	⇒ '<p><strong><a href="/">somefuncreturnvalue</a></strong></p>'
-	⇒ '<p><a href="/">somefuncreturnvalue</a></p>'
-
-• integer html_ap(void)
-
-  Return the a̲utoclose stack’s current p̲osition.
-
-• string html_ao(string $name, optional(empty) array $attrs)
-
-  Works the same as html_eo() but pushes $name onto the a̲utoclose
-  element stack when o̲pening it.
-
-• string html_ac(integer $spos)
-
-  Return a set of closing elements until the a̲utoc̲lose stack
-  has reached the position it had when html_ap() returned $spos.
-
-  If $spos === false: an empty string is returned, for html_aonce().
-
-  If $spos < current stack position, an Exception is raised.
-
-• string html_aonce(ByRef integer $sptr, string $name,
-    optional(empty) array $attrs)
-
-	$spos = false;
-	foreach ($row in $rows) {
-		echo html_aonce('table');
-		echo html_e('tr', array(), html_e('td', array(),
-		    util_html_secure($row['data'])));
-	}
-	echo html_ac($spos);
-	⇒ ''  // if $rows is empty
-	⇒ '<table><tr><td>content1</td></tr><tr><td>content2</td></tr></table>'
-
-  If $sptr is not false, do nothing. Otherwise, set it to
-  the current html_ap() then do html_ao($name, $attrs).
-
-  This function can easily be used to open an enclosing element
-  with mandatory inner elements, such as a table, only once except
-  if no table row were to be generated.
-
-‣ Autoclose stack copy functions
-
-	$spos = html_ap();
-	echo html_ao('tr', array('bgcolor' => '#FF0000'));
-	echo html_ao('td');
-	echo "content 1";
-	$scopy = html_a_copy($spos);
-	echo html_ac($spos);
-	echo html_e('tr', array(), html_e('td', array(), "intermediate"));
-	echo html_a_apply($scopy);
-	echo "content 2";
-	echo html_ac($spos);
-	echo html_a_apply($scopy);
-	echo "content 3";
-	echo html_ac($spos);
-
-	⇒ <tr bgcolor="#FF0000"><td>content 1</td></tr>
-	  <tr><td>intermediate</td></tr>
-	  <tr bgcolor="#FF0000"><td>content 2</td></tr>
-	  <tr bgcolor="#FF0000"><td>content 3</td></tr>
-
-• opaque html_a_copy(integer $spos)
-• string html_a_apply(opaque $scopy)
-
-  Before autoclosing the stack down to a level $spos, you can
-  retrieve a copy of the stack in an opaque format, which can
-  later be used to (re-)open the same elements, with the same
-  attributes, even in a different nesting state.

Deleted: branches/Branch_5_1/src/docs/README.html:utils
===================================================================
--- branches/Branch_5_1/src/docs/README.html:utils	2012-05-21 09:23:21 UTC (rev 15536)
+++ branches/Branch_5_1/src/docs/README.html:utils	2012-05-21 09:40:09 UTC (rev 15537)
@@ -1,102 +0,0 @@
-Documentation of common HTML utility functions
-──────────────────────────────────────────────
-
-Functions defined in src/common/include/utils.php → available: always.
-
-
-• string util_html_encode(string $s)
-
-	util_html_secure('a=1&b=2')
-	⇒ 'a=1&b=2'        // HTML-encoded
-
-	util_html_secure('a=1&b=2')
-	⇒ 'a=1&amp;b=2'    // changed!
-
-  Encode a string for use in XHTML even if it is already encoded.
-
-• string util_html_secure(string $s)
-
-	util_html_secure('a=1&b=2')
-	⇒ 'a=1&b=2'    // HTML-encoded
-
-	util_html_secure('a=1&b=2')
-	⇒ 'a=1&b=2'    // unchanged
-
-  Encode a string for use in XHTML if it is not already encoded.
-  (So, if you use this for output sanitising, other than a slight
-  performance penalty no harm is done if the output was already
-  sane.)
-
-• string util_unconvert_htmlspecialchars(string $s)
-
-	util_unconvert_htmlspecialchars('a=1&b=2')
-	⇒ 'a=1&b=2'    // unchanged
-
-	util_unconvert_htmlspecialchars('a=1&b=2')
-	⇒ 'a=1&b=2'    // HTML-decoded
-
-  Undo util_html_encode; be careful, this can decode partially.
-
-
-• string util_gethref(optional(false) string $baseurl,
-    optional(empty) array $args, optional(true) bool $ashtml,
-    optional('&') string $sep)
-
-	util_gethref("/x.php", array(
-		'foo' => 'a+b&c',
-		'bar' => 'd+b&e',
-	    ));
-	⇒ "/x.php?foo=a%2Bb%26c&bar=d%2Bb%26e"
-
-	util_gethref("/x.php", array(
-		'foo' => 'a+b&c',
-		'bar' => 'd+b&e',
-	    ), false);
-	⇒ /x.php?foo=a%2Bb%26c&bar=d%2Bb%26e
-
-	util_gethref("/x.php", array(
-		'foo' => 'a+b&c',
-		'bar' => 'd+b&e',
-	    ), true, ';')
-	⇒ "/x.php?foo=a%2Bb%26c;bar=d%2Bb%26e"
-
-  Construct an URI for use with util_make_url, session_redirect,
-  html_e('a', array('href' => …)), and similar. The first argument
-  ($baseurl) is passed through as-is but, if falsy, defaults to
-  getStringFromServer('PHP_SELF'); the arguments (both keys and
-  values) are urlencoded (entries while values is false are not
-  emitted at all) and appended, with a question mark in front and
-  the $sep separator in between.
-
-  If $ashtml is true (default), the result will then be run through
-  util_html_encode; set this to false when using in html_e href as
-  value (since html_e will html-encode itself).
-
-• string util_make_url(string $path)
-
-	util_make_url('/foo.php?a=1&b=2')
-	⇒ 'https://forge.domain.com/fusionforge/foo.php?a=1&b=2'
-
-  Return an absolute URI for the path in question, containing the
-  system-defined protocol, hostname and (if defined) webroot prefix.
-
-  Both html-encoded and not html-encoded return values of util_gethref
-  are safe to pass as arguments, if their baseurl was only a path.
-
-• integer|false util_nat0(ByRef string $s)
-
-  If and only if $s is the normalised positive integer (ℕ₀)
-  representation of a number, return that number; false otherwise.
-  Limited by system constraints, i.e. usually [0;2³¹-1].
-
-
-‣ common non-HTML utility functions
-
-
-• mixed util_ifsetor(ByRef mixed $val, optional(false) mixed $default)
-
-  If isset($val), return $val, otherwise (no warning) $default.
-
-• string debug_string_backtrace(void)
-
-  Return the current debugging backtrace as string.




More information about the Fusionforge-commits mailing list