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