From: Mark N. <Mar...@fr...> - 2005-10-21 21:13:34
|
Martin Blais wrote: > So [David Goodger] said I should have another look and make a list of the > elements I found that I thought did not fit in the context of a > generic document representation and send to the list. Here they > are: > > * all the *options list* elements. > > Those are really specific to documenting man pages for > computer programs, and unless docutils is used a lot for that > purpose--which I think it isn't--they should be removed. > Displaying option lists could be carried out using normal > document structures, e.g. tables, bulleted items, etc. This > is what people who write manuals do. I can't say how commonly these elements are used, but I know that we make heavy use of them here at Freescale. Of course, I *do* work for a tools group... > * the *doctest* blocks. > > These are highly Python-specific. I know that if I were to > consider some file format for generic use and it had some tags > specific to VisualBasic I would probably stop reading right > there and look for something else right away. I would think > that someone not familiar with Python might think > similarly. Also, the fact that docutils is implemented in > Python should not influence the choices of nodes for > documentation representation--who knows, maybe one day Python > will be gone and the docutils reference implementation will be > written in LISP. Also, these would be easily replaced by > literal blocks, maybe with a class tag, for those who want to > customize. Agreed. > These two sets of nodes are those I object to. > > I was wondering what other people think about the idea of > removing them or phasing them out from the docutils nodes tree? > > Are there any other nodes that you find are not generic? I think all the specific admonition elements could easily be rolled into the generic admonition element. Incorporating the docinfo elements into a generic docinfo-element element could also simplify writer development. --Mark |