[Doc-SIG] What's important in a docstring markup language?
Edward D. Loper
edloper@gradient.cis.upenn.edu
Wed, 28 Mar 2001 10:55:35 EST
So, I was thinking about how to make ST more formal, more like a real
markup language, and possibly more lightweight.. And that led me to
think about what I *really* want in a markup language for docstrings..
The following is an ordered list of the features I think it should
have. I.e., I think features earlier on the list are more important,
and ones later are less important. I would personally be happy
to draw a line anywhere after 4, and forget about anything under
the line. :)
1. The ability to distinguish text that can be rendered with soft
spaces and word wrapped from text that should be rendered in
monospace with whitespace preserved (i.e., the ability to
distinguish natural language from everything else). This includes
both inline literals and literal blocks
2. The ability to label the semantic content of parts of descriptions,
eg., as the return value or as a description of an argument.
3. The ability to properly handle doctest blocks (this is a high
priority, because these have become standard)
4. Unordered lists
5. Ordered lists
6. Sections
7. Hierarchical sections
8. The ability to mark a word as emphasized
9. URLs
10. The ability to mark regions as emphasized
11. The ability to mark regions as strong
12. Footnotes/endnotes
13. Internal anchors/references to parts of a docstring
Does this correspond more-or-less with other people's priorities?
What markup do people feel is essential for documenting the APIs of
python objects?
-Edward