From Fred L. Drake, Jr." Well, there's been a lot of discussion! ;-) This is good. I've been out a couple of days unexpectedly, and am still reading the mail. I'm not forgetting about the issues I've raised, but want a chance to read through what everyone has said before I start throwing my opinions around again. -Fred -- Fred L. Drake, Jr. Corporation for National Research Initiatives From uche.ogbuji@fourthought.com Wed Sep 29 17:43:04 1999 From: uche.ogbuji@fourthought.com (uche.ogbuji@fourthought.com) Date: Wed, 29 Sep 1999 12:43:04 -0400 Subject: [Doc-SIG] Re: [XML-SIG] Re: PyDoc/XML? In-Reply-To: Your message of "Wed, 29 Sep 1999 12:30:44 CDT." <19990929123044.A58950@enteract.com> Message-ID: <199909291643.MAA01229@malatesta.local> [hi doc-sig folks. This is a conversation that has been brewing in xml-sig, but I think you may find it relevant] > > I am trying to learn XML by developing my own tools. This has introduced > > me to some of the more subtle aspects of XML and has caused me to revise > > my opinion of what XML is. (Actually, I think my XML 'evangelists' don't > > really know exactly what XML is and are abusing it by proposing it for > > object databases and other somewhat mis-appropriate uses). I see XML > > strictly as a way of marking up a 'document' to expose its structure and > > semantics. Sure, documents are trees, like databases, but doesn't necessarily > > imply XML is a good way to implement a database. (Basic necessities such > > as query languages don't exist, yet). > > In my experience it's really awkward to author material using > XML/SGML-based notations. And even with the best XML-authoring tool > that I can conceive, there's still the problem of reading and revising > the content later. To me, even the best of XML documents are just > plain *ugly*. XML makes sense as a data interchange format, but *not* > as an authoring format or as a database format. It isn't ideal, but I've got used to typing in XML. Maybe that's why I don't have so many of the typical first-glance reactions anymore, and I don't even remember having had them. When I'm hacking at XML, I'm usually thinking in that mode, and I make liberal use of EMACS short-cuts to get things done switfly. Of course this will never do for most normal people, and that us why no-one here has been advocating that Python programmers type their docs in straight XML. All I was pursuing was an XML format for the eventual product, and user-friendly tools such as you describe for RSS would come along easily enough. > In the case of > software documentation, XML could play a role in providing a basis for > a family of DTDs used in sharing useful information about programs, > such as consolidating reference material from multiple sources (and > source languages) into a common catalog or repository. The actual > documentation source would be designed to be convenient to the authors > and maintainers of the programs, and translated to the common XML DTDs > as necessary. > > One related example is the "RSS" format being promulgated by > UserLand.com and Netscape [1]. It's an XML DTD for publishing short > news items and weblogs with links to extended material. Getting to my > point... one of the first things RSS authors did is write scripts to > generate the RSS/XML code from source written in a simple > structured-text format [2]. This is likely to be typical: frequent > users will create their own mini-language tailored to their tasks, and > will use scripts to generate the XML from that source. > > [1] > [2] I should note that the explosion of mini-languages is probably not a good thing. I don't think it's a matter for language conversion, I think it's a case for intelligent tools. I just read through the recent doc-sig archives and a relevant discussion has been taking place there. What I conclude is that there will be no solution to meet all tastes, so this is the best we can hope for: 1) Perhaps a single structured, "normal" format for Python doc-strings that can be exported to XML. Perhaps this would be some variant of John Day's RML markup. Some people would ignore this facility, and I would be one of them. 2) A nice tool (perhaps Web-based) for generating [X|SG]ML docs from source code. My idea is that it could read Python source and put up a form or interactively ask the programmer to fill in the fields corresponding to the parts that need to be documented. This is the approach I would choose to use. 3) A DTD or schema for storing *ML docs for Python modules regardles of whether they were generated from method (1) or (2) above. It would also be used by the direct-to-*ML folks using their favorite intelligent editor. 4) A tool that could map the *ML docs back to doc-strings and comments embedded within the Python code for amateurs of method (1) 5) A tool that could generate links from code doc-strings and comments to relevant parts of the separate *ML docs for people who prefer their docs separate but accessible (probably amaterus of method (2), myself included). I don't think the above tools would be too hard to write. FourThought has already made a small start on (2), (3) and (5). And these tools would appear to satisfy all the preferences I've observed so far. -- Uche Ogbuji FourThought LLC, IT Consultants uche.ogbuji@fourthought.com (970)481-0805 Software engineering, project management, Intranets and Extranets http://FourThought.com http://OpenTechnology.org From sean@digitome.com Thu Sep 30 09:56:45 1999 From: sean@digitome.com (Sean Mc Grath) Date: Thu, 30 Sep 1999 09:56:45 +0100 Subject: [Doc-SIG] Re: [XML-SIG] Re: PyDoc/XML? In-Reply-To: <14322.21025.492054.432751@weyr.cnri.reston.va.us> References: <199909291458.KAA00987@malatesta.local> <3.0.1.32.19990929112045.006b55bc@mail.csihq.com> <199909291458.KAA00987@malatesta.local> Message-ID: <3.0.6.32.19990930095645.009b8db0@gpo.iol.ie> [Fred Drake over on xml-sig] > I think the only thing I'd really like to be able to use from SGML >that XML doesn't offer is the empty end tag. When marking one or two >words, XML is incredibly verbose. If I have: > > In the module foo, the function bar() provides... > >The XML might be: > > In the module foo, the function > bar provides... > >The corresponding SGML (with the right declaration) might be: > > In the module foo, the function bar > provides... > An alternative is to use an application specific rule rather than rely on the markup language. Here is what I mean: In the module foo, the function bar provides... Here module and function are point elements identifying the point at which module/function names begin. Application logic then terminates the module/function name using appropriate lexical rules i.e. next piece of whitespace or whatever. I would be the first to admit that some people find this approach revolting but it works and it is valid XML:-) Developers Day co-Chair WWW9, April 2000, Amsterdam http://www.www9.org From Fred L. Drake, Jr." References: <199909291458.KAA00987@malatesta.local> <3.0.1.32.19990929112045.006b55bc@mail.csihq.com> <3.0.6.32.19990930095645.009b8db0@gpo.iol.ie> Message-ID: <14323.29759.905232.70250@weyr.cnri.reston.va.us> Sean Mc Grath writes: > In the module foo, the function bar > provides... ... > I would be the first to admit that some people find > this approach revolting but it works and it is valid Ouch! I hadn't even imagined this option! What do others (prospective authors!) think about this? The minimal markup is appealing, but the structure is ... weird. (I suspect that writing DSSSL or XSL to support it directly would be very difficult, but I don't yet consider myself proficient at either of those.) So is anyone working on a DSSSL book? ;-) -Fred -- Fred L. Drake, Jr. Corporation for National Research Initiatives