Anonymous avatar Anonymous committed 069d2d1

Docs for webhelpers.html.builder

Comments (0)

Files changed (2)

docs/modules/html/builder.rst

 .. automodule:: webhelpers.html.builder
 
 .. currentmodule:: webhelpers.html.builder
+
+Other functions
+---------------
+
+.. autofunction:: lit_sub
+
+``webhelpers.html.builder`` **url_escape** (*s, safe='/'*)
+
+    Urlencode the path portion of a URL. This is the same function as
+    ``urllib.quote`` in the Python standard library. It's exported here
+    with a name that's easier to remember.

webhelpers/html/builder.py

 """HTML/XHTML tag builder
 
-HTML Builder provides an ``HTML`` object that creates (X)HTML tags in a
-Pythonic way,  a ``literal`` class used to mark strings containing intentional
-HTML markup, and a smart ``escape()`` function that preserves literals but
-escapes other strings that may accidentally contain markup characters ("<",
-">", "&") or malicious Javascript tags.  Escaped strings are returned as
-literals to prevent them from being double-escaped later.
+HTML Builder provides: 
+
+* an ``HTML`` object that creates (X)HTML tags in a Pythonic way.  
+
+* a ``literal`` class used to mark strings containing intentional HTML markup. 
+
+* a smart ``escape()`` function that preserves literals but
+  escapes other strings that may accidentally contain markup characters ("<",
+  ">", "&") or malicious Javascript tags.  Escaped strings are returned as
+  literals to prevent them from being double-escaped later.
 
 ``literal`` is a subclass of ``unicode``, so it works with all string methods
 and expressions.  The only thing special about it is the ``.__html__`` method,
     >>> HTML.cdata(u"<p>")
     literal(u'<![CDATA[<p>]]>')
 
-The protocol is simple: if an object has an ``.__html__`` method, ``escape()``
-calls it rather than ``.__str__()`` to obtain a string representation.
-
 About XHTML and HTML
 --------------------
 
-This builder always produces tags that are valid as *both* HTML and
-XHTML.  "Empty" tags (like ``<br>``, ``<input>`` etc) are written like
-``<br />``, with a space and a trailing ``/``.
+This builder always produces tags that are valid as *both* HTML and XHTML.
+"Void" tags -- those which can never have content like ``<br>`` and ``<input>``
+-- are written like ``<br />``, with a space and a trailing ``/``.
 
-*Only* empty tags get this treatment.  The library will never, for
-example, produce ``<script src="..." />``, which is invalid HTML.
+*Only* void tags get this treatment.  The library will never, for
+example, produce ``<script src="..." />``, which is invalid HTML.  Instead
+it will produce ``<script src="..."></script>``.
 
 The `W3C HTML validator <http://validator.w3.org/>`_ validates these
 constructs as valid HTML Strict.  It does produce warnings, but those
 warnings warn about the ambiguity if this same XML-style self-closing
-tags are used for HTML elements that can take content (``<script>``,
+tags are used for HTML elements that are allowed to take content (``<script>``,
 ``<textarea>``, etc).  This library never produces markup like that.
 
 Rather than add options to generate different kinds of behavior, we
 context.
 
 If you _really_ want tags without training slashes (e.g., ``<br>`)`, you can
-"abuse" ``_closed=False`` to produce them.
+abuse ``_closed=False`` to produce them.
 
 """
 import re
 
 def lit_sub(*args, **kw):
     """Literal-safe version of re.sub.  If the string to be operated on is
-    a literal, return a literal result.
+    a literal, return a literal result.  All arguments are passed directly to
+    ``re.sub``.
     """
     lit = hasattr(args[2], '__html__')
     cls = args[2].__class__
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.