Mailman 3 December 2002 - Doc-SIG

reST block quotes
by fantasai Dec. 22, 2002

Dec. 22, 2002

hmm.. it's been awhile. ok, so there's a problem with the blockquote syntax that was one of the first things I noticed: The syntax relies exclusively on indentation. This means one can't use indentation for other things--like indenting sections to make the document structure easier to grasp. The other problem is that attributions don't seem to be recognized. It would be nice to put uris in HTML's 'cite' attribute and mark up just regular attributions as such. | An Attribution identifies the source to whom a | BlockQuote or Epigraph is ascribed. -- http://www.docbook.org/tdg/en/html/attribution.html So, I'd like to have reST take something like that (URIs might need something to distinguish them from, say, people) and translate it into appropriate markup. An option could require the pipe quoting or another symbol (e.g. '>') and just treat indented blocks as regular text. (I'd gotten the symbol-quoting part to work last year, but ran into some trouble with the attribution (I was using a different syntax) and put everything aside for later.) So, what do you think? ~fantasai

6 29

Python Reader module parser now usable
by David Goodger Dec. 19, 2002

Dec. 19, 2002

The first part of the Docutils Python Source Reader component is in a usable form: <http://docutils.sf.net/docutils/readers/python/moduleparser.py>. It takes a module's text (a string) and converts it into a documentation-oriented tree. Assignments/attributes, functions, classes, and methods are all converted. Arbitrarily complex right-hand sides of assignments (including default parameter values) are supported by parsing tokens from tokenize.py. Comments are not handled yet, and namespaces are not computed. There's a list of open issues at the end of the module docstring. I've also added a "showdoc" script to test/test_readers/test_python which processes input from the test_parser.py module, or stdin, depending on how it's called. Please play with these; any input is welcome. Here's a sample. Given this module as input:: # comment """Docstring""" """Additional docstring""" __docformat__ = 'reStructuredText' a = 1 """Attribute docstring""" class C(Super): """C's docstring""" class_attribute = 1 """class_attribute's docstring""" def __init__(self, text=None): """__init__'s docstring""" self.instance_attribute = (text * 7 + ' whaddyaknow') """instance_attribute's docstring""" def f(x, # parameter x y=a*5, # parameter y *args): # parameter args """f's docstring""" return [x + item for item in args] f.function_attribute = 1 """f.function_attribute's docstring""" Here's the output tree, with objects converted to the pseudo-XML form I'm fond of:: <Module filename="<stdin>"> <Docstring> Docstring <Docstring lineno="5"> Additional docstring <Attribute lineno="7" name="__docformat__"> <Expression lineno="7"> 'reStructuredText' <Attribute lineno="9" name="a"> <Expression lineno="9"> 1 <Docstring lineno="10"> Attribute docstring <Class bases="Super" lineno="12" name="C"> <Docstring lineno="12"> C's docstring <Attribute lineno="16" name="class_attribute"> <Expression lineno="16"> 1 <Docstring lineno="17"> class_attribute's docstring <Method lineno="19" name="__init__"> <Docstring lineno="19"> __init__'s docstring <ParameterList lineno="19"> <Parameter lineno="19" name="self"> <Parameter lineno="19" name="text"> <Default lineno="19"> None <Attribute lineno="22" name="self.instance_attribute"> <Expression lineno="22"> (text * 7 + ' whaddyaknow') <Docstring lineno="24"> instance_attribute's docstring <Function lineno="27" name="f"> <Docstring lineno="27"> f's docstring <ParameterList lineno="27"> <Parameter lineno="27" name="x"> <Parameter lineno="27" name="y"> <Default lineno="27"> a * 5 <ExcessPositionalArguments lineno="27" name="args"> <Attribute lineno="33" name="f.function_attribute"> <Expression lineno="33"> 1 <Docstring lineno="34"> f.function_attribute's docstring -- David Goodger <goodger(a)python.org> Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) - The Go Tools Project: http://gotools.sourceforge.net/

1 0

Adding new inline markup?
by Andrew Kuchling Dec. 18, 2002

Dec. 18, 2002

RST only supports a few different inline markup notations, such as * and ** for emphasis, ` for interpreted things, &c. For my application I'd like to add some more inline markups, such as /cited text/. Should I expect to be able to subclass Inliner in order to add new notations? Right now that's rather messy. Inliner.dispatch is a dictionary mapping symbols to handler methods, but the large regular expression stored as Inliner.parts doesn't take this into account. First, is there some other, better, way of adding new inline notations? Second, if not, should it be possible by subclassing Inliner? A possible way of handling this would be to add an internal method _get_initial_pattern() to the Inliner class that synthesized the 'parts' regular expression, using self.dispatch.keys() to match all the listed inline markups. Inliner is fairly complicated, though, so maybe there are additional changes that would be necessary. --amk (www.amk.ca) It was astonishing the number of useless things people found to do. -- R.H. Barlow and H.P. Lovecraft, "The Night Ocean"

3 4

compact HTML output from Docutils
by David Goodger Dec. 17, 2002

Dec. 17, 2002

I've tweaked Docutils' HTML writer to produce more visually compact HTML (less vertical whitespace). HTML's mixed content models allow list items to contain "<li>body elements</li>" or "<li>just text</li>" or even "<li>textand body elementscombined</li>", each with different effects. I'd prefer to stick with strict body elements in list items, but they affect vertical spacing in browsers (although they really shouldn't). Does anybody know of a good discussion of vertical space issues for HTML and/or CSS? After trying various algorithms, I've settled on a hybrid: - Check for and omit tags in "simple" lists: list items contain either a single paragraph, a nested simple list, or a paragraph followed by a nested simple list. This means that this list can be compact: - Item 1. - Item 2. But this list cannot be compact: - Item 1. This second paragraph forces space between list items. - Item 2. - In non-list contexts, omit tags on a paragraph if that paragraph is the only child of its parent (footnotes & citations are allowed a label first). - Regardless of the above, in definitions, table cells, field bodies, option descriptions, and list items, mark the first child with 'class="first"' if it is a paragraph. The stylesheet sets the top margin to 0 for these paragraphs. I'd appreciate feedback, especially from people using different browsers (I've checked IE and Mozilla on both MacOS & Win2K, and Netscape 4 & 6 on MacOS). Please browse the following files: - http://docutils.sf.net/tools/test.html - http://docutils.sf.net/spec/pep-0287.html - http://docutils.sf.net/spec/pep-0000.html Is the above approach correct? Does the generated HTML come out right? Should the compact output be optional (i.e. should there be an option to turn it off)? Any suggestions? Get your snapshots here: http://docutils.sf.net/docutils-snapshot.tgz -- David Goodger <goodger(a)users.sourceforge.net> Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) - The Go Tools Project: http://gotools.sourceforge.net/

4 3

looking for prior art
by David Goodger Dec. 7, 2002

Dec. 7, 2002

I have begun work on a Python source Reader component for Docutils. I expect the work to go slowly, as there is lots to absorb, much earlier work to study and learn from, and little spare time to devote. I'm trying to keep it as simple as possible, mostly for my own benefit (lest my brain explode). I've looked over the HappyDoc code and Tony "Tibs" Ibbs' PySource prototype. HappyDoc uses the stdlib "parser" module to parse Python modules into abstract syntax trees (ASTs), but that seems difficult and fragile, the ASTs being so low-level. Tibs' prototype uses the much higher-level ASTs built by the stdlib "compiler" module, which are much easier to understand. I've decided to use the "compiler" module also. My first stumbling block is in parsing assignments. I want to extract the right-hand side (RHS) of assignments straight from the source. In his prototype, Tibs rebuilds the RHS from the AST, but that seems rather roundabout and the results may not match the source perfectly (equivalent, but not character-for-character). I think using the "tokenize" module in parallel with "compiler" may allow the code to extract the raw RHS text, as well as other raw text that doesn't make it verbatim to the AST. So, is there any prior art out there? Any pointers or advice? -- David Goodger <goodger(a)python.org> Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) - The Go Tools Project: http://gotools.sourceforge.net/

4 7

Re: [Doc-SIG] looking for prior art
by Michael Hudson Dec. 6, 2002

Dec. 6, 2002

Doug Hellmann <doug(a)hellfly.net> writes: > If you're starting from scratch, I would definitely recommend trying the > compiler module first. Amen. [...] > Does compiler include comments? No. tokenize.py does, though. I don't know how hard it would be to turn the output of tokenize.py into something like the output of compiler/transformer.py, but with comments. SPARK may be your friend... Cheers, M. -- Two things I learned for sure during a particularly intense acid trip in my own lost youth: (1) everything is a trivial special case of something else; and, (2) death is a bunch of blue spheres. -- Tim Peters, 1 May 1998

1 0

Including files
by Pearu Peterson Dec. 1, 2002

Dec. 1, 2002

Hi, I am using Docutils in creating a reference manual (for F2PY project) and found that it would be nice if rst formatted text files could have some support for including other rst formatted text files as well as various source codes to the document. The equivalent hooks in LaTeX would be \input{..} and \verbatiminput{..} commands. Typical usage cases: * If a rst-text file tends to become very large (in the sense that its printed version has, say, 20 or more pages) then factoring it to different files would ease maintaining such documents. * Including example source codes. Currently one has to maintain two copies of source codes, one as a source file and one typed (copied) into the rst-text file. I am not sure what would be appropiate Docutils hooks for emulating LaTeX \input or \verbatiminput commands but may be something like the following: * Using :: .. input:: filename in a rst-text file is equivalent to a situation as if the ``.. input:: filename`` part is replaced by the contents of ``filename``, possibly taking into account also indentation level. Possible variations for ``input``:: file insert include fileinput .. * Using :: .. verbatim:: filename is equivalent to including the contents of ``filename`` as a literate block to the current rst-text file. Possible variations for ``verbatim``:: source verbatiminput .. What do you think? Pearu

2 2