Description of problem: The template for new books have an <orderedlist> inside of a <para>. <section id="sect-Documentation-testmehere-Test_Chapter-Test_Section_2"> <title>Test Section 2</title> <para> This is a test paragraph in Section 2 <orderedlist> <listitem> <para> This is a test listitem. </para> </listitem> </orderedlist> </para> </section> While it is valid docbook, I think it we don't consider it good practice to nest other block elements inside of paras, at least for translation considerations. Might want to change it to: <section id="sect-Documentation-testmehere-Test_Chapter-Test_Section_2"> <title>Test Section 2</title> <para> This is a test paragraph in Section 2. </para> <orderedlist> <listitem> <para> This is a test listitem. </para> </listitem> </orderedlist> </section>
Created attachment 700299 [details] patch for suggested change
(In reply to comment #0) > at least for translation considerations. What considerations are they? Publican >= 3.0 will handle translating nested block tags. $ publican create --name Test_Book --lang en-US $ cd Test_Book/ $ publican update_pot $ publican update_po --langs de-DE $ grep -n 'This is a' de-DE/* de-DE/Chapter.po:22:msgid "This is a test paragraph" de-DE/Chapter.po:32:msgid "This is a test paragraph in a section" de-DE/Chapter.po:42:msgid "This is a test paragraph in Section 2" de-DE/Chapter.po:47:msgid "This is a test listitem."
It's been a while since I had to deal with it, so I don't have a specific example. But I recall problems where translators sometimes ended up with text strings that were difficult to translate because paragraphs got fragmented due to block elements within paragraphs. The fragments made sense in English, but not always in other languages. Not due to a "bug", just bad writing and markup choices on the part of the writer. And while that isn't Publican's fault, I think it would be preferable to have the templates encourage "better" markup choices. Of course "better" is always arguable ... maybe "simpler" ? ;-)
As per #2 publican 3.0+ handle translation of nested blocks. There may be individual cases where writers use creative sentence structures, but the general use case is supported and works well.