From: Adam C. <ad...@ch...> - 2004-09-17 20:13:36
|
Hi. I have the need to be able to specify a page break, for stylistic and ease-of-reading reasons, when certain sections start. I'm not sure if this should be handled on the writer side, or if a common directive should be used on the ReST end. I'm leaning towards the latter, since there might be several different writers for page-based formats and it should be present in the docutils XML for things like XSL:FO. Two aproaches: 1. A new directive "page-break" which inserts a </pagebreak> node in the doctree at the given point:: .. page-break:: The Section =========== 2. Use the 'class' directive to add a 'new-page' (or a better name?) class to the preceeding section header. A transform would take care of transforming this into a </pagebreak> node in the doctree just before the section header:: The Section =========== .. class:: new-page Any chance for something like this getting implemented? :-) -- Adam Chodorowski <ad...@ch...> Kleptomaniac, n.: A rich thief. -- Ambrose Bierce, "The Devil's Dictionary" |
From: David P. <pr...@sf...> - 2004-09-17 20:19:21
|
On Fri, 17 Sep 2004 22:22:24 +0200, Adam Chodorowski <ad...@ch...> wrote: > 2. Use the 'class' directive to add a 'new-page' (or a better name?) > class to the preceeding section header. A transform would take care > of transforming this into a </pagebreak> node in the doctree just > before the section header:: > > The Section > =========== > .. class:: new-page > This is what I've been using. No transformation, mind; I handle the attribute through XSL. |
From: David G. <go...@py...> - 2004-09-17 21:00:04
|
[Adam Chodorowski] > I have the need to be able to specify a page break, for stylistic > and ease-of-reading reasons, when certain sections start. But not all sections, correct? It all sections began a new page, it would simply be a stylesheet issue. > I'm not sure if this should be handled on the writer side, or if a > common directive should be used on the ReST end. I think the writer is the earliest stage that should be concerned with this. The renderer does the actual pagination of course. > I'm leaning towards the latter, since there might be several > different writers for page-based formats and it should be present in > the docutils XML for things like XSL:FO. But there are also several formats that have no concept of page breaks. > Two aproaches: > > 1. A new directive "page-break" which inserts a </pagebreak> node in > the doctree at the given point:: > > .. page-break:: > > The Section > =========== I'm not too keen on this approach. DocBook has a "beginpage" element, but it seems to be descriptive ("in the printed version, page n begins here") rather than prescriptive ("start a new page here"). I'd want to think long & hard before adding something like this to the document model, which doesn't know or care much about rendering issues. > 2. Use the 'class' directive to add a 'new-page' (or a better name?) > class to the preceeding section header. ... > The Section > =========== > > .. class:: new-page The "class" directive actually applies to the *following* element, so the example should be:: .. class:: new-page The Section =========== This is an approach that can easily be implemented on the back-end. I'd suggest "page-break" or "break-page", since there are many variations (column breaks, recto & verso breaks). > A transform would take care of transforming this into a > </pagebreak> node in the doctree just before the section header:: Again, I wouldn't be hasty making such an addition to the doc tree. > Any chance for something like this getting implemented? :-) Sure, if somebody implements it ;-) -- David Goodger <http://python.net/~goodger> |
From: Adam C. <ad...@ch...> - 2004-09-21 14:04:16
|
On Fri, 2004-09-17 at 22:56, David Goodger wrote: > [Adam Chodorowski] > > I have the need to be able to specify a page break, for stylistic > > and ease-of-reading reasons, when certain sections start. > > But not all sections, correct? It all sections began a new page, it > would simply be a stylesheet issue. Right. Basically, these are sections that "stand out" a bit from the surrounding text flow. In this particular case they are descriptions of specific subprojects within a larger project, so there is normally no "link" from one such section to the other. It's simply easier to read if two subprojects aren't mixed on the same page. > > I'm not sure if this should be handled on the writer side, or if a > > common directive should be used on the ReST end. > > I think the writer is the earliest stage that should be concerned with > this. The renderer does the actual pagination of course. > > > I'm leaning towards the latter, since there might be several > > different writers for page-based formats and it should be present in > > the docutils XML for things like XSL:FO. > > But there are also several formats that have no concept of page > breaks. True, but in that case it can simply be ignored. I think docutils needs to have *some* support for issues that paginated formats deal with to be really usefull. [...] > The "class" directive actually applies to the *following* element, so > the example should be:: > > .. class:: new-page > > The Section > =========== Ah, right. > This is an approach that can easily be implemented on the back-end. > I'd suggest "page-break" or "break-page", since there are many > variations (column breaks, recto & verso breaks). Yes, I think you're right. I didn't really like the idea of a real doctree node, since "page-break" smells very much like a layout issue. If using class is the way to go, I think it would be good if all page-based writers supported the same class name. Perhaps specifying "standard class names and their meaning" somewhere? (I know it's just one class now, but there might be more later). I don't really like the name "break-page" either though. Still smells a bit to much like a layout issue in the wrong place. Is there some other good word/concept for sections that "are outside the normal section-flow of the document"? In the same way that "sidebar" is text outside the normal text flow... -- Adam Chodorowski <ad...@ch...> How To Keep A Healthy Level Of Insanity: 9. As often as possible, skip rather than walk. |
From: David G. <go...@py...> - 2004-09-21 14:24:46
|
[Adam Chodorowski] > I think docutils needs to have *some* support for issues that > paginated formats deal with to be really usefull. It does: classes :-) > If using class is the way to go, I think it would be good if all > page-based writers supported the same class name. Perhaps > specifying "standard class names and their meaning" somewhere? (I > know it's just one class now, but there might be more later). Sure. When we have more than one writer that supports classes, we should aim toward that kind of standardization. I think it may be too early now though. > I don't really like the name "break-page" either though. Still > smells a bit to much like a layout issue in the wrong place. Is > there some other good word/concept for sections that "are outside > the normal section-flow of the document"? In this case, I'd recommend "subproject". It's descriptive and apt. In a paper-oriented format, it could translate to a page break, but in a display-oriented format, it may have some other meaning. I think there may be a need for a separate mapping of classes to concrete rendering functions; a stylesheet of sorts. Aahz did some initial work on class stylesheets; see docs/dev/todo.txt. -- David Goodger <http://python.net/~goodger> |
From: Adam C. <ad...@ch...> - 2004-09-21 18:58:52
|
On Tue, 2004-09-21 at 16:23, David Goodger wrote: [...] > > I don't really like the name "break-page" either though. Still > > smells a bit to much like a layout issue in the wrong place. Is > > there some other good word/concept for sections that "are outside > > the normal section-flow of the document"? > > In this case, I'd recommend "subproject". It's descriptive and apt. > In a paper-oriented format, it could translate to a page break, but > in a display-oriented format, it may have some other meaning. That gave me an idea; how about "subdocument"? Conceptually that's actually what it is, since the "subdocument" section can ofcourse have subsection. So it's a bit like a somewhat standalone mini-document within the document. > I think there may be a need for a separate mapping of classes to > concrete rendering functions; a stylesheet of sorts. Aahz did some > initial work on class stylesheets; see docs/dev/todo.txt I'm not quite sure what the point would be. Each writer format often has it's own stylesheet system, so it seems like asking for trouble to include some kind of generic layout code inside docutils. Perhaps I've misunderstood what it would be used for though... -- Adam Chodorowski <ad...@ch...> Disclaimer: I do not, in fact, want to set real people on fire. Not only is it wildly illegal and immoral, it smells bad and would probably get bits of ash and melted flesh all over my clothes. I neither condone nor support the setting of people on fire. -- Dom / MegaTokyo |
From: Aahz <aa...@py...> - 2004-09-21 19:09:22
|
On Tue, Sep 21, 2004, Adam Chodorowski wrote: > On Tue, 2004-09-21 at 16:23, David Goodger wrote: >> >> I think there may be a need for a separate mapping of classes to >> concrete rendering functions; a stylesheet of sorts. Aahz did some >> initial work on class stylesheets; see docs/dev/todo.txt > > I'm not quite sure what the point would be. Each writer format often has > it's own stylesheet system, so it seems like asking for trouble to > include some kind of generic layout code inside docutils. Perhaps I've > misunderstood what it would be used for though... I'm not sure what David thinks I was working on; what I was working on was a workaround for Frame's lack of hierarchical styles. Essentially, it was an add-on for reST, defining a class system framework for creating styles that would then need a writer for generating styles in specific output formats. But I never got far with it. -- Aahz (aa...@py...) <*> http://www.pythoncraft.com/ "A foolish consistency is the hobgoblin of little minds, adored by little statesmen and philosophers and divines." --Ralph Waldo Emerson |
From: David G. <go...@py...> - 2004-10-01 15:25:36
Attachments:
signature.asc
|
[Adam Chodorowski] > That gave me an idea; how about "subdocument"? You can call it whatever you like, of course. When I think of subdocuments though, I think of a large document made up of many files, one file per "subdocument". -- David Goodger <http://python.net/~goodger> |
From: David G. <go...@py...> - 2004-10-01 15:30:35
Attachments:
signature.asc
|
[David Goodger] >> I think there may be a need for a separate mapping of classes to >> concrete rendering functions; a stylesheet of sorts. Aahz did some >> initial work on class stylesheets; see docs/dev/todo.txt [Adam Chodorowski] > I'm not quite sure what the point would be. The point is that the author can define their own set of descriptive classes (also applies to custom interpreted text roles), and a mapping between those classes and a standard set of "concrete" classes. In this case, a document says "subproject", and the renderer understands that to mean "page-break". Given a standard set of styles that Writers generate, such a mapping could allow easy creation of custom descriptive markup. [Aahz] > I'm not sure what David thinks I was working on; what I was working > on was a workaround for Frame's lack of hierarchical styles. > Essentially, it was an add-on for reST, defining a class system > framework for creating styles that would then need a writer for > generating styles in specific output formats. But I never got far > with it. Yes, that's what I thought you were working on. We're on the same wavelength. I saw your simple implementation and thought that it might be more generally useful. I haven't worked out any details yet though; it's all just hand-waving. -- David Goodger <http://python.net/~goodger> |