[Doc-SIG] Some random thoughts

[Edward Welbourne]

>>> * 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
duration).

> 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, ...

      Arguments:

          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 ]

      Tailpiece:
          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.

	Eddy.