From: Mark M. <ma...@mc...> - 2002-09-13 20:49:57
|
The documentation says: "An underline/overline must be at least 4 characters long (to avoid mistaking ellipses ["..."] for overlines). When an overline is used, the length and character used must match the underline." http://docutils.sourceforge.net/spec/rst/reStructuredText.html#sections However, when I use this: My section is longer than the underline ==== (left-aligned in actual source, indented for readability) I get this: System Message: WARNING/2 (user_task_matrix.rst, line 4) Title underline too short. Is that a bug? Why make users type all those extra underline characters and then have to keep adjusting them as the section title changes? Cheers, // m - |
From: David G. <go...@us...> - 2002-09-15 14:30:07
|
Mark McEahern wrote: > The documentation says: > > "An underline/overline must be at least 4 characters long (to avoid > mistaking ellipses ["..."] for overlines). When an overline is used, the > length and character used must match the underline." You omitted this sentence: An underline/overline is a single repeated punctuation character that begins in column 1 and forms a line extending at least as far as the right edge of the title text. The "at least as far" is significant. > http://docutils.sourceforge.net/spec/rst/reStructuredText.html#sections > > However, when I use this: > > My section is longer than the underline > ==== > > (left-aligned in actual source, indented for readability) > > I get this: > > System Message: WARNING/2 (user_task_matrix.rst, line 4) > > Title underline too short. > > Is that a bug? No, it's a diagnostic message, warning you that the markup is questionable. The parser assumes that a section title is intended, but the inserted warning is such an eyesore that you're sure to fix the underline. > Why make users type all those extra underline characters and > then have to keep adjusting them as the section title changes? Because anything *less* than a full underline looks wrong. There's no reason to limit your underlines to the exact length of the title though (thus "at least as far" above). You're welcome to use 80 column underlines for all titles, no matter how long. In reStructuredText, section titles are underlined. Only full underlines get full marks. Are you seriously proposing some other behavior? If so, please be explicit. Coincidentally, currently there is a proposal to remove the 4-character minimum on over- & underlines, for short titles. It and other proposed changes & additions to the markup are discussed on the Doc-SIG list: http://mail.python.org/mailman/listinfo/doc-sig Docutils implementation issues are discussed on the docutils-develop list: http://lists.sourceforge.net/lists/listinfo/docutils-develop Interested parties should subscribe to both since there is some overlap. -- David Goodger <go...@us...> Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) - The Go Tools Project: http://gotools.sourceforge.net/ |
From: Mark M. <mar...@mc...> - 2002-09-15 22:33:23
|
[David Goodger] > You omitted this sentence: > > An underline/overline is a single repeated punctuation character > that begins in column 1 and forms a line extending at least as far > as the right edge of the title text. > > The "at least as far" is significant. My apologies. I missed that sentence. So the behavior is by design, I see. > Because anything *less* than a full underline looks wrong. I agree, it does look unfinished. However, I keep thinking about all the useless work involved in this scenario: 1. Type "The Political Landscape" 2. Type "-----------------------" 3. Change the title to "The Political Landscape of the US" 4. Add underscores to the underline to match the new section title. 5. Change the title to "Politics in the US" 6. etc. Why should I have to keep adjusting the length of the line? I know you pointed out that I can just type 80 of the underline characters (or 79 or whatever) and leave that alone--as long as it's longer than the title. I'm reminded of Scott McConnell's comments on Commenting Efficiently in Code Complete (pp 464-367): He writes of this: ########### # globals # ########### "Use styles that don't break down or discourage modification." Perhaps I'm making mountains out of molehills, though? > In reStructuredText, section titles are underlined. Only full > underlines get full marks. Are you seriously proposing some other > behavior? If so, please be explicit. As it is, the current dev snapshot seems to intuit that I want an underline in this case: The Political Landscape of the US ---- The only thing I guess I'm asking is, "Can we at least make the error suppressible?" And, it turns out, we can: -r3 does the trick just fine. I really like reStructuredText. Thank you for developing it! Cheers, // mark - |
From: David G. <go...@us...> - 2002-09-16 00:57:27
|
Mark McEahern wrote: >> Because anything *less* than a full underline looks wrong. > > I agree, it does look unfinished. However, I keep thinking about all the > useless work involved in this scenario: > > 1. Type "The Political Landscape" > 2. Type "-----------------------" > 3. Change the title to "The Political Landscape of the US" > 4. Add underscores to the underline to match the new section title. > 5. Change the title to "Politics in the US" > 6. etc. > > Why should I have to keep adjusting the length of the line? Is it really such a hardship? Is it not something you would do anyhow, in a text file? The core of reStructuredText is merely a formalization of common long-standing conventions for plaintext documents. I didn't invent this particular convention, just chose and codified it (and wrote the code to parse it). The plaintext medium simply has limitations that we have to live with. I don't know of a better way. If there is one, I'm receptive. Nothing I've seen so far comes close though. Perhaps someday someone will write a reStructuredText mode for Emacs, which will automatically take care of such mundane issues. That would be great! Won't be me though; I can hack Emacs Lisp but not well enough to write a major mode. > I know you pointed out that I can just type 80 of the underline characters > (or 79 or whatever) and leave that alone--as long as it's longer than the > title. If it bugs you, this solution seems reasonable. > I'm reminded of Scott McConnell's comments on Commenting Efficiently in Code > Complete (pp 464-367): > > He writes of this: > > ########### > # globals # > ########### > > "Use styles that don't break down or discourage modification." Good advice. Whenever I've done something like that in a source file, I would write it like this:: ##################################################################### # Globals ##################################################################### Easy to edit. :-) > Perhaps I'm making mountains out of molehills, though? *I* think so, yes. ;-) >> In reStructuredText, section titles are underlined. Only full >> underlines get full marks. Are you seriously proposing some other >> behavior? If so, please be explicit. > > As it is, the current dev snapshot seems to intuit that I want an underline > in this case: > > The Political Landscape of the US > ---- The parser knows enough to assume you want an underline, but then it makes it very clear what the error is and where. I'd say that it's the assumption that's closer to being a "bug" than the error message. > The only thing I guess I'm asking is, "Can we at least make the error > suppressible?" And, it turns out, we can: -r3 does the trick just fine. -r3 does indeed suppress that error. Unfortunately, it also suppresses all other errors, and all warnings as well. Dangerous and not recommended. If you use -r3, you'll regret it in the long run. The error is meant as diagnostic feedback to the user, and isn't meant to be ignored. That's what the ERROR/3 level means: "a major issue that should be addressed. If ignored, the output will contain unpredictable errors." See http://www.python.org/peps/pep-0258.html#error-handling for details. I'm not inclined to remove the generated error. Asking if the error can be suppressed is approaching the issue from the wrong direction. If pressed, I'd rather remove the leniency: leave just the error and omit the section & title recognition. > I really like reStructuredText. Thank you for developing it! You're most welcome. -- David Goodger <go...@us...> Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) - The Go Tools Project: http://gotools.sourceforge.net/ |
From: Mark M. <mar...@mc...> - 2002-09-16 01:42:06
|
[David Goodger] > Is it really such a hardship? Is it not something you would do > anyhow, in a text file? Nope, it's not that much of a hardship. > I don't know of a better way. If there is one, I'm receptive. > Nothing I've seen so far comes close though. I never mastered the old StructuredText, but its approach, using merely indentation and whether text was a single line or more than one line (was that is?) to indicate H1 vs. H2 for instance seemed too fuzzy for my taste. So, in contrast, I like the precision of reStructuredText. Thanks for the warning about suppressing errors. Cheers, // mark - |