r18913 - /trunk/lib/text/sectioning.py -- March 20, 2013 - 14:57

Author: bugman
Date: Wed Mar 20 14:57:41 2013
New Revision: 18913

URL: http://svn.gna.org/viewcvs/relax?rev=18913&view=rev
Log:
Expansion of the lib.text.sectioning module.

The following new functions have been added:  box(), section(), subsection(), 
subsubsection(),
subtitle(), subsubtitle(), underline().


Modified:
    trunk/lib/text/sectioning.py

Modified: trunk/lib/text/sectioning.py
URL: 
http://svn.gna.org/viewcvs/relax/trunk/lib/text/sectioning.py?rev=18913&r1=18912&r2=18913&view=diff
==============================================================================
--- trunk/lib/text/sectioning.py (original)
+++ trunk/lib/text/sectioning.py Wed Mar 20 14:57:41 2013
@@ -23,27 +23,99 @@
 """Functions for the formatting of titles, subtitles and other sectioning."""
 
 
+def box(file=None, text=None, char=None):
+    """Format and write out a box surrounding the text.
+
+    @keyword file:      The file object to write to.
+    @type file:         file object
+    @keyword text:      The text to box.
+    @type text:         str
+    @keyword char:      The single character to use for the box.
+    @type char:         str
+    """
+
+    # The length and horizontal box text.
+    length = len(text) + 4
+    hline = char * length
+
+    # The text.
+    file.write("%s\n" % hline)
+    file.write("%s %s %s\n" % (char, text, char))
+    file.write("%s\n" % hline)
+
+
+def section(file=None, text=None):
+    """Format and write out a section to the given file.
+
+    @keyword file:      The file object to write to.
+    @type file:         file object
+    @keyword text:      The section text.
+    @type text:         str
+    """
+
+    # Underline the text.
+    file.write("\n\n")
+    underline(file=file, text=text, char="=")
+    file.write("\n")
+
+
+def subsection(file=None, text=None):
+    """Format and write out a subsection to the given file.
+
+    @keyword file:      The file object to write to.
+    @type file:         file object
+    @keyword text:      The subsection text.
+    @type text:         str
+    """
+
+    # Underline the text.
+    file.write("\n")
+    underline(file=file, text=text, char="-")
+    file.write("\n")
+
+
+def subsubsection(file=None, text=None):
+    """Format and write out a subsubsection to the given file.
+
+    @keyword file:      The file object to write to.
+    @type file:         file object
+    @keyword text:      The subsubsection text.
+    @type text:         str
+    """
+
+    # Underline the text.
+    file.write("\n")
+    underline(file=file, text=text, char="~")
+    file.write("\n")
+
+
+def subsubtitle(file=None, text=None):
+    """Format and write out a subsubtitle to the given file.
+
+    @keyword file:      The file object to write to.
+    @type file:         file object
+    @keyword text:      The subsubtitle text.
+    @type text:         str
+    """
+
+    # Box the text.
+    file.write("\n")
+    box(file=file, text=text, char="~")
+    file.write("\n")
+
+
 def subtitle(file=None, text=None):
     """Format and write out a subtitle to the given file.
 
     @keyword file:      The file object to write to.
     @type file:         file object
-    @keyword text:      The subtitle.
+    @keyword text:      The subtitle text.
     @type text:         str
     """
 
-    # The length and hline text.
-    length = len(text) + 2
-    hline = '#' * length
-
-    # First the spacing above the section.
+    # Box the text.
     file.write("\n")
-
-    # The text.
-    file.write("# %s\n" % text)
-    file.write("%s\n" % hline)
-
-    # Final spacing.
+    box(file=file, text=text, char="-")
     file.write("\n")
 
 
@@ -52,21 +124,31 @@
 
     @keyword file:      The file object to write to.
     @type file:         file object
-    @keyword text:      The title.
+    @keyword text:      The title text.
     @type text:         str
     """
 
-    # The length and hline text.
-    length = len(text) + 4
-    hline = '#' * length
+    # Box the text.
+    file.write("\n\n")
+    box(file=file, text=text, char="=")
+    file.write("\n")
 
-    # First the spacing above the section.
-    file.write("\n\n")
+
+def underline(file=None, text=None, char=None):
+    """Format and write out the text underlined by the given character.
+
+    @keyword file:      The file object to write to.
+    @type file:         file object
+    @keyword text:      The text to underline.
+    @type text:         str
+    @keyword char:      The single character to use for the underline.
+    @type char:         str
+    """
+
+    # The length and horizontal underline text.
+    length = len(text)
+    hline = char * length
 
     # The text.
+    file.write("%s\n" % text)
     file.write("%s\n" % hline)
-    file.write("# %s #\n" % text)
-    file.write("%s\n" % hline)
-
-    # Final spacing.
-    file.write("\n")