Mailman 3 March 2009 - Doc-SIG

(Issue #4711) Wide literals in the table of contents overflow in documentation
by Scott Dial March 10, 2009

March 10, 2009

I posted this bug a few months ago onto the tracker and it didn't garner any attention, perhaps because it is a bit of a nitpick. However, it drives me nuts everytime I see it come up in the python docs, so I bring it up here again in hopes of resolving it. I copy the report here: """ There is a problem with the table contents with respect to literals that cannot be word-wrapped. I see this issue here: http://docs.python.org/dev/2.6/library/multiprocessing.html The line in the table of contents that reads "The multiprocessing.sharedctypes module" is broken in that the literal "multiprocessing.sharedctypes" overflows into the right-hand side. It also ends up underneath the contents on the right, which makes it extra hard to know what that entry was about. This instance may be browser specific, but I think it brings up a more general question of what should be done with such long literals and how overflow should be handled. And perhaps even whether it is wise to have set the width of that div to such a narrow and specific value (230px). """ -- Scott Dial scott(a)scottdial.com scodial(a)cs.indiana.edu

1 0

Ambiguity in default output for publish_string
by Jeffrey C. Jacobs March 4, 2009

March 4, 2009

The two reStructuredText files: -------- This paragraph has a very funny **indent** after that word, right? -------- and: -------- his paragraph has a very funny **indent after that word, right?** -------- are theoretically different. The first puts strong emphasis only on the word **indent**, which is followed by exactly 4 spaces, where as the other puts strong emphasis on the entire expression "indent after that word, right?", where there is a line feed between "indent" and "after". However, when publish_string is called to output the tree for both of these expressions, they both return: <document source="<string>"> <paragraph> This paragraph has a very funny <strong> indent after that word, right? which is not different. As far as I can tell, the internal node structure is correct, it's just when the node structure is displayed in string form, the default function of publish_string. Since this output is a serialization of the node structure, it seems that the output to publish_string should not be ambiguous in terms of what it truly represents. Or, is there a better way to represent the internal doc tree unambiguously as a string?

2 1

Diffing reStructuredText documents that only differ by formatting
by Jeffrey C. Jacobs March 3, 2009

March 3, 2009

I am wondering if there is a way to diff 2 versions of a reStructuredText document that differ only by line breaks within paragraphs such that those differences do not trigger a diff entry. In other words, I wonder if there is a tool out there where: this is one reStructuredText paragraph Is considered equivalent to: this is one reStructuredText paragraph Does anyone have any ideas how this can be accomplished, especially with respect to VCS differences, e.g. svn? Thanks! Jeffrey.

3 4