Luke Plant avatar Luke Plant committed e55d520

Added some comments

Comments (0)

Files changed (1)

semanticeditor/utils/presentation.py

 # Section 2, this would require a div structure incompatible with the
 # above. Thus the column layout is limited by the logical structure of
 # the document.
+#
+# While the above is a real constraint, we try to be as flexible as
+# possible within it.  The user may want to be able to apply column
+# breaks to paragraphs, not just section headings.  In order to
+# support this, consider the following
+#
+# - H1 - NEWROW  - 2 col row
+# - H1 - NEWCOL
+# - H1 - NEWROW  - simply to finish the existing column structure
+#  - p - NEWROW  - this is where the column structure actual starts
+#  - p - NEWCOL
+#
+# The first 'p' will be contained in the 'row1col' div that wraps the
+# preceding H1 and its contents. So, for the case of being at the
+# beginning of a single column row, we allow a nested column
+# structure.  This imposes a constraint on what follows - a H1
+# following the second 'p' cannot have 'NEWCOL' because that would
+# make the previous H1 into the start of a *2* column row!
 
 
 def format_html(html, styleinfo):
     Formats the XHTML given using a dictionary of style information.
     The dictionary has keys which are the names of headings,
     and values which are lists of CSS classes or special commands.
-    Commands start with 'command:', CSS classes start with 'class:'
     """
     root = parse(html)
     structure = get_structure(root, assert_structure=True)
                if tag.lower() in headingdef]
 
     # Cut the HTML up into sections
+
     # First deal with headers only.  This makes life simple,
     # as headers always produce nested structures, and the
     # indexes passed to wrap_elements_in_tag don't need
 
 
 def _add_rows_and_columns(topnode, known_nodes, styleinfo):
+    # This is the most involved and tricky part.  See the comments
+    # above the 'format_html' function.
+
     cur_row_start = None
     cur_col = None
     children = list(topnode.getchildren())
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.