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