From: Richard D. <rjd...@gm...> - 2010-04-30 18:18:00
|
I've recently switched to sphinx/reST for creating project documentation, and so far I've found that using reST is a breeze. However, there is one bit of formatting I need to do occasionally that's not obviously expressible in reST (not obvious to me, anyway): declare a single-line literal block that starts with a space that must be preserved. The problem with: :: This line should have a space at the beginning (but it's removed) is that the leading space is lost, because there's no way to indicate the initial indentation level. I have discovered that the following cumbersome construct does the job: .. parsed-literal:: :class: nonexistent This line should have a space at the beginning (and it's retained) (note how "This line..." is indented one space more than the ":class:" option) but it *is* cumbersome. Is there a better, cleaner way to do this? -- Richard Dymond |
From: David G. <go...@py...> - 2010-04-30 19:14:54
|
On Fri, Apr 30, 2010 at 14:17, Richard Dymond <rjd...@gm...> wrote: > However, there is one bit of formatting I need to do occasionally > that's not obviously expressible in reST (not obvious to me, anyway): > declare a single-line literal block that starts with a space that must > be preserved. > > The problem with: > > :: > > This line should have a space at the beginning (but it's removed) > > is that the leading space is lost, because there's no way to indicate > the initial indentation level. Right. The initial indentation level is set by the leftmost line of text in the literal block. The reason the leading space is removed is because it's impossible to differentiate between an intentional leading space and a space used for indentation. If there was a second line in the literal block further left, it would set the initial indentation level. If this is a formatting issue, a stylesheet (and maybe a class) should solve it. If not, why do you need a leading space in the literal block? It won't be visible. > Is there a better, cleaner way to do this? You could use a prompt character (like "> literal block here"). Otherwise, I don't think so. This seems to be a corner case that reST syntax can't handle easily. It's really only an accident (some might consider it a bug) that the "parsed-literal" workaround does what you want. -- David Goodger <http://python.net/~goodger> |
From: Richard D. <rjd...@gm...> - 2010-04-30 19:43:25
|
> If this is a formatting issue, a stylesheet (and maybe a class) should solve it. > > If not, why do you need a leading space in the literal block? It won't > be visible. I'm writing documentation about a file format in which the first character of each line must be a space, or a semi-colon, or some other character chosen from a fixed set. Occasionally I need to show an example snippet from such a file where the first character of each line is a space. It's important to preserve the space because that is an essential part of the file format; if anyone copies and pastes the snippet, the space should be there in the copy. > You could use a prompt character (like "> literal block here"). > Otherwise, I don't think so. This seems to be a corner case that reST > syntax can't handle easily. It's really only an accident (some might > consider it a bug) that the "parsed-literal" workaround does what you > want. I see. Well, this is a happy accident for me. The fact that the placing of the ':class:' option serves to specify the initial indentation level seems unobjectionable, perhaps even logical. Here's hoping it's never "fixed". :) -- Richard Dymond |
From: David G. <go...@py...> - 2010-04-30 20:40:28
|
On Fri, Apr 30, 2010 at 15:43, Richard Dymond <rjd...@gm...> wrote: > I'm writing documentation about a file format in which the first > character of each line must be a space, or a semi-colon, or some other > character chosen from a fixed set. Occasionally I need to show an > example snippet from such a file where the first character of each > line is a space. It's important to preserve the space because that is > an essential part of the file format; if anyone copies and pastes the > snippet, the space should be there in the copy. Indicating that whitespace is significant is a solved problem: rather than using an invisible space character, instead use a character like "␢" (Unicode U+02422) or "␣" (U+02423) along with some explanatory text (e.g. "replace '␣' with a space, Unicode U+00020"). If you insist on copy-paste-compatibility, the best reST can do is something like this: """ File format:: e.g.: line one (indented one space relative to the "e.g.") """ (I.e. include some "guarding" text that enables the indentation you need.) >> It's really only an accident (some might >> consider it a bug) that the "parsed-literal" workaround does what you >> want. > > I see. Well, this is a happy accident for me. The fact that the > placing of the ':class:' option serves to specify the initial > indentation level seems unobjectionable, perhaps even logical. Here's > hoping it's never "fixed". :) I would recommend against relying on that arguably buggy behavior. While I don't think anyone would maliciously "fix" it just to spite you, it may get fixed for some unrelated but valid reason at some point. -- David Goodger <http://python.net/~goodger> |
From: thomas <tho...@gm...> - 2010-04-30 20:28:59
|
Instead of a white-space, just put a no-break space (U+00A0). Thomas |
From: David G. <go...@py...> - 2010-04-30 20:41:21
|
On Fri, Apr 30, 2010 at 16:28, thomas <tho...@gm...> wrote: > Instead of a white-space, just put a no-break space (U+00A0). Try it; I don't think it works. Docutils is smarter than that :-) -- David Goodger <http://python.net/~goodger> |
From: Marc 'B. R. <ma...@ri...> - 2010-05-02 10:03:11
|
On Friday 30 April 2010, David Goodger wrote: > On Fri, Apr 30, 2010 at 14:17, Richard Dymond <rjd...@gm...> wrote: > Right. The initial indentation level is set by the leftmost line of > text in the literal block. The reason the leading space is removed is > because it's impossible to differentiate between an intentional > leading space and a space used for indentation. If there was a second > line in the literal block further left, it would set the initial > indentation level. > > If this is a formatting issue, a stylesheet (and maybe a class) > should solve it. > > If not, why do you need a leading space in the literal block? It > won't be visible. I stumbled over this problem too some time ago. I wanted to explain a longer method with code and explaining paragraphs mixed. It looked somewhat like this: ---- Explanation… :: class A: def method(self): with …: for i in …: for j in …: for k in …: More explanations… :: some_code() more_code() That pattern above repeated several times… ---- And when rendered the code blocks where not aligned any more. For the reader the structure of the whole method was not clear anymore from the visual appearance. Maybe that's a sign for a method that is too long if you need multiple "interlaced" paragraphs to explain it. But it was not my code so I wasn't able to just refactor that deeply nested and long piece of code. Ciao, Marc 'BlackJack' Rintsch -- “In Britain, it seems that all the attention in recent years has been on the evils of Mad Cow – with little or no heed paid to the Mad Men! Just because you don't eat the Mad Men is no reason to ignore the serious safety issue here.” -- Michael Moore, “Stupid White Men” |
From: David G. <go...@py...> - 2010-05-02 14:22:13
|
On Sun, May 2, 2010 at 05:51, Marc 'BlackJack Rintsch <ma...@ri...> wrote: > I stumbled over this problem too some time ago. I wanted to explain a > longer method with code and explaining paragraphs mixed. It looked > somewhat like this: > > ---- > > Explanation… :: > > class A: > def method(self): > with …: > for i in …: > for j in …: > for k in …: > > More explanations… :: > > some_code() > more_code() > > That pattern above repeated several times… > > ---- > > And when rendered the code blocks where not aligned any more. Use a marker like "(continued)" or "..." to indicate the initial indentation level: Explanation… :: class A: def method(self): with …: for i in …: for j in …: for k in …: More explanations… :: ... some_code() more_code() -- David Goodger <http://python.net/~goodger> |
From: Marc 'B. R. <ma...@ri...> - 2010-05-02 16:42:33
|
On Sunday 02 May 2010, David Goodger wrote: > Use a marker like "(continued)" or "..." to indicate the initial > indentation level: > > Explanation… :: > > class A: > def method(self): > with …: > for i in …: > for j in …: > for k in …: > > More explanations… :: > > ... > some_code() > more_code() In general a nice idea but in that particular case I used `pylit`, so that marker would be part of the code. Maybe using a comment as marker works somehow. Have to try when I face this problem again. Ciao, Marc 'BlackJack' Rintsch -- “The basic tool for the manipulation of reality is the manipulation of words. If you can control the meaning of words, you can control the people who must use the words.” -- Philip K. Dick, How To Build A Universe That Doesn't Fall Apart Two Days Later |
From: Richard D. <rjd...@gm...> - 2010-05-03 17:30:46
|
On 2 May 2010 13:45, Marc 'BlackJack Rintsch <ma...@ri...> wrote: > On Sunday 02 May 2010, David Goodger wrote: > >> Use a marker like "(continued)" or "..." to indicate the initial >> indentation level: >> >> Explanation… :: >> >> class A: >> def method(self): >> with …: >> for i in …: >> for j in …: >> for k in …: >> >> More explanations… :: >> >> ... >> some_code() >> more_code() > > In general a nice idea but in that particular case I used `pylit`, so > that marker would be part of the code. Maybe using a comment as marker > works somehow. Have to try when I face this problem again. To get an indented literal block I have toyed with creating a new directive: 'indented-literal'. Add the following key-value pair to the _directive_registry in parsers/rst/directives/__init__.py: 'indented-literal': ('body', 'IndentedLiteral') and then add the 'IndentedLiteral' class to parsers/rst/directives/body.py: class IndentedLiteral(Directive): option_spec = {'indent': directives.nonnegative_int} has_content = True def run(self): set_classes(self.options) self.assert_has_content() indent = ' ' * self.options.get('indent', 0) text = '\n'.join(['%s%s' % (indent, line) for line in self.content]) text_nodes = [nodes.Text(text)] node = nodes.literal_block(text, '', *text_nodes, **self.options) node.line = self.content_offset + 1 return [node] When that's done, you can specify an indented literal block thus: .. indented-literal:: :indent: 4 This block of text will be indented by 4 spaces My apologies to the docutils developers if this appears to be a gross hack and violation of coding style; my thanks to them also for a design that makes this hack possible with just a few extra lines of code! -- Richard Dymond |
From: Guenter M. <mi...@us...> - 2010-05-03 07:06:16
|
On 2010-05-02, Marc 'BlackJack Rintsch wrote: > On Sunday 02 May 2010, David Goodger wrote: >> Use a marker like "(continued)" or "..." to indicate the initial >> indentation level: ... > In general a nice idea but in that particular case I used `pylit`, so > that marker would be part of the code. Maybe using a comment as marker > works somehow. It works. You can either attach a comment without blank line, so it is treated as code, or use a different comment string:: More explanations :: # ... some_code() more_code() or, e.g. :: More explanations :: ## ... some_code() more_code() Günter |