[Doc-SIG] Some random thoughts

Edward Welbourne Edward Welbourne <eddyw@lsl.co.uk>
Mon, 6 Mar 2000 13:46:32 +0000

>>> * Forcing anything between ' ' into <Code> seems particularly clumsy; *
>> Agreed.  This has been discussed here before.
> Do we have any suggestions for an alternative?

Yes, but no take-up on it: use #blah# for <code>blah</code>
The only objection (I've heard) to this is that it looks ugly, but then
so do monospaced fonts and that's what it's asking for.

I believe this is conflict-free for inline code blocks (of course, code
paragraphs may want to include comments; but such paragraphs will be
introduced by a tag such as Example or a prefix such as >>> and, being
parsed as paragraphs, can suppress the special meaning of # for the

> My thinking is that perhaps there need to be two "types" of style.

No ! don't do it !  Doc-strings should (and StructuredText provides for
them to) use only minimal mark-up.  If you need to do fancy markup, it
belongs in the accompanying (out-of-line) documentation, *not* in the
doc-strings.  If it can't be said with minimal markup, it doesn't belong
in the doc string ...

> I am currently doing some fence sitting on section headlines

How about a line starting (at the indent of its predecessors) with a
colon ?
  ... """First line

      Introductory paragraph, ...


          blah -- desription

      : First section

          paragraphs indented relative to it

          : sub-section

             With further nesting to arbitrary depth ?
             Discourage depth > 6, of course, for HTML's sake.

          more paragraphs in first section ?  [ would be confusing ]

      : Second section

          and so on

      more paragraphs ?  [ again, would be confusing ]

          All that stuff that got discussed earlier about
          cross-references and so on; XML-style info content using
          indentation instead of nested <tag>...</tag> pairs.

I can't think of any case where that might otherwise appear (but is : a
valid list-item-bullet ?).  Otherwise, in the style of the `keyword:'
setups discussed earlier (and illustrated as Tailpiece), use `Section:'
with the indentation relative to earlier `Section:' lines serving to
decide whether this is a sub-section or a new section at the same level.