Mailman 3 September 1999 - Doc-SIG

XML Conversion Update
by Fred L. Drake, Jr. Dec. 3, 1999

Dec. 3, 1999

Last week I promised on the Python list to describe the current status of the conversion to SGML/XML. Here it is! I'm currently able to parse all the LaTeX markup and generate either XML or SGML. The structure of the output is very similar to the input structure, but a number of minor improvements are made. The improvements are mostly very localized and have more to do with keeping the markup from getting to complex and disjointed, and eliminating some bogosities. I am not at all decided on a DTD to use. I see three options: 1. DocBook -- this has been developed and heavily use-tested by a number of corporate users, and is known to be good for technical documentation. There are tools and stylesheets available to convert from DocBook to HTML and printed formats. We'd probably need to specialize it, but it's designed for that. Konrad Hinsen has already developed one customization that he's using to document Python modules, and there's an initiative to create a common extension for documenting OO constructs. I've asked Konrad for some sample documentation so I can see how it actually works out. My concern with DocBook is that the markup may be a bit on the "heavy" side; I don't want the document source to be so markup-heavy that I'm the only one to work on them. 2. Create something similar to what we had in LaTeX, but with fewer warts. This is appealing because the conversion would be done sooner. However, new stylesheets would be needed, slowing down the usefulness of the result. It would also be the easiest to adopt for people already familiar with the current markup. 3. Create something entirely new and specific to Python. Clearly, this offers a lot of work to all the volunteers. We'd need requirements analysis, DTD design, stylesheets, and probably lots of things I haven't thought of. However, it also means we can limit the weight of the markup in the source, which might be a major advantage in getting people to use it. But *everyone* would have to learn it (well, everyone that writes documentation at any rate). This offers a great deal of opportunity to "get it right" for Python, but also a lot of rope. (You know what rope is used for, right?) I'd like to see some discussion on what should be done and what needs to be done. From where I sit, the most important thing is to make sure we can maintain a high level of semantic markup (hopefully making further improvements over what we already have), with generation of hypertext (HTML, info, whatever) being the next most important thing. Typeset documents are a requirement, but aren't as high up the list. I'm not terribly concerned about how XML/SGML-->foo conversion processes are implemented, with the caveat being that I need to be able to understand them without a massive learning curve. Clearly, Python code is a major option for tools (surprised?), but I can easily deal with using Java tools (with or without JPython), DSSSL processors (just don't expect me to maintain Jade/OpenJade!), XSL, CSS, and whatnot. I'd like to get away from having any Perl scripts involved, not because I think Perl is Evil, but because I'm not a Perl hacker. (Don't get me wrong; I make no claim that Perl is not Evil! ;) Comments, suggestions, volunteers? -Fred -- Fred L. Drake, Jr. <fdrake(a)acm.org> Corporation for National Research Initiatives

9 16

Re: [Doc-SIG] XML Conversion Update
by Jack Jansen Dec. 3, 1999

Dec. 3, 1999

While I agree with Sean (and others) that small DTDs are a lot better suited to documenting Python modules there's various standard-formatting things that you'd like to borrow from existing DTDs (emphasis, references to other manuals/sections, footnotes, etc). Is there a way that that could be done, without dragging in the whole of the (apparently huge and hairy, from the reports here) docbook DTD? -- Jack Jansen | ++++ stop the execution of Mumia Abu-Jamal ++++ Jack.Jansen(a)oratrix.com | ++++ if you agree copy these lines to your sig ++++ www.oratrix.nl/~jack | see http://www.xs4all.nl/~tank/spg-l/sigaction.htm

6 8

Re: [XML-SIG] Re: PyDoc/XML?
by Sean Mc Grath Sept. 30, 1999

Sept. 30, 1999

[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 <module>foo</module>, the function > <function>bar</function> provides... > >The corresponding SGML (with the right declaration) might be: > > In the module <module>foo</>, the function <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 <module/>foo, the function <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:-) <Sean uri="http://www.digitome.com/sean.html"> Developers Day co-Chair WWW9, April 2000, Amsterdam <uri>http://www.www9.org</uri> </Sean>

2 1

Re: [XML-SIG] Re: PyDoc/XML?
by uche.ogbuji＠fourthought.com Sept. 29, 1999

Sept. 29, 1999

[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] <http://my.netscape.com/publish/help/mnn20/quickstart.html> > [2] <http://my.userland.com/stories/storyReader$14> 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(a)fourthought.com (970)481-0805 Software engineering, project management, Intranets and Extranets http://FourThought.com http://OpenTechnology.org

1 0

status
by Fred L. Drake, Jr. Sept. 1, 1999

Sept. 1, 1999

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. <fdrake(a)acm.org> Corporation for National Research Initiatives

1 0