On May 3, 2009, at 9:03 AM, James Rowe wrote:
> Is this going to be the Great Sphinx Bikeshedding of '09? :) > > * Doug Hellmann (doug.hellm...@gmail.com) wrote: >> On May 3, 2009, at 5:54 AM, Christophe de VIENNE wrote: >>> 2009/5/2 Georg Brandl <ge...@python.org> >>>> - Rename Sphinx' "class". I don't have a suggestion for a better >>>> name though. >> >> +1 on warning in the next point release and generating an error in >> 1.0. > > I like that too, as I said in my other mail the idea of long-lived > alias seems like a bad idea in my eyes. > >> My point is that having an incompatibility with docutils will always >> raise issues, and since changing docutils seems less realistic, it >> leaves only one option. > > Am I the only person who thinks the incompatibility is much, much > broader than the cssclass issue. I don't believe I have a document > source that I use with Sphinx that is compatible with rst2html.py, > because they use module markup or inline cross-referencing or ... > > Yes, I can make them available by writing my own rst2html.py but it > is > still incompatible with docutils as installed, I just feel the > compatibility argument is flawed. Tell me I wrong though, in fact > I likely am if nobody else sees this. I'm not that concerned about absolute compatibility, but I would prefer sphinx to build on docutils rather than modify it. I should be able to give my tech writer the docutils version of the reST markup reference (which is much more complete than the primer included with the sphinx docs) and have that markup just work. That level of compatibility would mean I could use the same README file as part of my overall package docs generated by sphinx and as the file I pass to setuptools as my "long description" when uploading files to PyPI. >>> Now for the new name the only one I can think of is "pclass" (for >>> python class). But if Sphinx is used for documenting other languages >>> the rational of this name is lost. >> >> If "cssclass" becomes "class" to match docutils, you could make the >> "class" for describing code something like "codeclass" to make it >> explicitly code-related. > > What pains me about the change to "codeclass" is what it means to the > rest of the code documenting syntax, at least with the current > incompatibility we have uniform naming. Or, and personally I don't > mind > the idea, should the entire syntax group receive the prefix: > "codefunction", "codeattribute", etc. Using the prefix for all of those directives makes sense. Maybe we want something other than "code"? Can directives have "." in them (e.g., "code.class", "code.function")? Doug --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "sphinx-dev" group. To post to this group, send email to sphinx-dev@googlegroups.com To unsubscribe from this group, send email to sphinx-dev+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en -~----------~----~----~----~------~----~------~--~---
