From: Edward L. <ed...@gr...> - 2004-04-21 15:08:30
|
[Edward Loper] >> - If we replace the "::" in directives with ":", then "comment" >> can be trivially implemented as a directive. I.e., it's no >> longer a special construct to learn, but just another instance >> of a general pattern. [David Goodger] > I don't see that changing "::" to ":" is a prerequisite for a > "comment" directive. They're two unrelated issues. They're two *different* issues but not two *unrelated* issues. In particular, explicilty marking comments removes one of the two justifications for using "::": [David Goodger] > - To avoid clashes with common comment text like:: > .. Danger: modify at your own risk! And I don't find the second justification very compelling: [David Goodger] > - If an implementation of reStructuredText does not recognize a > directive (i.e., the directive-handler is not installed), a > level-3 (error) system message is generated, and the entire > directive block (including the directive itself) will be > included as a literal block. Thus "::" is a natural choice. [Edward Loper] >> Nevertheless, I'm +1 for eliminating the specialized comment syntax >> and replacing it with a directive. And if we do replace comment >> with a directive, then I'm also +1 for replacing the "::" in >> directives with ":". [David Goodger] > That would cause a lot of breakage. I'm not sure the benefit is worth > the cost. What to do with all the existing ".. legacy comments"? > [...] > I'm not convinced this is an issue worth spending effort on. I'll spend a bit more effort on it before I give up. :) Here's a proposal for dealing with backwards compatibility: 1. ".. foo" will generate a deprication warning to stderr, and nothing in the output (no info/error node) 2. ".. foo: bar" will be treated as a directive foo. If there is no foo directive, then do the normal error output. 3. ".. foo:: bar" will generate a deprication warning to stderr, and be treated as a directive. So some existing documents might start printing deprication warnings, but the only existing documents that would *break* would be ones that say something like: .. warning: this should be a comment instead of: .. warning:: this should be a comment Here, we're trading fairly common a silent error (directive falsely treated as a comment) for a fairly uncommon explicitly flagged error (comment falsely treated as directive). To make things even easier, we could add a sentence to the unknown-directive error. Something like "If you intended to create a comment, please use ".. comment:" instead. At some point in the future, we could turn the deprication warnings into real errors; or we could just always keep them as deprication warnings. -Edward |