From: Red W. <red...@gm...> - 2008-10-19 16:15:15
|
Hi members of the docutils mailing lists! I've recently discovered reStructuredText and I'm really fascinated. I like it very much. However, what I'm missing are line breaks. Normally, each paragraph becomes a <p> when converting to HTML (or a similar construct when converting to other formats). But sometimes, you want to separate two blocks of text *without* putting an empty line in between. I thought thoroughly about how line breaks could be realized in a comfortable way. I came up with the following idea: An option to connect paragraphs: Instead of defining a "line break" symbol, making it possible to connect two or more paragraphs using two "connection symbols" ( eg. { and } ). I'm going to explain what I mean by using an example: { reStructuredText is an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and parser system. RST is designed for extensibility for specific application domains. Its parser is a component of Docutils. } This document defines the goals of reStructuredText and provides a history of the project. It is written using the reStructuredText markup... Converting to HTML, this would be transformed into something like: <p> reStructuredText is an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and parser system. <br /> RST is designed for extensibility for specific application domains. Its parser is a component of Docutils. </p> <p> This document defines the goals of reStructuredText and provides a history of the project. It is written using the reStructuredText markup... </p> Which would result in the following visible output: reStructuredText is an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and parser system. RST is designed for extensibility for specific application domains. Its parser is a component of Docutils. This document defines the goals of reStructuredText and provides a history of the project. It is written using the reStructuredText markup... Note that the word "RST" neither is in the same line as the preceding sentence, nor is at the beginning of a new paragraph after a blank line. Of course, as usual, the length of lines without line breaks depends on the document width (e.g. the window width of a browser displaying the HTML). Another example: { If you often get errors of the kind "Invalid configuration. Configuration file: config123.conf" you should do bla bla. } This would result in the following visible output: If you often get errors of the kind "Invalid configuration. Configuration file: config123.conf" you should do bla bla. Note that there are no empty lines in between. Without using the "connection symbols" it would be harder to read this as a single sentence because of the empty lines. The other possibility to write everything into a normal paragraph would also produce a rather ugly result. Finally, I want to list some advantages of the "connection symbols" idea I can think of: 1. People writing documents which make a vast use of both line breaks and normal separated paragraphs (e.g. novels) now could easily do this using reStructuredText. 2. The source code still is nicely readable. There are no "linebreak symbols" in the text blocks which would interrupt the reading flow. 3. Using the "connection symbols" doesn't force the user to change indention levels. So normal paragraphs and connected paragraphs could be mixed without making the source code look bad. AFAIK, indention would be required if one used a RST directive instead of the proposed "connection symbols". 4. Outputs like the one in my second example are possible which, at the moment, aren't possible. What do you think about this idea? |
From: David G. <go...@py...> - 2008-10-19 16:54:54
|
On Sun, Oct 19, 2008 at 12:06, Red Wraith <red...@gm...> wrote: > Hi members of the docutils mailing lists! > > I've recently discovered reStructuredText and I'm really fascinated. I > like it very much. Welcome! > However, what I'm missing are line breaks. I think line blocks will suit your purpose: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#line-blocks -- David Goodger <http://python.net/~goodger> |
From: Red W. <red...@gm...> - 2008-10-20 19:09:23
|
| David Goodger wrote: | > I think line blocks will suit your purpose: | > http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#line-blocks | I know about the line-block feature but I think it is rather uncomfortable for writing documents which often use line breaks. Having to write always | in the right line and having to indent the lines all the time is stressful IMO. | Imagine you're writing, for example, a novel where you almost always use line breaks instead of normal paragraphs. Only when you're changing the point of view (or similar), you want to have a blank line. However, if there is only the line-block feature you always have to bother with the pipe symbols and the indention (on *every* line!). | If there were such connection symbols like I proposed, one would only have to write a { or a } every now and then. Furthermore, when mixing normal paragraphs and line-blocks, the source code becomes ugly because of the different indention levels (which, in fact, don't cause different indentions in the output). I realized, that the second example of my last mail was a bad example. For such _rare_ and short applications the line-block feature works and is okay: | If you often get errors of the kind | "Invalid configuration. Configuration file: config123.conf" | you should do bla bla. | However, many other things can't be done if there is only the line-block feature. For example, one can't connect "Literal Blocks" to other paragraphs without producing gaps in the output. | One also can't put lists directly after a text block without producing an empty space between, etc. | Moreover, you always have to care about the length of your lines when writing the source document if you're using line-blocks excessively. You can't simply use the wrap function of your text editor, but you have to insert real line breaks in the source file, unless you want your source file to become very hard to read (the wrap will cause a different indention level than your other lines normally have). | Sometimes you can't even add a line break in the source file, e.g. when you're writing a very long URL. Last but not least, a source document which often uses line-blocks become almost unreadable if the text editor, which is used for displaying the source file, uses a shorter width than the original line width the file was written for (and automatic wrapping applies). PS: Until here, I used the line-block feature for this mail to demonstrate that it's not very comfortable for writing such documents. Of course, for this certain case, I could've written this mail only using normal paragraphs, but that's not the point. PPS: I am using a news reader to send this mail. I'm not subscribed to the mailing list. I'm not sure if this might prevent me from receiving all answers. Until now, I've received one answer to this thread in total. |
From: Roberto A. <ra...@ne...> - 2008-10-20 19:26:28
|
On Monday 20 October 2008 17:09:02 Red Wraith wrote: > | Imagine you're writing, for example, a novel where you > > almost always use line breaks instead of normal > paragraphs. Only when you're changing the point of view > (or similar), you want to have a blank line. However, if > there is only the line-block feature you always have to > bother with the pipe symbols and the indention (on > *every* line!). You could use a line block only when you need the extra space. This is a regular paragraph. This is another | This is one with extra spacebefore it. Then configure no inter-paragraph spacing. -- ("\''/").__..-''"`-. . Roberto Alsina `9_ 9 ) `-. ( ).`-._.`) KDE Developer (MFCH) (_Y_.)' ._ ) `._`. " -.-' http://lateral.netmanagers.com.ar _..`-'_..-_/ /-'_.' The 6,855th most popular site of Slovenia (l)-'' ((i).' ((!.' according to alexa.com (27/5/2007) Debugging is twice as hard as writing the code in the first place. Therefore, if you write the code as cleverly as possible, you are, by definition, not smart enough to debug it. --Brian W. Kernighan |
From: David G. <go...@py...> - 2008-10-20 19:49:32
|
On Mon, Oct 20, 2008 at 15:09, Red Wraith <red...@gm...> wrote: > | I know about the line-block feature but I think it is > rather uncomfortable for writing documents which often > use line breaks. Having to write always | in the right > line and having to indent the lines all the time is > stressful IMO. > | Imagine you're writing, for example, a novel where you > almost always use line breaks instead of normal > paragraphs. ... ISTM that your use case is just too esoteric for reStructuredText. reST is designed to support standard prose styles with a readable syntax. It is not meant to support experimental styles of writing and layout. If there are real-world examples of the kind of documents you're talking about, please provide evidence (e.g. URLs). Apart from indentation, reST doesn't have the concept of begin/end markers for block-level constructs. That's a design decision. IMO what you're proposing does not fit the reST aesthetic. -1. Possible alternatives: * Use a "container" directive and define a corresponding style that removes vertical whitespace from paragraphs (http://docutils.sourceforge.net/docs/ref/rst/directives.html#container). * Use the "compound" directive to indicate compound paragraphs, and apply a style to them. You'll still need to indent though. (http://docutils.sourceforge.net/docs/ref/rst/directives.html#compound-paragraph) * Create a directive that does what you want, release it to the world, and gather support. Perhaps with widespread support the change will make more sense. > | However, many other things can't be done if there is only > the line-block feature. For example, one can't connect > "Literal Blocks" to other paragraphs without producing > gaps in the output. > | One also can't put lists directly after a text block > without producing an empty space between, etc. Why would one *want* to do either of these? > | Moreover, you always have to care about the length of > your lines when writing the source document if you're > using line-blocks excessively. reST is a 2-D markup language. One cost of this is that indentation and line breaks can be significant. > Last but not least, a source document which often uses > line-blocks become almost unreadable if the text editor, > which is used for displaying the source file, uses a > shorter width than the original line width the file was > written for (and automatic wrapping applies). So widen your text editor window, or turn off auto-wrapping. Line blocks normally are not used that often anyhow. > PS: Until here, I used the line-block feature for this mail to > demonstrate that it's not very comfortable for writing such documents. > Of course, for this certain case, I could've written this mail only > using normal paragraphs, but that's not the point. Understood, but it wasn't convincing. "Such documents" are not common. Show me some real-world examples and maybe I'll understand better. But sorry, reST isn't going to adapt to your unique personal writing style. > PPS: I am using a news reader to send this mail. I'm not subscribed to > the mailing list. I'm not sure if this might prevent me from receiving > all answers. Until now, I've received one answer to this thread in total. Before your reply there was only one answer on the mailing list, mine. If you're using a mail/news gateway like Gmane.org, anything sent to the mailing list will show up. -- David Goodger <http://python.net/~goodger> |
From: Alan G I. <ai...@am...> - 2008-10-20 20:52:44
|
> On Mon, Oct 20, 2008 at 15:09, Red Wraith <red...@gm...> wrote: >> | However, many other things can't be done if there is only >> the line-block feature. For example, one can't connect >> "Literal Blocks" to other paragraphs without producing >> gaps in the output. >> | One also can't put lists directly after a text block >> without producing an empty space between, etc. On 10/20/2008 3:49 PM David Goodger wrote: > Why would one *want* to do either of these? One might take a different view of what constitutes a "paragraph" than was taken in the HTML specifications. E.g., a paragraph can certainly contain inline lists, and by extension it can be reasonable for a "paragraph" to contain e.g. a bulleted list. Similarly for a literal block. (Some people argue that this violates the definition of a "paragraph", but I would argue that the writer gets to determine what constitutes a "paragraph". Whatever.) I would find a compound directive (as David suggested) to be the most natural way to achieve the desired grouping (which visually ends up being a matter of vertical space). This seems most like to be translatable into a variety of output formats. But if the target format is only HTML, the use of adjacent sbiling selectors offers a variety of ways to procede. http://www.w3.org/TR/CSS2/selector.html#adjacent-selectors Cheers, Alan Isaac |
From: Stefan R. <lis...@st...> - 2008-10-21 05:49:41
|
on 20.10.2008 21:49 David Goodger said the following: > On Mon, Oct 20, 2008 at 15:09, Red Wraith <red...@gm...> wrote: >> | I know about the line-block feature but I think it is >> rather uncomfortable for writing documents which often >> use line breaks. Having to write always | in the right >> line and having to indent the lines all the time is >> stressful IMO. >> | Imagine you're writing, for example, a novel where you >> almost always use line breaks instead of normal >> paragraphs. > ... > > ISTM that your use case is just too esoteric for reStructuredText. <snip> > Possible alternatives: > <snip-container-directive> > <snip-compound-directive> > <snip-custom-directive> > Or, possibly easier for your use-case above, change the style file (css for html) to remove inter-paragraph margins generally, and define a class to re-add the whitespace when wanted:: The first paragraph The second, no space between us two. .. class:: morespacewantedhere Now we have a new block of text here... >> | However, many other things can't be done if there is only >> the line-block feature. For example, one can't connect >> "Literal Blocks" to other paragraphs without producing >> gaps in the output. >> | One also can't put lists directly after a text block >> without producing an empty space between, etc. > > Why would one *want* to do either of these? A similar solution can be found for these ideas. cheers, stefan |
From: Red W. <red...@gm...> - 2008-10-21 19:13:32
|
Thank you all for your comments and suggestions. David Goodger wrote: > If there are real-world examples of the kind of documents you're > talking about, please provide evidence (e.g. URLs). I looked into my bookshelf and found some books which were written in the style I mentioned. I have to admit that I thought more authors used this style but still there are some. I searched for some free ebooks which use that style. They are written in German but that shouldn't matter because the text itself is not important. Note, that I randomly selected these books. I've never read any of those. Here are the links: http://i-bux.com/support-files/jamesundlilly.pdf http://neue_atheisten.ja-nee.de/terryrotter.pdf http://www.talon-abenteuer.de/data/talon010/talon010.htm In the second document one sees that the author uses, amongst other things, line breaks for all dialogs David Goodger wrote: > Apart from indentation, reST doesn't have the concept of begin/end > markers for block-level constructs. That's a design decision. IMO what > you're proposing does not fit the reST aesthetic. > Hm. The "compound" directive and the "container" directive unfortunately require indenting. In addition to that, they require rather much text to write comparing to { and }. However, at least, probably they wouldn't require much modding of the style files. The suggestions of Roberto Alsina and Stefan Rank wouldn't require indenting. The idea of Roberto Alsina would also be very easy to use (only one symbol needed to write). However, I'm afraid, one would have to heavily modify the style files with either suggestion. David Goodger wrote: > Why would one *want* to do either of these? Just for aesthetics. Of course, beauty always is in the eye of the beholder. |
From: Roberto A. <ra...@ne...> - 2008-10-21 19:35:35
|
On Tuesday 21 October 2008 17:13:11 Red Wraith wrote: > The "compound" directive and the "container" directive unfortunately > require indenting. In addition to that, they require rather much text to > write comparing to { and }. However, at least, probably they wouldn't > require much modding of the style files. > The suggestions of Roberto Alsina and Stefan Rank wouldn't require > indenting. The idea of Roberto Alsina would also be very easy to use > (only one symbol needed to write). However, I'm afraid, one would have > to heavily modify the style files with either suggestion. For my suggestion I expect you only need to change one property of the p element (in html at least). -- ("\''/").__..-''"`-. . Roberto Alsina `9_ 9 ) `-. ( ).`-._.`) KDE Developer (MFCH) (_Y_.)' ._ ) `._`. " -.-' http://lateral.netmanagers.com.ar _..`-'_..-_/ /-'_.' The 6,855th most popular site of Slovenia (l)-'' ((i).' ((!.' according to alexa.com (27/5/2007) Debugging is twice as hard as writing the code in the first place. Therefore, if you write the code as cleverly as possible, you are, by definition, not smart enough to debug it. --Brian W. Kernighan |
From: Guenter M. <mi...@us...> - 2008-10-21 15:05:10
|
Red Wraith <red...@gm...> schrieb: >| David Goodger wrote: >| > I think line blocks will suit your purpose: >| I know about the line-block feature but I think it is > rather uncomfortable for writing documents which often > use line breaks. So this is not the right choice in this case. Try the next reST construct... >| Imagine you're writing, for example, a novel where you > almost always use line breaks instead of normal > paragraphs. Or, maybe you mark a new paragraph by indenting the first line instead of a vertical space like its usual in books... > Only when you're changing the point of view > (or similar), you want to have a blank line. Better call it a separating space. A "blank line" is a typewriter (and text editor) metaphor. What you want here, is a "transition". Rst provides a transition element, you only need to style it accordingly, so that it produces a vertical space (with "nothing") instead of a horizontal line. > I realized, that the second example of my last mail was a > bad example. For such _rare_ and short applications the > line-block feature works and is okay: Maybe that is why David proposed it... Günter |
From: David G. <go...@py...> - 2008-10-21 19:53:12
|
> David Goodger wrote: >> If there are real-world examples of the kind of documents you're >> talking about, please provide evidence (e.g. URLs). On Tue, Oct 21, 2008 at 15:13, Red Wraith <red...@gm...> wrote: > I looked into my bookshelf and found some books which were written in > the style I mentioned. I have to admit that I thought more authors used > this style but still there are some. Please provide references (authors & titles). > I searched for some free ebooks which use that style. They are written > in German but that shouldn't matter because the text itself is not > important. Note, that I randomly selected these books. I've never read > any of those. > Here are the links: > > http://i-bux.com/support-files/jamesundlilly.pdf > http://neue_atheisten.ja-nee.de/terryrotter.pdf > http://www.talon-abenteuer.de/data/talon010/talon010.htm The second (terryrotter.pdf) was not available. The other two just look like examples of poor layout to me. Does this style have a name? References to The Chicago Manual of Style or similar would help. If this is actually a common style, it has to be documented somewhere. I've never seen it before, other than as an example of poor formatting. There are two common ways to format paragraphs: 1. Indent the first line, and no vertical whitespace between paragraphs. This is common in newspapers, magazines, and novels. 2. No indentation on the first line, but one blank line between paragraphs. This is common in business correspondence, reports, and on the web. I don't know the names of these formatting styles off-hand; my copy of CMoS is not with me. > The suggestions of Roberto Alsina and Stefan Rank wouldn't require > indenting. The idea of Roberto Alsina would also be very easy to use > (only one symbol needed to write). Günter Milde's analysis and suggestion to use transitions seems most appropriate to me. > However, I'm afraid, one would have > to heavily modify the style files with either suggestion. It's much easier to customize stylesheet files than the Docutils core code. It's something that you can do yourself, without having to convince anyone of the merits of your style. > > Why would one *want* to do either of these? > > Just for aesthetics. Of course, beauty always is in the eye of the beholder. Beauty (or aesthetics) is exactly what stylesheets are for. -- David Goodger <http://python.net/~goodger> |
From: Red W. <red...@gm...> - 2008-10-25 22:44:01
|
David Goodger wrote: > Please provide references (authors & titles). I looked at my family's house for a few books which use those empty lines I talked about. I realized that they all use indents after line breaks (or after paragraphs if you define paragraphs in the same way as HTML does). However, they all use empty lines. I think I have a book somewhere which doesn't use indents but still uses empty lines but I don't remember which book this was. Probably this was a rare "style exception" anyway, I have to admit. Here are the authors and titles of those books: Books in English language: Dan Abnett: The Saint Dan Abnett: Honour Guard Dan Abnett: Eisenhorn You can see the style of the last book on page 20 at the following site: http://www.amazon.com/gp/reader/1844161560/ref=sib_dp_pt#reader-link Books in German language: Tad Williams: Otherland - Stadt der goldenen Schatten Wolfgang Hohlbein: Der Magier - Das Tor ins Nichts Wolfgang und Heike Hohlbein: Elfentanz Wolfgang und Heike Hohlbein: Märchenmonds Erben Mel Odom: Auf Beutezug Stephen Kenson: Ragnarok Tobias Hamelmann & Christian Lonsing : Shadowrun - Die 6. Welt It would be very nice if reStructuredText featured an extra standard element for empty lines. Or maybe different *standard* types of transitions (simple empty line, horizontal dash, etc.), so one can use empty lines and everybody which converts the RST source file sees empty lines by default and not horizontal dashs for example. At the moment, if you use "-----------" one can't specify a type. A "-----------" becomes a <hr> in HTML and you can't modify it with a CSS file to be shown as an empty line (as far as I know). |
From: Guenter M. <mi...@us...> - 2008-11-26 10:05:04
|
David Goodger <go...@py...> schrieb: > On Tue, Nov 25, 2008 at 09:57, Guenter Milde <mi...@us...> wrote: >> Idea: >> b) concatenate --stylesheet and --stylesheet-path arguments (after path >> expansion) > +0. That's tricky, especially since it would break backward > compatibility (new behavior different from the old). What to do about > the defaults? I agree. It would make replacing the default difficult. >> c) provide a stylesheet_search_path setting (especially useful for >> embedded style sheets) which can contain multiple paths (like PATH) > -0. Seems like more trouble than it's worth. So let me explain in more detail what I want to achieve: Motivation ---------- Allow easy combination of a set of prepared style sheets to customise the layout of Docutils-generated documents. For the user, choosing e.g. a different layout for transitions should be as easy as rst2html --stylesheet=html4css1,starred-transitions or [html4css1 writer] stylesheet-path: <path-to-dir>/html4css1.css, <path-to-dir>/starred-transitions.css (the same method could be used to select syntax highlighting schemes for the upcoming code-block directive). Use cases --------- a) preparing documents for a site common style sheets, typically in the root dir¹ or a styles/ subdir:: --stylesheet=/a.css,/b.css --link-stylesheet ¹) note: generally http::host/ != file:/ b) preparing self-containing documents Embed style sheets (from different locations): --embed-stylesheet Typical locations for the style sheets are #. Docutils core folder (docutils/docutils/writers/<writer>), #. Docutils sandbox (docutils/sandbox/stylesheets/), #. [Optional] a local and per-user style repository, #. the pwd of the rst2*.py command, #. the input and/or output directory of the document. Boundary conditions ------------------- The existence of the style-sheet can not be checked with --link-stylesheet, as the path might differ due to movement of the generated doc (e.g. upload to a site) and http: vs file: access. -> Keep path as-is, do not search. With --embed-stylesheet, the style file must be found by Docutils. Searching along a set of directories is a common method in this cases and makes for a friendly user interface. Proposals --------- For simple, backwards-compatible, and a user-friendly interface: 1. Multiple style sheets can be given as comma-separated list. 2. Search to-be-embedded style sheet files in "typical" locations instead of "file not found" error. + Only for --stylesheet or also for --stylesheet-path ? + Make the "typical locations" a config setting? How to call this as "stylesheet-path" is already taken? 3. Append ".css" default extension to embedded style sheets if there is no extension and it is not found. 4. Whichever --stylesheet or --stylesheet-path comes last overwrites earlier occurrences (as well as definitions in the config files). 5. Apply --embed-stylesheet vs. --link-stylesheet to all style sheets. Mixing embedded and linked style sheets is possible "the classical way" --stylesheet=c.css --embed-stylesheet with c.css importing /a.css and /b.css. Implementation -------------- Not all of these points need to be implemented in one step. Some are already implemented (no wonder, as we want to be backwards compatible). >> Actually, the sandbox project already exists: ... >> (Please update the web site.) > Done. Thanks. So interested parties can get a "starred" transition with the CSS style sheet from http://docutils.sourceforge.net/sandbox/README.html Günter |
From: Red W. <red...@gm...> - 2008-11-26 20:56:08
|
I just want to state that I really like the idea of being able to specify several style files and having a collection of default style files shipped with docutils (like the "star-transitions" file). I also think the "stylesheet_search_path" Günter Milde suggested is good idea. Some reasons why I like the idea: 1. I can choose the styles I want to use from a collection and combine them without having to modify any style file. 2. Not having to always specify the paths to the style files because of the automatic search is very comfortable and intuitive. 3. If I use only default style files, I can tell someone else which parameters to set to get the same output without having to send him any style file. Altogether, this is MUCH better than my suggestion of adding new parameters for certain styles (like transition styles). |
From: Guenter M. <mi...@us...> - 2008-10-22 14:30:02
|
David Goodger <go...@py...> schrieb: >> David Goodger wrote: >>> If there are real-world examples of the kind of documents you're >>> talking about, please provide evidence (e.g. URLs). >> I searched for some free ebooks which use that style. They are written >> in German but that shouldn't matter because the text itself is not >> important. Note, that I randomly selected these books. I've never read >> any of those. >> Here are the links: >> http://i-bux.com/support-files/jamesundlilly.pdf >> http://neue_atheisten.ja-nee.de/terryrotter.pdf >> http://www.talon-abenteuer.de/data/talon010/talon010.htm > The second (terryrotter.pdf) was not available. The other two just > look like examples of poor layout to me. IMO, the second is also poor layout (too large vertical space between paragraphs (in a novel, first-line indention is even better), simple line-breaks in the dialogues) Maybe, line-block syntax for dialogues is not too bad but I would first look at some *nice* books to see how a good layout of such things should be done. The third is near to what I suggested: No vertical space between paragraphs, relatively large vertical space for a transition. Only the indention of the first line of a new paragraph is missing. Günter |
From: <tre...@gm...> - 2008-10-22 23:46:08
|
Guenter Milde <mi...@us...> writes: > The third is near to what I suggested: No vertical space between > paragraphs, relatively large vertical space for a transition. Only the > indention of the first line of a new paragraph is missing. Unfortunately doing that in HTML/CSS is not straightforward -- while you can indent the first line of all paragraph elements, what you *actually* want is to indent the first line of *most* paragraph elements. The first paragraph following a heading, for example, generally has no first-line indent. You could conceivably use CSS2's ability to match the first child, but because in XHTML (unlike Docbook), you don't have a surrounding <SECTION> but rather simply insert <Hn> into the stream, you actually end up having to either 1) match P where its immediate elder sibling is a heading; or 2) teach the writer to add extra DIVs. This is the point where I said "fuck it, I hate web browsers anyway. I'll use PDF and leave the CSS at its default setting." |
From: Guenter M. <mi...@us...> - 2008-10-23 09:06:40
|
Trent W. Buck <tre...@gm...> schrieb: > Guenter Milde <mi...@us...> writes: >> The third is near to what I suggested: No vertical space between >> paragraphs, relatively large vertical space for a transition. Only the >> indention of the first line of a new paragraph is missing. > Unfortunately doing that in HTML/CSS is not straightforward -- while you > can indent the first line of all paragraph elements, what you *actually* > want is to indent the first line of *most* paragraph elements. True. You will have to define exception rules as well. > The first paragraph following a heading, for example, generally has no > first-line indent. This depends on the layout preferences. Some people (excluding me) prefer it even there (hence the "indentfirst" LaTeX package). Paragraphs following a list are another example. > You could conceivably use CSS2's ability to match the first child, but > because in XHTML (unlike Docbook), you don't have a surrounding ><SECTION> but rather simply insert <Hn> into the stream, you actually > end up having to either 1) match P where its immediate elder sibling is > a heading; or 2) teach the writer to add extra DIVs. 1) is IMO the beter solution. > This is the point where I said "fuck it, I hate web browsers anyway. > I'll use PDF and leave the CSS at its default setting." a) there is a reason for this default setting: On-screen reading is harder because of lower resolution, so clearly separating paragraphs by vertical space is the preferred option. b) as we are not the first people to think about this, there are certainly many CSS implementations of a "parindent" style available on the net. Providing such a style sheet with docutils might be an option (e.g. for print-from HTML). c) Using PDF is the best alternative if you intend to print the material (or expect the readers to print it out). The rst2latex2e writer will by default use the "parindent" style. Also with PDF, I would propose to style the transition element as empty vertical space. Günter |
From: <tre...@gm...> - 2008-10-23 10:12:12
|
Guenter Milde <mi...@us...> writes: > b) as we are not the first people to think about this, there are > certainly many CSS implementations of a "parindent" style available on > the net. Providing such a style sheet with docutils might be an option > (e.g. for print-from HTML). I don't much care about (b), because of (c). > c) Using PDF is the best alternative if you intend to print the material > (or expect the readers to print it out). [...] |
From: Guenter M. <mi...@us...> - 2008-11-02 23:47:33
|
Red Wraith <red...@gm...> schrieb: > David Goodger wrote: > It would be very nice if reStructuredText featured an extra standard > element for empty lines. Do you really need both, standard transitions and "empty lines"? (Are these mixed in any of the examples?) > Or maybe different *standard* types of transitions (simple empty line, > horizontal dash, etc.), so one can use empty lines and everybody which > converts the RST source file sees empty lines by default and not > horizontal dashs for example. The style of a transition is a layout feature, so it is not coded in the rst source but the style sheet. As you cannot specify the style sheet in the source, someone translating it with the default settings will see the default transition. You can, however, configure docutils in a way that all transitions will by default be styled as vertical space (do not call it empty lines -- the browser is not a typewriter) with a custom style-sheet specified in ~/.docutils. > At the moment, if you use "-----------" one can't specify a type. You can:: Hallo Welt .. class:: vspace ------ but this is only needed if you indeed plan to use both, standard and vspace transition in one document. > A "-----------" becomes a <hr> in HTML and you can't modify it with a > CSS file to be shown as an empty line (as far as I know). You can make the <hr> invisible with CSS2. However, you cannot (currently) style a transition in LaTeX, as the latex2e writer writes:: \hspace*{\fill}\hrulefill\hspace*{\fill} Günter |
From: Red W. <red...@gm...> - 2008-11-24 19:32:41
|
Sorry that I haven't answered earlier. Guenter Milde wrote: > Do you really need both, standard transitions and "empty lines"? > (Are these mixed in any of the examples?) I've thought about it: I actually don't need both types of transitions in the same file. I'm realizing that I don't need a way to "connect paragraphs", either (that was my initial idea). What I would really like to have was an easy way to style transitions (especially to display them as vertical space). The book examples I provided each do use only *one* style of transition as far as I remember. Some other books (e.g. some of the novels I have) show transitions as vertical space plus some dingbats (like stars). But only very seldom horizontal lines are used (as far as it concerns the books I have). Thus, probably, also many other people beside of me would be happy about an easy way to set a different transition style. Maybe a parameter of rst2html.py (and maybe later also of other output scripts) could set the style of the transitions of the document? There are already some parameters which change the output style, e.g. "--compact-field-lists". A new parameter could be called "--transition-style=". "--transition-style=line" would be the default and one could set "--transition-style=vspace" (or similar) for vertical space. If someone else would like to convert your RST file you could tell him which parameter to use to get the same output. Other "transition-styles" which some authors like to use maybe could be added later. Perhaps, someone else also comes up with an idea how the style of the transitions could be set easily. Guenter Milde wrote: > However, you cannot (currently) style a transition in LaTeX, as the > latex2e writer writes:: > > \hspace*{\fill}\hrulefill\hspace*{\fill} That's one of the reasons why I came up with the idea of suggesting a parameter. A RST transition could be converted to something different than a standard LaTeX transition *before* LaTeX styles apply. However, I don't know much about the conversion process (including LaTeX styling) and therefore don't know if this is practical (and if it works this way at all). Maybe one can't style transitions in LaTeX because latex2e has an own definition of "transition", namely a horizontal line, and LaTeX has commands like "\vspace" for different things. |
From: Guenter M. <mi...@us...> - 2008-12-03 11:05:36
|
David Goodger <go...@py...> schrieb: > On Fri, Nov 28, 2008 at 09:56, Guenter Milde <mi...@us...> wrote: > Adding search-path processing is an example of YAGNI (you ain't gonna > need it), IMO. While, You AGNI, I will need it. Finding out that ``html4css1.css`` stands for ``/home/milde/Code/Python/docutils-svn/docutils/docutils/writers/html4css1/html4css1.css`` is a task I would prefer the computer to do for me. (And I am going to need this, e.g., for the html4strict writer.) (For you, it might be easier to change the defaults to meet your needs, the average user does not have this possibility.) >> The implementation would be somewhat simpler, if >> utils.get_stylesheet_reference returned a list. However, joining it to >> a string keeps backwards compatibility (in case other writers use this >> util fun). > Why not add a new function, "docutils.utils.get_stylesheet_references", > which has that API? Then replace the usage where appropriate. This > will avoid incompatibilities. We could mark the original deprecated, or > even remove it, but there's no harm in leaving it in. There may be > 3rd-party code that relies on the old behavior. Because this would be more complicated than returning ``",".join(sheets)`` and using ``stylesheets.split(",")`` in the writer. > Actually, the best thing might be to add a validator function to > docutils.frontend (like "validate_comma_separated_string_list"), and > define the options in terms of a list ('action': 'append'). What would we gain from this? Is this the way to get [foo, bar] from --opt=foo --opt=bar ? Then we will not need it, as a subsequent arg should replace the first one. >> David, could you have a look and tell me whether it is OK to commit? > The option help needs a syntax explanation ("comma-separated"). And > the docs will need updating. That can be done after though. The patch for get_stylesheet_reference uses a list comprehension: + sheets = [relative_path(relative_to, sheet) + for sheet in settings.stylesheet_path.split(",")] which is certainly not compatible with python 2.2. Should I use a "for" loop instead? Günter |
From: David G. <go...@py...> - 2008-12-03 14:38:24
|
On Wed, Dec 3, 2008 at 06:05, Guenter Milde <mi...@us...> wrote: > David Goodger <go...@py...> schrieb: >> On Fri, Nov 28, 2008 at 09:56, Guenter Milde <mi...@us...> wrote: > >> Adding search-path processing is an example of YAGNI (you ain't gonna >> need it), IMO. > > While, You AGNI, I will need it. > > Finding out that ``html4css1.css`` stands for > ``/home/milde/Code/Python/docutils-svn/docutils/docutils/writers/html4css1/html4css1.css`` > is a task I would prefer the computer to do for me. > (And I am going to need this, e.g., for the html4strict writer.) > > (For you, it might be easier to change the defaults to meet your needs, > the average user does not have this possibility.) I still call YAGNI. It's feature bloat, not needed, and difficult to implement correctly. I'm not saying don't implement it, just warning you that you're asking for trouble. >>> The implementation would be somewhat simpler, if >>> utils.get_stylesheet_reference returned a list. However, joining it to >>> a string keeps backwards compatibility (in case other writers use this >>> util fun). > >> Why not add a new function, "docutils.utils.get_stylesheet_references", >> which has that API? Then replace the usage where appropriate. This >> will avoid incompatibilities. We could mark the original deprecated, or >> even remove it, but there's no harm in leaving it in. There may be >> 3rd-party code that relies on the old behavior. > > Because this would be more complicated than returning > ``",".join(sheets)`` and using ``stylesheets.split(",")`` in the > writer. No, it would be simpler. It doesn't risk breaking any code. Do you know every existing use of docutils.utils.get_stylesheet_reference? >> Actually, the best thing might be to add a validator function to >> docutils.frontend (like "validate_comma_separated_string_list"), and >> define the options in terms of a list ('action': 'append'). > > What would we gain from this? It keeps the processing of option syntax in one place, docutils.frontend. > Is this the way to get > [foo, bar] > from > --opt=foo --opt=bar > ? Then we will not need it, as a subsequent arg should replace the > first one. OK, please document that behavior. > The patch for get_stylesheet_reference uses a list comprehension: > > + sheets = [relative_path(relative_to, sheet) > + for sheet in settings.stylesheet_path.split(",")] > > which is certainly not compatible with python 2.2. Should I use a "for" > loop instead? No. List comprehensions were added to Python 2.0. -- David Goodger <http://python.net/~goodger> |
From: Guenter M. <mi...@us...> - 2008-11-24 23:40:36
|
On 2008-11-24, Red Wraith wrote: > Guenter Milde wrote: >> Do you really need both, standard transitions and "empty lines"? > ... What I would really like to have was an easy way to style > transitions (especially to display them as vertical space). ... > Maybe a parameter of rst2html.py (and maybe later also of other output > scripts) could set the style of the transitions of the document? IMO, styling via CSS is the way to go. Especially as most styles with vertical space for a transition also use indentation to mark paragraphs. This would become easier, if a) specification (and embedding) of several stylesheets were possible (specifying several stylesheets is possible in LaTeX already) b) docutils included a collection of pre-defined style sheets (e.g. in the sandbox), so that users without CSS knowledge can customize the layout by combining them. > There are already some parameters which change the output style, e.g. > "--compact-field-lists". Yes, but these should stay the exception used in cases where styling via CSS is impossible. So, instead of > "--transition-style" --stylesheet=html4css1.css,space-transition.css could be used without any need to change the html writer. > Other "transition-styles" which some authors like to use maybe could be > added later. You see the advantage here: adding style sheets can be done by everyone. > > However, you cannot (currently) style a transition in LaTeX, as the > > latex2e writer writes:: > > > > \hspace*{\fill}\hrulefill\hspace*{\fill} > That's one of the reasons why I came up with the idea of suggesting a > parameter. But also here, the right way is to use a stylable macro, e.g. \providecommand{\DUtransition}{\hspace*{\fill}\hrulefill\hspace*{\fill}} which could be given another definition in a LaTeX style. > Maybe one can't style transitions in LaTeX because latex2e has an own > definition of "transition", namely a horizontal line, and LaTeX has > commands like "\vspace" for different things. No. It's just because no one requested stylable transitions in LaTeX so far. Günter |
From: David G. <go...@py...> - 2008-11-25 01:07:28
|
On Mon, Nov 24, 2008 at 18:40, Guenter Milde <mi...@us...> wrote: > On 2008-11-24, Red Wraith wrote: >> ... What I would really like to have was an easy way to style >> transitions (especially to display them as vertical space). We already have that; it's called "stylesheets". >> Maybe a parameter of rst2html.py (and maybe later also of other output >> scripts) could set the style of the transitions of the document? We are not going to add a parameter, sorry. > IMO, styling via CSS is the way to go. Especially as most styles with > vertical space for a transition also use indentation to mark paragraphs. +1 > This would become easier, if > > a) specification (and embedding) of several stylesheets were possible > (specifying several stylesheets is possible in LaTeX already) -1. The C in CSS stands for "cascading". You can chain stylesheets together, so there is no need for to be able to specify multiple stylesheets. Instructions here: http://docutils.sourceforge.net/docs/howto/html-stylesheets.html > b) docutils included a collection of pre-defined style sheets (e.g. in > the sandbox), so that users without CSS knowledge can customize the > layout by combining them. Sure, please go ahead. -- David Goodger <http://python.net/~goodger> |
From: Guenter M. <mi...@us...> - 2008-12-03 15:09:55
|
David Goodger <go...@py...> schrieb: > On Wed, Dec 3, 2008 at 06:05, Guenter Milde <mi...@us...> wrote: >> David Goodger <go...@py...> schrieb: >>> On Fri, Nov 28, 2008 at 09:56, Guenter Milde <mi...@us...> wrote: >>> Why not add a new function, "docutils.utils.get_stylesheet_references", >>> which has that API? Because "docutils.utils.get_stylesheet_references" could very easily be confused with "docutils.utils.get_stylesheet_reference" producing hard to spot bugs. >>> Then replace the usage where appropriate. This will avoid >>> incompatibilities. We could mark the original deprecated, or even >>> remove it, but there's no harm in leaving it in. There may be >>> 3rd-party code that relies on the old behavior. >> Because this would be more complicated than returning >> ``",".join(sheets)`` and using ``stylesheets.split(",")`` in the >> writer. > No, it would be simpler. It doesn't risk breaking any code. Do you > know every existing use of docutils.utils.get_stylesheet_reference? Of course not. An estimation is grepping in the Docutils SVN working copy: grep -nH -r --include='*.py' get_stylesheet_references docutils-svn However, I know the behaviour of utils.get_stylesheet_reference before and after the change: * if there is no comma in the stylesheet argument, nothing is changed. * if there is a comma in the stylesheet argument and settings.stylesheet_path == TRUE, the path expansion is done for every part of the comma separated list and it is joined again. For the latex writer, this results in fixing a non-reported bug. But if you prefer, I can define and use utils.get_stylesheet_reference_list(). >>> Actually, the best thing might be to add a validator function to >>> docutils.frontend (like "validate_comma_separated_string_list"), and >>> define the options in terms of a list ('action': 'append'). >> What would we gain from this? > It keeps the processing of option syntax in one place, docutils.frontend. >> ... a subsequent arg should replace the first one. > OK, please document that behavior. This is not new at all:: rst2html --link-stylesheet --stylesheet=foo --stylesheet=bar example.txt produces <link rel="stylesheet" href="bar" type="text/css" /> >> The patch for get_stylesheet_reference uses a list comprehension: ... >> Should I use a "for" loop instead? > No. List comprehensions were added to Python 2.0. Fine. Günter |