From: Felix W. <Fel...@gm...> - 2005-05-05 15:49:26
|
I need section subtitles. My idea is to transform :: <section> <title> Title <section> <title> Subtitle <paragraph> Section contents. into :: <section> <title> Title <subtitle> Subtitle <paragraph> Section contents. It works like doctitle transformation, actually. My idea for the implementation in the HTML writer:: <h1>Title</h1> <h1 class="section-subtitle">Subtitle</h1> (<h2> for the subtitle doesn't seem reasonable since it messes up the document structure.) In the CSS file: h1.section-subtitle, h2.section-subtitle, ... { font-size: 70%; } My quick'n'dirty implementation for the transform is below (no writer implementation yet). DocTitle and SectionSubTitle should have a common base class, but I don't have enough time to clean it up now; I wanna hear your comments first. Regarding when to transform section subtitles, I'd say we add an option (section_subtitle_xform or so [1]_). But I'm not yet sure about the default; "true" as a default might be not that bad (and it would be analog to doctitle_xform), but it causes a (slight?) change of some existing reST documents. So what would you like to see as a default? .. [1] Am I the only one who thinks "xform" sounds bad? Maybe it should all be renamed to "transform", maintaining compatibility for some time. ------------------------------------------------------------------------ Index: test/test_transforms/test_doctitle.py =================================================================== --- test/test_transforms/test_doctitle.py (revision 3293) +++ test/test_transforms/test_doctitle.py (working copy) @@ -11,7 +11,7 @@ """ from __init__ import DocutilsTestSupport -from docutils.transforms.frontmatter import DocTitle +from docutils.transforms.frontmatter import DocTitle, SectionSubTitle from docutils.parsers.rst import Parser @@ -23,7 +23,7 @@ totest = {} -totest['section_headers'] = ((DocTitle,), [ +totest['section_headers'] = ((DocTitle, SectionSubTitle), [ ["""\ .. test title promotion @@ -188,6 +188,39 @@ This title should be the document title despite the substitution_definition. """], +["""\ +This is no doc title. + +=============== + Section Title +=============== + +Subtitle +======== + +----------------- + Another Section +----------------- + +Another Subtitle +---------------- + +""", +"""\ +<document source="test data"> + <paragraph> + This is no doc title. + <section ids="section-title" names="section title"> + <title> + Section Title + <subtitle ids="subtitle" names="subtitle"> + Subtitle + <section ids="another-section" names="another section"> + <title> + Another Section + <subtitle ids="another-subtitle" names="another subtitle"> + Another Subtitle +"""], ]) Index: docutils/transforms/frontmatter.py =================================================================== --- docutils/transforms/frontmatter.py (revision 3293) +++ docutils/transforms/frontmatter.py (working copy) @@ -107,24 +107,23 @@ def apply(self): if not getattr(self.document.settings, 'doctitle_xform', 1): return - if self.promote_document_title(): - self.promote_document_subtitle() + if self.promote_title(self.document): + self.promote_subtitle(self.document) - def promote_document_title(self): - section, index = self.candidate_index() + def promote_title(self, node): + section, index = self.candidate_index(node) if index is None: return None - document = self.document - # Transfer the section's attributes to the document element (at root): - document.attributes.update(section.attributes) - document[:] = (section[:1] # section title - + document[:index] # everything that was in the - # document before the section - + section[1:]) # everything that was in the section + # Transfer the section's attributes to the node: + node.attributes.update(section.attributes) + node[:] = (section[:1] # section title + + node[:index] # everything that was in the + # node before the section + + section[1:]) # everything that was in the section return 1 - def promote_document_subtitle(self): - subsection, index = self.candidate_index() + def promote_subtitle(self, node): + subsection, index = self.candidate_index(node) if index is None: return None subtitle = nodes.subtitle() @@ -132,31 +131,39 @@ subtitle.attributes.update(subsection.attributes) # Transfer the contents of the subsection's title to the subtitle: subtitle[:] = subsection[0][:] - document = self.document - document[:] = (document[:1] # document title - + [subtitle] - # everything that was before the section: - + document[1:index] - # everything that was in the subsection: - + subsection[1:]) + node[:] = (node[:1] # title + + [subtitle] + # everything that was before the section: + + node[1:index] + # everything that was in the subsection: + + subsection[1:]) return 1 - def candidate_index(self): + def candidate_index(self, node): """ Find and return the promotion candidate and its index. Return (None, None) if no valid candidate was found. """ - document = self.document - index = document.first_child_not_matching_class( - nodes.PreBibliographic) - if index is None or len(document) > (index + 1) or \ - not isinstance(document[index], nodes.section): + index = node.first_child_not_matching_class( + nodes.PreBibliographic) + if index is None or len(node) > (index + 1) or \ + not isinstance(node[index], nodes.section): return None, None else: - return document[index], index + return node[index], index +class SectionSubTitle(DocTitle): + + default_priority = 330 + + def apply(self): + for section in self.document.traverse(lambda n: + isinstance(n, nodes.section)): + self.promote_subtitle(section) + + class DocInfo(Transform): """ ------------------------------------------------------------------------ -- For private mail please ensure that the header contains 'Felix Wiemann'. http://www.ososo.de/ |
From: Felix W. <Fel...@gm...> - 2005-05-07 16:25:42
|
Felix Wiemann wrote: > Regarding when to transform section subtitles, I'd say we add an option > (section_subtitle_xform or so [1]_). But I'm not yet sure about the > default; About the default: I just noticed that it would break <http://docutils.sf.net/FAQ.html#can-i-use-docutils-for-python-auto-documentation>, because there we have a section (section 4) which has only one subsection. So it's probably best not to transform section subtitles by default. Hmm. Any comments on this? I'd like to get in sync to the trunk again. -- For private mail please ensure that the header contains 'Felix Wiemann'. http://www.ososo.de/ |
From: David G. <go...@py...> - 2005-05-08 00:08:09
Attachments:
signature.asc
|
[Felix Wiemann] > I need section subtitles. +1. Go for it. > My idea for the implementation in the HTML writer:: > > <h1>Title</h1> > <h1 class="section-subtitle">Subtitle</h1> > > (<h2> for the subtitle doesn't seem reasonable since it messes up > the document structure.) In the CSS file: > > h1.section-subtitle, h2.section-subtitle, ... { > font-size: 70%; > } Seems fine. > Regarding when to transform section subtitles, I'd say we add an > option (section_subtitle_xform or so [1]_). +1. > .. [1] Am I the only one who thinks "xform" sounds bad? Maybe it > should all be renamed to "transform", maintaining compatibility > for some time. -1. It's not worth the trouble. > But I'm not yet sure about the default; "true" as a default might be > not that bad (and it would be analog to doctitle_xform), but it > causes a (slight?) change of some existing reST documents. So what > would you like to see as a default? Make it "true". > About the default: I just noticed that it would break > <http://docutils.sf.net/FAQ.html#can-i-use-docutils-for-python-auto-documentation>, > because there we have a section (section 4) which has only one > subsection. So it's probably best not to transform section > subtitles by default. I don't know about that. The FAQ is a special case; there's a single subsection only because we anticipate future subsections. There's not much difference (visually or structurally) between a section title & subtitle, and a section title with single subsection title. In other words, a section whose sole content is a single subsection, is a degenerate case that doesn't make much sense from a document structure perspective. Therefore, we shouldn't worry about it much. However, I have another case that we should consider: Section 1 Title =============== Section 1 Subtitle ------------------ text Section 2 Title =============== text Subsection 2.1 Title -------------------- text The adornment of "Section 1 Subtitle" and "Subsection 2.1 Title" must be the same to parse, but structurally they're different. Would this be confusing to authors or readers of the text source? -- David Goodger <http://python.net/~goodger> |
From: Felix W. <Fel...@gm...> - 2005-05-18 23:05:08
|
David Goodger wrote: > Felix Wiemann wrote: > >> I need section subtitles. > > +1. Go for it. Done. >> My idea for the implementation in the HTML writer:: >> >> <h1>Title</h1> >> <h1 class="section-subtitle">Subtitle</h1> >> >> (<h2> for the subtitle doesn't seem reasonable since it messes up >> the document structure.) In the CSS file: >> >> h1.section-subtitle, h2.section-subtitle, ... { >> font-size: 70%; >> } > > Seems fine. Sorry, I forgot to implement HTML writer support. Will do tomorrow. >> Regarding when to transform section subtitles, I'd say we add an >> option (section_subtitle_xform or so [1]_). > > +1. Mmmh. I called it sectsubtitle_xform to make it analogous to doctitle_xform. Should it be changed to section_subtitle_xform? (I'm not sure.) >> About the default: I just noticed that it would break >> >> <http://docutils.sf.net/FAQ.html#can-i-use-docutils-for-python-auto-documentation>, >> because there we have a section (section 4) which has only one >> subsection. So it's probably best not to transform section subtitles >> by default. > > I don't know about that. The FAQ is a special case; there's a single > subsection only because we anticipate future subsections. Yeah, but I expect you have that case quite often, given that documents often evolve and are processed to HTML even if they are in an intermediate stage. > There's not much difference (visually or structurally) between a > section title & subtitle, and a section title with single subsection > title. Oh, there *are* visual differences: * Subtitles aren't numbered. * Subtitles aren't listed in the TOC. So for many cases activating section subtitles by default would change not only the semantics but also the rendering of existing documents. Even worse, authors might write implicit section subtitles without noticing it because often it *is* visually indistinguishable, and then they're struck by weird unexplainable behavior when using section numbering or adding a TOC. Thus it's probably a bad idea to activate it by default. > In other words, a section whose sole content is a single subsection, > is a degenerate case that doesn't make much sense from a document > structure perspective. It may be degenerate but it occurs, esp. in incomplete documents. > However, I have another case that we should consider: > > Section 1 Title > =============== > Section 1 Subtitle > ------------------ > text > > Section 2 Title > =============== > text > > Subsection 2.1 Title > -------------------- > text > > The adornment of "Section 1 Subtitle" and "Subsection 2.1 Title" must > be the same to parse, but structurally they're different. Would this > be confusing to authors or readers of the text source? It's a bit confusing, yes. I see two solutions: * Loosening the reST spec to allow inconsistent adornment:: Section 1 Title =============== Section 1 Subtitle ~~~~~~~~~~~~~~~~~~ text Section 2 Title =============== text Subsection 2.1 Title -------------------- text * Wait for complaints. -- For private mail please ensure that the header contains 'Felix Wiemann'. http://www.ososo.de/ |
From: David G. <go...@py...> - 2005-05-19 01:09:48
Attachments:
signature.asc
|
[Felix Wiemann] > Thus it's probably a bad idea to activate it by default. +1 ... > I see two solutions: > > * Loosening the reST spec to allow inconsistent adornment:: ... > * Wait for complaints. I vote we wait ;-) -- David Goodger <http://python.net/~goodger> |