On 12/22/05, Phillip J. Eby <[EMAIL PROTECTED]> wrote: > At 04:08 PM 12/22/2005 -0500, Martin Blais wrote: > >ReST does an amazing job of inferring generic document structures from > >text, but for documenting source code, you really want to be able to > >say "This is a function", "this is an optional argument", etc. ReST > >does not provide this kind of functionality, and if you try to stretch > >the interpreted roles to do this you get an equally ugly syntax as > >LaTeX input (I would even argue that I prefer the LaTeX source). > > That sounds like a misuse of the tool to me; if you need structured, > extractable information from a reST document, fields and directives are > probably going to be the way to go. Similarly, I'd suggest that > interpreted roles to identify the context of a name probably isn't the best > way to go about it either; a link to the definition of the referenced item > will be more useful and more uniform. A formatter or intermediate > processor can then decide whether it should actually be rendered as a > hyperlink, a fully-qualified name, or just the function/method/class name. > > So, definitions of functions, classes, and other structured stuff would > just use fields under a directive, and references to those definitions > would just be reST links.
So you end up with a document with a bunch of custom directives, like:: .. python-class:: MyClass :arg: comfobulator :arg optional: bliptor My Class description. This does not look significantly better to me than the LaTeX code, and the docutils directives are not as flexible as the commands provided by tex/latex. > >Also, ReST has many gotchas: if you will infer structures from > >invisible markup, it's very easy to make mistakes, and there are many > >cases where it's not clear what the parsed document will be like, you > >have to "learn" a lot of how it parses the documents, and the corner > >cases, by checking with rst2pseudoxml.py. > > Huh? I've never used rst2pseudoxml.py, so I don't understand how it's a > requirement. Do you mean, if you're writing some kind of reST processor > it's helpful to understand how stuff is parsed? It is if you're relying on specific document structures to provide information about your special constructs. rst2pseudoxml.py just helps you display that parsed structure. For example, you could write some kind of processor on the docutils document tree that looks for definition lists whose "term" starts with "class" and then assumes some other things about what it will find in the body of this definition, e.g. class MyClass <Some indented material about the class MyClass> (this gets parsed as a ReST definition term/body because of the indented line right after the "class MyClass" line). I'm doing this kind of processing, albeit in a limited way, to extract book reviews, bookmarks, and contact info from a body of text files that I maintain, using my nabu system (http://furius.ca/nabu/ come to my talk at PyCon for mode details). This might be a better way to hijack ReST than to create a gazillion custom directives, thereby creating more or less another markup language (with a smaller userbase, less tested!). > Can you list some of these "gotchas"? I've on maybe two occasions had to > add a backslash to something to prevent it being interpreted as markup, and > that's about it, although I've written many hundreds of K of Python > documentation in reST. (Not the Python core documentation, but other open > source projects written in Python.) Lots. No time to go through the whole list now, but here is an example: ----------------- .. Some text ----------------- and ----------------- .. Some text ----------------- Generate the following document structures, respectively: <comment xml:space="preserve"> Some text and <comment xml:space="preserve"> <block_quote> <paragraph> Some text One is a comment, the other is an empty comment followed by a block quote. Not very obvious to me, unless you know "the rules". Easy to make mistakes. There are *many* other issues just like this one. Pop quiz: what does this generate? ----------------- .. Some text Some other text ----------------- _______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
