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/ |