Skip Montanaro wrote: > >> 1. reference docs: ... > >> > >> 2. user documentation: ... > > Ian> I think that's a good distinction. And like several people I'm not > Ian> very interested in 1. > > Ah, but I started this thread thinking about #1. <wink>
Well, not the #1 that Martin described (epydoc-like). The Python documentation is a perfect example of #2 -- documentation written completely by hand that provides a structured and concise description of a module. I shudder to think about what #1 would look like for the standard library. Well, that's not fair, I can see exactly what it looks like: http://epydoc.sourceforge.net/stdlib/ -- maybe "shuddering" isn't really appropriate (it's not that bad), but it's not at all like the reference docs we know and love. > FYI, while #2 is important, I'm still interested in this. I'm particularly > interested in being able to replace latex2html with something more flexible > that would allow relatively easy experimentation with the online > presentation of the core documentation. Well, getting back to your original question about ReST (I've also copied David Goodger and Felix Wiemann, as they might have more to say about this and I'm not sure if they are tracking this list)... * I believe ReST markup is a superset of the conventional Python Latex. I know a couple people worked on this at PyCon 2004, and they seemed to feel that local roles were the only missing part (to specifically mark a word as being a class name, for instance), and that was added to docutils a while ago in response. This doesn't address linking, indexing, or the build process -- just the local markup. * ReST is a superset, so there's a bunch of things that I think are much more easily expressed there than in the Latex. (Note: I have no idea what the actual Latex looks like, I only say this from familiarity with its output ;) The problem with this is that it may be hard to mix documents generated from the two sources and keep a consistent style. * There's no build process that would apply. This doesn't seem like a huge task, nor one that can really be addressed until someone actually tries it. * Interlinking documents may be difficult. ReST documents can't easily be merged or separated (from what I can tell), and there's no support for abstract links (you can only link internally or to concrete files). These are acknowledged problems with ReST, so there might ideas or even code to address this. * I'm not sure about indexing -- there's markup to express indexable terms (I believe), but I don't know if there's tools that actually make use of that. * That said, some of its internal-to-the-document indexing is better. It creates lots of anchors allowing deeper links and the contents headers are often useful. It's readily extensible on the local level by adding new directives and inline roles. * There's no tools that I know of to generate ReST. I think it would have to be based on heuristics, with manual editing. I think the warnings are pretty good, though, so I think this is doable without having to carefully proofread all of the output. * I personally find writing ReST pleasant, but I think Michael is right that it's not the Latex that keeps people from contributing. Personally, I think it has a lot to do with an intimidation factor; standard library docs are implicitly authoritative, so you don't write docs on a whim. Well, does anyone write docs on a whim? Anyway, if I was to analyze my own non-contribution, that'd probably be the reason. Anyway, I think commenting and annotation systems -- while often annoying and messy -- do offer a middleground for contributors. For the most part these could be applied to the current system; but ReST would make it easier, and has (some) more potential for streamlining the integration process, integrating comments and annotations into the actual documentation. * OTOH, complicated build tools are death to building a group of contributors -- it makes a huge difference, because contributors are grown over time, most don't start with the intention to be serious contributors. The offer to convert documents doesn't necessarily make its way to the people who would take you up on it. -- Ian Bicking / [EMAIL PROTECTED] / http://blog.ianbicking.org _______________________________________________ Doc-SIG maillist - [email protected] http://mail.python.org/mailman/listinfo/doc-sig
