3.2 Paragraphs

Paragraphs in a plasTeX document are grouped in the same way that they are grouped in TeX: essentially anything within a section that isn’t a section itself is put into a paragraph. This is different than the HTML model where tables and lists are not grouped into paragraphs. Because of this, it is likely that HTML generated that keeps the same paragraph model will not be 100% valid. However, it is highly unlikely that this variance from validity will cause any real problems in the browser rendering the correct output.

Paragraphs are grouped using the paragraphs method available on all Python macro classes. When this method is invoked on a node, all of the child nodes are grouped into paragraphs. If there are no paragraph objects in the list of child nodes already, one is created. This is done to make sure that the document is fully normalized and that paragraphs occur everywhere that they can occur. This is most noteworthy in constructs like tables and lists where some table cells or list items have multiple paragraphs and others do not. If a paragraph weren’t forced into these areas, you could have inconsistently paragraph-ed content.

Some areas where paragraphs are allowed, but not necessarily needed might not want the forced paragraph to be generated, such as within a grouping of curly braces ({ }). In these cases, you can use the force=False keyword argument to paragraphs. This still does paragraph grouping, but only if there is a paragraph element already in the list of child nodes.