From da@maigret.cog.brown.edu Mon Feb 10 19:00:12 1997 From: da@maigret.cog.brown.edu (David Ascher) Date: Mon, 10 Feb 1997 14:00:12 -0500 (EST) Subject: [PYTHON DOC-SIG] SGML-Tools Message-ID: <199702101900.OAA16284@maigret> FYI: The Linux Documentation Project has recently changed the name of their tool suite to SGML-Tools. I'd recommend that we at least consider it as a possibility, just to leverage off of their efforts. http://web.inter.NL.net/users/C.deGroot/sgmltools/ --david PS: I may convert my Numeric tutorial to it to see how painful it is. It might make sense for someone to convert one of the existing .tex files to .sgml to see how painful that is. _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From guido@CNRI.Reston.Va.US Mon Feb 10 19:32:42 1997 From: guido@CNRI.Reston.Va.US (Guido van Rossum) Date: Mon, 10 Feb 1997 14:32:42 -0500 Subject: [PYTHON DOC-SIG] SGML-Tools In-Reply-To: Your message of "Mon, 10 Feb 1997 14:00:12 EST." <199702101900.OAA16284@maigret> References: <199702101900.OAA16284@maigret> Message-ID: <199702101932.OAA01256@monty> > FYI: The Linux Documentation Project has recently changed > the name of their tool suite to SGML-Tools. I'd recommend > that we at least consider it as a possibility, just to leverage > off of their efforts. > > http://web.inter.NL.net/users/C.deGroot/sgmltools/ Hmm, coming from the Netherlands it can't be all that bad :-) Seriously, it looks like they used the LaTeX document structure and command set as a model, which could be an advantage for the Library reference manual and the (yet to write :-) Python-C API manual. On the other hand, the list of software that is *required* to make it work is rather impressive, and I wonder how easy it would be to do some of the conversion steps on Windows (or Mac, but the larger market share has more power :-( ). > PS: I may convert my Numeric tutorial to it to see how painful it is. > It might make sense for someone to convert one of the existing .tex > files to .sgml to see how painful that is. If someone steps forward and converts the library manual (or a single chapter or even section) to SGML, that would be great. I expect that the fastest approach is to develop a flexible latex-to-anything converter... I'd also be interested in conversion results to TIM, and would like to consider a comparison of the quality of the restulting Postscript and HTML (being probably the most useful output formats). --Guido van Rossum (home page: http://www.python.org/~guido/) _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From da@maigret.cog.brown.edu Mon Feb 10 19:48:07 1997 From: da@maigret.cog.brown.edu (David Ascher) Date: Mon, 10 Feb 1997 14:48:07 -0500 (EST) Subject: [PYTHON DOC-SIG] SGML-Tools In-Reply-To: <199702101932.OAA01256@monty> from "Guido van Rossum" at Feb 10, 97 02:32:42 pm Message-ID: <199702101948.OAA17012@maigret> > On the other hand, the list of software that is *required* to make it > work is rather impressive, and I wonder how easy it would be to do > some of the conversion steps on Windows (or Mac, but the larger market > share has more power :-( ). They are planning to move to PERL as their awk/sed replacement. I suspect if we intervened, we might be able to convince them to use Python (especially if the regex stuff goes through =). Then we wouldn't have any problems. Has anyone tried to make a PythonAWK? > If someone steps forward and converts the library manual (or a single > chapter or even section) to SGML, that would be great. I expect that > the fastest approach is to develop a flexible latex-to-anything > converter... I'd also be interested in conversion results to TIM, and > would like to consider a comparison of the quality of the restulting > Postscript and HTML (being probably the most useful output formats). Right. TIM has a slightly different look and feel in the HTML mode, and both look great as Latex/dvi/postscript documents. One issue which I think neither probably deal with very well is the notion of cross-references (which should become HREF's). For example, references to functions in other modules should become href'ed automatically. I know that emacs has good smgls support, but I haven't tried to write with it. --david _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From fdrake@CNRI.Reston.Va.US Mon Feb 10 19:47:38 1997 From: fdrake@CNRI.Reston.Va.US (Fred L. Drake) Date: Mon, 10 Feb 1997 14:47:38 -0500 (EST) Subject: [PYTHON DOC-SIG] SGML-Tools In-Reply-To: <199702101932.OAA01256@monty> from "Guido van Rossum" at Feb 10, 97 02:32:42 pm Message-ID: <199702101947.OAA01999@weyr.CNRI.Reston.Va.US> Guido van Rossum wrote: > > > FYI: The Linux Documentation Project has recently changed > > the name of their tool suite to SGML-Tools. I'd recommend > > that we at least consider it as a possibility, just to leverage > > off of their efforts. > Seriously, it looks like they used the LaTeX document structure and > command set as a model, which could be an advantage for the Library > reference manual and the (yet to write :-) Python-C API manual. Their document type definition is based on an old DTD called "QWERTZ" which was intended to be almost a direct translation of LaTeX. Other than allowing documents to be validated against a DTD and being able to use their software, there don't appear to be any particular advantages to linuxdox/sgml-tools. > On the other hand, the list of software that is *required* to make it > work is rather impressive, and I wonder how easy it would be to do Windows NT is probably pretty straightforward, especially if you can get a bourne shell and perl pre-built. The shell might be the hardest thing in the freeware market. (I haven't heard of bash being ported to NT, and I'd guess that's unlikely.) The SGML parser should be readily available. > > PS: I may convert my Numeric tutorial to it to see how painful it is. > > It might make sense for someone to convert one of the existing .tex > > files to .sgml to see how painful that is. > > If someone steps forward and converts the library manual (or a single > chapter or even section) to SGML, that would be great. I expect that > the fastest approach is to develop a flexible latex-to-anything > converter... I'd also be interested in conversion results to TIM, and > would like to consider a comparison of the quality of the restulting > Postscript and HTML (being probably the most useful output formats). I'd be quite glad to do the work if we could decide on a usable DTD, but I don't think QWERTZ-derived DTDs really qualify. There are others (DocBook springs to mind; http://www.ora.com/davenport/index.html), but they get complex if they're actually much good, and are probably hard to deal with in the fairly open Python community. I don't think it would be hard to derive or create something useful or even write the tools, but it would take a little doing. There is an early DSSSL (SGML style sheet) implementation available that supports output in HTML, RTF, and TeX, but the style sheet and some support would need to be written. -Fred -- Fred L. Drake, Jr. fdrake@cnri.reston.va.us Corporation for National Research Initiatives 1895 Preston White Drive Reston, VA 20191-5434 _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From guido@CNRI.Reston.Va.US Mon Feb 10 20:08:54 1997 From: guido@CNRI.Reston.Va.US (Guido van Rossum) Date: Mon, 10 Feb 1997 15:08:54 -0500 Subject: [PYTHON DOC-SIG] SGML-Tools In-Reply-To: Your message of "Mon, 10 Feb 1997 14:47:38 EST." <199702101947.OAA01999@weyr.CNRI.Reston.Va.US> References: <199702101947.OAA01999@weyr.CNRI.Reston.Va.US> Message-ID: <199702102008.PAA01345@monty> > Their document type definition is based on an old DTD called > "QWERTZ" which was intended to be almost a direct translation of > LaTeX. Other than allowing documents to be validated against a DTD > and being able to use their software, there don't appear to be any > particular advantages to linuxdox/sgml-tools. [...] > I'd be quite glad to do the work if we could decide on a usable DTD, > but I don't think QWERTZ-derived DTDs really qualify. There are > others (DocBook springs to mind; > http://www.ora.com/davenport/index.html), but they get complex if > they're actually much good, and are probably hard to deal with in the > fairly open Python community. I don't think it would be hard to > derive or create something useful or even write the tools, but it > would take a little doing. There is an early DSSSL (SGML style sheet) > implementation available that supports output in HTML, RTF, and TeX, > but the style sheet and some support would need to be written. Hmm... Given the requirements of acceptance in the Python community, which requires common freeware that runs on Unix and Windows (at least), what do you *recommend*? Or, perhaps this question is premature -- what list of criteria do you think we should use for deciding on Python documentation tools? --Guido van Rossum (home page: http://www.python.org/~guido/) _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From graham.hughes@resnet.ucsb.edu Mon Feb 10 20:30:06 1997 From: graham.hughes@resnet.ucsb.edu (Graham C. Hughes) Date: Mon, 10 Feb 1997 12:30:06 -0800 Subject: [PYTHON DOC-SIG] SGML-Tools In-Reply-To: <199702101947.OAA01999@weyr.CNRI.Reston.Va.US>; from Fred L. Drake on Feb 10, 1997 14:47:38 -0500 References: <199702101932.OAA01256@monty> <199702101947.OAA01999@weyr.CNRI.Reston.Va.US> Message-ID: <19970210123006.NW48577@A-abe.resnet.ucsb.edu> --28PehD5rHphoINzP On Feb 10, Fred L. Drake wrote > Their document type definition is based on an old DTD called > "QWERTZ" which was intended to be almost a direct translation of > LaTeX. Other than allowing documents to be validated against a DTD > and being able to use their software, there don't appear to be any > particular advantages to linuxdox/sgml-tools. Do you mean `advantages to SGML-Tools' or `advantages to SGML'? SGML has a lot to recommend it for this sort of idea, starting with the fact that it's much easier to translate into strange output formats than any other tool. Witness the perpetual difficulty turning the LaTeXed Python manuals into Texinfo for an example. SGML-Tools has the benefit that a large number of translators (to LyX, RTF (and thence to Windows Help), HTML, LaTeX, even straight text) are already written, and that somebody else is doing the maintenance so we don't have to. Plus, people like me can use it and not have to hack around with DTDs to get output to work. > > On the other hand, the list of software that is *required* to make it > > work is rather impressive, and I wonder how easy it would be to do One option is to distribute the SGML files, and either write a Python SGML parser (not a lot of fun...) or simply have the full documentation in various formats up on ftp.python.org. We could even be magnanimous and distribute the HTML output with the distribution. -- Graham Hughes (graham.hughes@resnet.ucsb.edu) http://A-abe.resnet.ucsb.edu/~graham/ -- MIME & PGP mail OK. "Never attribute to malice that which can be adequately explained by stupidity." -- Hanlon's Razor --28PehD5rHphoINzP Content-Type: application/pgp-signature -----BEGIN PGP SIGNATURE----- Version: 2.6.3 iQCVAwUBMv+FSiqNPSINiVE5AQGa+wP6AxPOzFV5zCromIMw9jSjiCtCvJ/NIqna NGqKnZKd/BugYQHUrWhDLCPlVK5a53CVcOKS7pBPSfGEuD7ih2N5k3PiJx4ZL9Yf pLIQzWYe9xZZazcdxgAp3qv31A/V4+oUnjNRJe9YgjkrXwbD4WP3xNn1Qk78/QHO Jr+c9RUSy/E= =5YFt -----END PGP SIGNATURE----- --28PehD5rHphoINzP-- _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From fdrake@CNRI.Reston.Va.US Mon Feb 10 20:56:54 1997 From: fdrake@CNRI.Reston.Va.US (Fred L. Drake) Date: Mon, 10 Feb 1997 15:56:54 -0500 (EST) Subject: [PYTHON DOC-SIG] SGML-Tools In-Reply-To: <19970210123006.NW48577@A-abe.resnet.ucsb.edu> from "Graham C. Hughes" at Feb 10, 97 12:30:06 pm Message-ID: <199702102056.PAA02146@weyr.CNRI.Reston.Va.US> Graham C. Hughes wrote: > Do you mean `advantages to SGML-Tools' or `advantages to SGML'? SGML > has a lot to recommend it for this sort of idea, starting with the fact Graham, Sorry for being unclear; I meant SGML-Tools specifically (I still tend to think Linuxdoc-SGML, must be getting dated). I am a strong advocate of SGML. > SGML-Tools has the benefit that a large number of translators (to LyX, > RTF (and thence to Windows Help), HTML, LaTeX, even straight text) are Translators are already available, yes, but the source format isn't sufficiently different from LaTeX to give any particular cause to convert. Yes, the interpretation of individual characters is difference and easier to handle, but that's about it; there is no additional logical structure to take advantage of, and that's where the usefulness of SGML comes in. Something like DocBook would give a little more useful structure, but still has some fairly substantial overhead where SGML tools are not the norm, and authoring in emacs would be non-trivial even with PSGML mode. I'd like to see a DTD that is reasonably simple but which includes elements such as FUNCTION, METHOD, CLASS, CONSTANT, PARAMETER, and others which might be useful to describe the structure of module contents with somewhat more clarity than the current LaTeX definitions do. I don't expect it to be hard to develop, but it would take time to think through and really get it right. This is not something I expect to be able to allocate any real time to which is why it hasn't already been done. > > > > On the other hand, the list of software that is *required* to make it > > > work is rather impressive, and I wonder how easy it would be to do > > One option is to distribute the SGML files, and either write a Python > SGML parser (not a lot of fun...) or simply have the full documentation > in various formats up on ftp.python.org. We could even be magnanimous > and distribute the HTML output with the distribution. I don't think there are problems with what is distributed; the problem is primarily one of maintainability. Extension authors will need to be able to keep their documents up-to-date and preview the formatted versions. A heavy SGML environment creates a problem for this (witness the complaints when Guido moved the language "specification" document to FrameMaker); the processing required should be readily achievable. The Python SGML parser *would* be quite fun, actually, if a little tedious to make really general. ;-) -Fred -- Fred L. Drake, Jr. fdrake@cnri.reston.va.us Corporation for National Research Initiatives 1895 Preston White Drive Reston, VA 20191-5434 _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From richardf@rbx.co.uk Mon Feb 10 23:43:27 1997 From: richardf@rbx.co.uk (Richard Folwell) Date: Mon, 10 Feb 1997 23:43:27 -0000 Subject: [PYTHON DOC-SIG] SGML-Tools Message-ID: <01BC17AC.3F8DC280@richardfathome.rbxlon> Available from SunSite as = http://sunsite.unc.edu/pub/Linux/utils/text/sgml-tools-0.99.0.tar.gz.=20 Does anyone have a sure-fire way of unpacking this kind of archive under = NT? I _do_ have access to a Linux box, but I don't use it much and = would much prefer to be able to handle it from my normal working OS. Thanks, Richard _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From MHammond@skippinet.com.au Tue Feb 11 01:34:22 1997 From: MHammond@skippinet.com.au (Mark Hammond) Date: Tue, 11 Feb 1997 11:34:22 +1000 Subject: [PYTHON DOC-SIG] SGML-Tools Message-ID: <199702110036.LAA29647@minotaur.labyrinth.net.au> > Does anyone have a sure-fire way of unpacking this kind of archive > under NT? I _do_ have access to a Linux box, but I don't use it > much and would much prefer to be able to handle it from my normal > orking OS. WinZip works well for me! Mark. ---------------------------------------------------------------------- Mark Hammond - MHammond@skippinet.com.au Check out Python - _the_ language for the Web/CGI/Windows/MFC/Unix/etc & _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From Anthony Baxter Tue Feb 11 04:29:23 1997 From: Anthony Baxter (Anthony Baxter) Date: Tue, 11 Feb 1997 15:29:23 +1100 Subject: [PYTHON DOC-SIG] SGML-Tools In-Reply-To: Your message of "Mon, 10 Feb 1997 15:56:54 CDT." <199702102056.PAA02146@weyr.CNRI.Reston.Va.US> Message-ID: <199702110429.PAA13273@jambu.off.connect.com.au> What about XML? : Overview > Extensible Markup Language (XML) is descriptively identified as "an > extremely simple dialect of SGML" the goal of which "is to enable > generic SGML to be served, received, and processed on the Web in the > way that is now possible with HTML," for which reason "XML has been > designed for ease of implementation, and for interoperability with both > SGML and HTML." XML is being "developed by a W3C Generic SGML Editorial > Review Board formed under the auspices of the W3 Consortium in 1996 and > chaired by Jon Bosak of Sun Microsystems, with the very active > participation of a Generic SGML Working Group also organized by the > W3C." [adapted from the Abstract of WD-xml-961101] > > Features in SGML but not in XML include [November 5, 1996], though not > exhaustively: "Tag omission; The CONCUR, LINK, DATATAG, and SHORTREF > features; The "&" connector in content models; Inclusions and > exclusions in content models; CURRENT, CONREF, NAME, NAMES, NUMBER, > NUMBERS, NUTOKEN, and NUTOKENS declarations for attributes; The NET > construct; Abstract syntax; Capacities and quantities; Comments > appearing within other markup declarations; Public Identifiers; > Omission of quotes on attribute values." _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From fdrake@CNRI.Reston.Va.US Tue Feb 11 16:13:47 1997 From: fdrake@CNRI.Reston.Va.US (Fred L. Drake) Date: Tue, 11 Feb 1997 11:13:47 -0500 (EST) Subject: [PYTHON DOC-SIG] SGML-Tools In-Reply-To: <199702110429.PAA13273@jambu.off.connect.com.au> from "Anthony Baxter" at Feb 11, 97 03:29:23 pm Message-ID: <199702111613.LAA03620@weyr.CNRI.Reston.Va.US> Anthony Baxter wrote: > What about XML? : XML is fine, but doesn't obviate the need for a DTD for our application. The advantages of XML at this point appear to be that many of the more difficult SGML constructs not often used simply aren't there and aren't needed for a general implementation. I see no reason that we couldn't use a DTD valid both for XML and SGML. ("Valid" XML is always valid SGML.) Whatever approach we take will require a bit of real decision-making regarding requirements and level of strictness which can be effectively used and enforced. I don't expect a set of translation tools from whatever source form we use to multiple interesting targets would be a problem if we have a clear and documented approach to using the framework. Processing tools can be included with the document sources. So how many of us have any knowledge or experience in DTD development? -Fred -- Fred L. Drake, Jr. fdrake@cnri.reston.va.us Corporation for National Research Initiatives 1895 Preston White Drive Reston, VA 20191-5434 _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From da@maigret.cog.brown.edu Tue Feb 11 18:16:59 1997 From: da@maigret.cog.brown.edu (David Ascher) Date: Tue, 11 Feb 1997 13:16:59 -0500 (EST) Subject: [PYTHON DOC-SIG] Re: DTD's for Python (fwd) Message-ID: <199702111817.NAA19264@maigret> I wrote to David Durand, who'se somewhat of a hypertext/sgml expert (he describes himself as an SGML bigot), just to get a little advice. Here's his reply, FYI: <---> From dgd@cs.bu.edu Tue Feb 11 17:44:04 1997 From: dgd@cs.bu.edu (David Durand) Date: Tue, 11 Feb 1997 12:44:04 -0500 Subject: DTD's for Python Message-ID: >Hi David. > >I'm writing for some technical advice. Sure, and I'm afraid that I'm continuing the tradition of computer scientists who study the "important problems." I don't follow all the details of all the DTDs and tools avaialble out there, so I may miss one or more obvious right things... > I'm on the Python DOC-SIG, and >we're once again considering what the right way to encode the Python >documentation is, especially the library reference. Right now it's in >pretty simple LaTeX, but we'd like to go to a real markup language, with >all the advantages that represents. >I threw in the idea of using the >Linux LDP tool which is basically the QWERTZ DTD and SGML. Someone >objected to the coarse nature of that DTD. Someone else suggested using >XML. The Linux tools already work in one of your major target environments, which is possibly a big factor. If they are easy to tailor, you could use some of their code as a starting point to getting things to work nicely. Docbook is a well-reputed DTD, though I confess to never having read it. Both Eve Maler and Terry Allen are sharp, experienced people. There must be some existing PD tools for it, but I'm afraid I don't know what they are. I think that Docbook comes from the Davenport group stuff (but I might be wrong). You can check this page and see: http://www.ora.com/davenport/index.html Cost 2.0 is a much improved tool, but slumming it in TCL would probably turn your stomach. XML is a great language, but the tools are not there right now (though there are _2_ draft parsers in Java). You can parse XML with simple Perl scripts, and that in fact is how the current XML docs wend their way from XML->HTML and XML->RTF... But you'd probably be rolling your own. On the other hand having XML support in the Python web-browser would be an impressive thing, so maybe there's a volunteer out there to do the coding. >Do you have any bright ideas? Our concerns are: > > - Free [The language reference was just changed to FrameMaker and that > caused quite a ruckus, even though people just want to print it]. You can do decent SGML->Postscript with Frame, I think. That might be good for your output needs... Of course, if you're backing off from the frame decision, then this is not acceptable. > - Conversion to PostScript and HTML relatively easy and full-featured > Has to look good, of course. On of the harder things with SGML of any flavor, of course, as someone has to write the scripts or macros to _make_ it look good. > - Allow the creation of a Python-specific DTD (with markup of > syntactic elements for example). You can extend almost any DTD pretty easily. You probably want to still the big, document striucture parts, and then play around with specialized elements for code examples, and maybe the reference sections, where a lot of navigational help would be useful. > - HTML which does smart things with references to other parts of the > document (==HREF's). > Again, it comes down to the scripts you write to do the conversion.You could just munch on SP output like everyone else in the world does. I'd also happily give you my YASP/TCL interface, but someone would have to move it to Python (I assume), and it's not really documented... When you get things a bit more narrowed down I may be of more help. Don't forget Robin Cover's SGML pages -- it may take you a morning to read, but they are _very_ complete. >Cheers, > >--david _________________________________________ David Durand dgd@cs.bu.edu \ david@dynamicDiagrams.com Boston University Computer Science \ Sr. Analyst http://www.cs.bu.edu/students/grads/dgd/ \ Dynamic Diagrams --------------------------------------------\ http://dynamicDiagrams.com/ MAPA: mapping for the WWW \__________________________ _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From kryee@wheat.uwaterloo.ca Tue Feb 11 20:10:12 1997 From: kryee@wheat.uwaterloo.ca (Ka-Ping Yee) Date: Tue, 11 Feb 1997 15:10:12 -0500 Subject: [PYTHON DOC-SIG] SGML-Tools Message-ID: <9702112010.AA18318@wheat> Fred Drake wrote: > So how many of us have any knowledge or experience in DTD > development? Hm. Well, i hung around on the HTML working group list for quite a while and watched what was going on, and was thus interested enough to go find out more about how SGML works. That definitely does not make me a DTD expert, but i think i'd be able to put one together. Making one that will last is, of course, another issue. The proposed XML specification contains some examples and prose that show how to construct DTD fragments. Perhaps one of the advantages of working in SGML is that we can use the existing SGMLParser stuff, and define Python functions under that to process individual elements? Another alternative is to use James Clark's nsgmls parser and then examine the output from that, which is emitted in a straightforward list of commands, one per line. I think the LinuxDoc people use this approach. However, there is the issue of embedded documentation. I suspect that many people will not want to enter SGML when they are editing docstrings for classes or functions, yet still desire the power of a "real document" to write reference material, so that we'll have to decide on two basic source formats. Ping _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From fdrake@CNRI.Reston.Va.US Tue Feb 11 20:38:30 1997 From: fdrake@CNRI.Reston.Va.US (Fred L. Drake) Date: Tue, 11 Feb 1997 15:38:30 -0500 (EST) Subject: [PYTHON DOC-SIG] SGML-Tools In-Reply-To: <9702112010.AA18318@wheat> from "Ka-Ping Yee" at Feb 11, 97 03:10:12 pm Message-ID: <199702112038.PAA04934@weyr.CNRI.Reston.Va.US> Ka-Ping Yee wrote: > Hm. Well, i hung around on the HTML working group list for > quite a while and watched what was going on, and was thus > interested enough to go find out more about how SGML works. No, but you're right: it does help to be aware of what's going on, and *that* is still hard to come by. > Perhaps one of the advantages of working in SGML is that we > can use the existing SGMLParser stuff, and define Python My thought exactly; either SGML or XML should be easy to support if we don't do anything elaborate in the documents, but I would want to make it more general and robust. (Preferably by a lot....) Another possibility would be to write another SGMLParser implementation around nsgmls output; this keeps the document-type stuff similar to what we have now while allowing substantial SGML to be used as needed. I expect we'd at least want to support general entities in the internal declaration subset. That would allow: ]> Python! <abstract>This is about &python;! By the time you've read this, it will be yours too! </abstract> ... </pydoc> One (potential, at least) problem is that the SGMLParser stuff in Grail is *not* part of the Python standard library. It is part of Grail and might not be available. A re-implementation of the interface using nsgmls as a backend would not be difficult to write, but raises the entry fee. > Another alternative is to use James Clark's nsgmls parser > and then examine the output from that, which is emitted in > a straightforward list of commands, one per line. I think > the LinuxDoc people use this approach. They do. A huge number of SGML processes are built around exactly this; I'd really like to see this done using Python instead of Perl. > However, there is the issue of embedded documentation. I > suspect that many people will not want to enter SGML when > they are editing docstrings for classes or functions, yet > still desire the power of a "real document" to write > reference material, so that we'll have to decide on two Docstrings are separate. My inclination is to take one or more of the formats that have been proposed for docstring conventions and providing a parser that can load a source file and generate the corresponding SGML. This can be done as simply another implementation of the SGMLParser base class. (Yes, at some point I'll rip the parser and handler classes apart, but probably not for Grail 0.3.) -Fred -- Fred L. Drake, Jr. fdrake@cnri.reston.va.us Corporation for National Research Initiatives 1895 Preston White Drive Reston, VA 20191-5434 _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From kryee@wheat.uwaterloo.ca Tue Feb 11 21:23:49 1997 From: kryee@wheat.uwaterloo.ca (Ka-Ping Yee) Date: Tue, 11 Feb 1997 16:23:49 -0500 Subject: [PYTHON DOC-SIG] SGML-Tools Message-ID: <9702112123.AA01813@wheat> When you mentioned your desire to create a more general and robust implementation of SGMLParser, i thought, "It might be good to write the lexical analyzer in C for speed, or even the whole parser as a compiled module." Fred Drake wrote: > Another > possibility would be to write another SGMLParser implementation around > nsgmls output; this keeps the document-type stuff similar to what we > have now while allowing substantial SGML to be used as needed. That's kind of what i had in mind when i mentioned nsgmls output. But putting together these two ideas, why not a Python interface to sgmls itself? James Clark has an API for SP, and as far as i know the source code is freely available. Import that as a module, and you have a super-fast, robust, well-tested SGML parser to play with from your Python script. (The back-ends for various output formats could then be Python scripts.) Just a thought... Ping _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From fdrake@CNRI.Reston.Va.US Tue Feb 11 21:37:07 1997 From: fdrake@CNRI.Reston.Va.US (Fred L. Drake) Date: Tue, 11 Feb 1997 16:37:07 -0500 (EST) Subject: [PYTHON DOC-SIG] SGML-Tools In-Reply-To: <9702112123.AA01813@wheat> from "Ka-Ping Yee" at Feb 11, 97 04:23:49 pm Message-ID: <199702112137.QAA05431@weyr.CNRI.Reston.Va.US> Ka-Ping Yee wrote: > But putting together these two ideas, why not a Python interface > to sgmls itself? James Clark has an API for SP, and as far as i > know the source code is freely available. Import that as a module, > and you have a super-fast, robust, well-tested SGML parser to play > with from your Python script. (The back-ends for various output Yes, I've thought of this as well. I even have a C++ source file sitting at home where I started it once. The catch is more one of time availability; I really don't expect my employer to allocate any of my time for this (these messages are already taxing my time;( ), and a version working from nsgmls output would be a lot faster to write & debug, especially since my C++ is getting rusty. The faster version could be dropped in when it becomes available at a later point. Maybe I'll take another look at going ahead and writing one or the other. -Fred -- Fred L. Drake, Jr. fdrake@cnri.reston.va.us Corporation for National Research Initiatives 1895 Preston White Drive Reston, VA 20191-5434 _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From fdrake@CNRI.Reston.Va.US Tue Feb 11 21:39:22 1997 From: fdrake@CNRI.Reston.Va.US (Fred L. Drake) Date: Tue, 11 Feb 1997 16:39:22 -0500 (EST) Subject: [PYTHON DOC-SIG] Ooops! Message-ID: <199702112139.QAA05459@weyr.CNRI.Reston.Va.US> Before anyone responds to my last message, please check the "To:" and "Cc:" headers; it might have some extraneous junk on it! ;-( Sorry! -Fred -- Fred L. Drake, Jr. fdrake@cnri.reston.va.us Corporation for National Research Initiatives 1895 Preston White Drive Reston, VA 20191-5434 _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From Anthony Baxter <arb@connect.com.au> Tue Feb 11 23:19:32 1997 From: Anthony Baxter <arb@connect.com.au> (Anthony Baxter) Date: Wed, 12 Feb 1997 10:19:32 +1100 Subject: [PYTHON DOC-SIG] SGML-Tools In-Reply-To: Your message of "Tue, 11 Feb 1997 16:37:07 CDT." <199702112137.QAA05431@weyr.CNRI.Reston.Va.US> Message-ID: <199702112319.KAA14928@jambu.off.connect.com.au> What about SWIGing SP? That was my first thought - I haven't looked at doing it yet, tho. Anthony >>> "Fred L. Drake" wrote > Ka-Ping Yee wrote: > > But putting together these two ideas, why not a Python interface > > to sgmls itself? James Clark has an API for SP, and as far as i > > know the source code is freely available. Import that as a module, > > and you have a super-fast, robust, well-tested SGML parser to play > > with from your Python script. (The back-ends for various output > > Yes, I've thought of this as well. I even have a C++ source file > sitting at home where I started it once. The catch is more one of > time availability; I really don't expect my employer to allocate any > of my time for this (these messages are already taxing my time;( ), > and a version working from nsgmls output would be a lot faster to > write & debug, especially since my C++ is getting rusty. The faster > version could be dropped in when it becomes available at a later > point. > Maybe I'll take another look at going ahead and writing one or the > other. > > > -Fred > > -- > Fred L. Drake, Jr. > fdrake@cnri.reston.va.us > Corporation for National Research Initiatives > 1895 Preston White Drive > Reston, VA 20191-5434 > > _______________ > DOC-SIG - SIG for the Python Documentation Project > > send messages to: doc-sig@python.org > administrivia to: doc-sig-request@python.org > _______________ _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From MHammond@skippinet.com.au Thu Feb 13 02:41:55 1997 From: MHammond@skippinet.com.au (Mark Hammond) Date: Thu, 13 Feb 1997 12:41:55 +1000 Subject: [PYTHON DOC-SIG] Re: DTD's for Python (fwd) Message-ID: <199702130145.MAA15996@minotaur.labyrinth.net.au> > >we're once again considering what the right way to encode the Python > >documentation is, especially the library reference. Right now it's in > >pretty simple LaTeX, but we'd like to go to a real markup language, with > >all the advantages that represents. I admit to not following this too closely, not knowing many of the tools being discussed (or even what the TLA's stand for :-) But would it make sense to beef up gendoc? gendoc could parse the .py, and possibly other special purpose doco files. This would seem perfect for the library doco - you end up with a very nice tool built in Python, and also a whole lot more documentation that has the same "look and feel" as the .lib documentation. For reference documentation especially, I feel it important to keep it close to the sources. This may not be appropriate for the tutorial etc, but it seems we are missing a "general" opportunity to really further beef up _all_ (including future :-) Python documentation. Mark. ---------------------------------------------------------------------- Mark Hammond - MHammond@skippinet.com.au Check out Python - _the_ language for the Web/CGI/Windows/MFC/Unix/etc <http://www.python.org> & <http://www.python.org/ftp/python/pythonwin> _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From kryee@wheat.uwaterloo.ca Thu Feb 13 02:59:01 1997 From: kryee@wheat.uwaterloo.ca (Ka-Ping Yee) Date: Wed, 12 Feb 1997 21:59:01 -0500 Subject: [PYTHON DOC-SIG] Re: DTD's for Python (fwd) Message-ID: <9702130259.AA26176@wheat> > But would it make sense to beef up gendoc? gendoc could parse the > .py, and possibly other special purpose doco files. Perhaps. The problem is that we could end up with two separate sets of documentation -- one embedded in doc-strings, and the other in a sophisticated desktop publisher. Even if we manage to keep them in separate domains to avoid conflicting information, there'd still be no connection (what if someone wants to hyperlink from a doc-string to the reference manual?). The trick is to come up with something that is lightweight enough for people to casually enter as doc-strings, yet powerful enough to supply all the features a book author might want while writing a technical manual. Akin to setext and gendoc, its goal would be a format simple enough to read directly as text. I think this is quite possible, but creating a whole new documentation format may not make some people happy. Ping _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From Jim@digicool.com Thu Feb 13 11:50:48 1997 From: Jim@digicool.com (Jim Fulton) Date: Thu, 13 Feb 1997 06:50:48 -0500 Subject: [PYTHON DOC-SIG] Re: DTD's for Python (fwd) References: <199702130145.MAA15996@minotaur.labyrinth.net.au> Message-ID: <33030018.2818@DigiCool.com> Mark Hammond wrote: > > But would it make sense to beef up gendoc? Yes. > gendoc could parse the > .py, and possibly other special purpose doco files. > > This would seem perfect for the library doco - you end up with a very > nice tool built in Python, and also a whole lot more documentation > that has the same "look and feel" as the .lib documentation. > > For reference documentation especially, I feel it important to keep > it close to the sources. This may not be appropriate for the > tutorial etc, but it seems we are missing a "general" opportunity to > really further beef up _all_ (including future :-) Python documentation. I agree alot. I think library documentation should be generated from doc strings. This keeps the documentation in sync with the source and with on-line browsing tools. Documentation strings are also much simpler to write, as they are a simple form of structured text. I will probably never contribute any documentation if I have to write it in Tex, or some variant. As a side note, I don't think parsing the code should be necessary either. I thing it should be possible to import a module and discover all of the documentation from exported objects and their attributes. I've been very successful with this myself. I've been able to do this with extensions too, although it requires a richer extension model, like ExtensionClass or MESS. Jim _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From Jim@digicool.com Thu Feb 13 11:55:07 1997 From: Jim@digicool.com (Jim Fulton) Date: Thu, 13 Feb 1997 06:55:07 -0500 Subject: [PYTHON DOC-SIG] Re: DTD's for Python (fwd) References: <9702130259.AA26176@wheat> Message-ID: <3303011B.6D63@DigiCool.com> Ka-Ping Yee wrote: > > > But would it make sense to beef up gendoc? gendoc could parse the > > .py, and possibly other special purpose doco files. > > Perhaps. The problem is that we could end up with two separate > sets of documentation -- one embedded in doc-strings, and the > other in a sophisticated desktop publisher. Even if we manage > to keep them in separate domains to avoid conflicting information, > there'd still be no connection (what if someone wants to hyperlink > from a doc-string to the reference manual?). This is fairly easy to do, since gendoc has conventions for entering hyper links. > The trick is to come up with something that is lightweight enough > for people to casually enter as doc-strings, yet powerful enough > to supply all the features a book author might want while writing > a technical manual. Akin to setext Gendoc now uses my structured-text module (or some variant of it), which is like setext mut easier to enter and read. > and gendoc, its goal would be > a format simple enough to read directly as text. Yes. > I think this is > quite possible, but creating a whole new documentation format may > not make some people happy. But the format used by gendoc is extremely simple and natural. It requires very little skill, and is very readable in it's raw form, unlike variants of Tex. Jim _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From MHammond@skippinet.com.au Fri Feb 14 09:14:27 1997 From: MHammond@skippinet.com.au (Mark Hammond) Date: Fri, 14 Feb 1997 19:14:27 +1000 Subject: [PYTHON DOC-SIG] Observations about gendoc. Message-ID: <199702140816.TAA20431@minotaur.labyrinth.net.au> Im starting to look into some of those changes I mentioned before. On my way Ive noticed a few things... All comments appreciated. I'll take a lack of objections as implicit approval to hack these changes, and submit them back :-) * .htp files. Is Ken on this list? www.python.org wants .htp files, which a script then converts to html. Whats the best way to tackle this? Just setup a "template" to make it look like the finished .html, and skip the conversion process? * Exceptions - It looks like much of this code pre-dates a useful traceback module. Some handlers print sys.exc_type, sys.exc_value etc (syntax error handling comes to mind) - should these be upgraded to print the full traceback? * Private Methods - I would find it useful if there was a mode which says "use Private Methods, but only if they have a docstring. ie, the existance of a docstring dictates its private-ness. In fact, maybe a more general "only export is docstring'd" flag - regardless of the leading "_". Personally, I prefer the first option better... Thats all for today! Mark. ---------------------------------------------------------------------- Mark Hammond - MHammond@skippinet.com.au Check out Python - _the_ language for the Web/CGI/Windows/MFC/Unix/etc <http://www.python.org> & <http://www.python.org/ftp/python/pythonwin> _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From Robin.K.Friedrich@USAHQ.UnitedSpaceAlliance.com Fri Feb 14 13:57:19 1997 From: Robin.K.Friedrich@USAHQ.UnitedSpaceAlliance.com (Robin.K.Friedrich@USAHQ.UnitedSpaceAlliance.com) Date: Fri, 14 Feb 1997 07:57:19 -0600 Subject: [PYTHON DOC-SIG] Observations about gendoc. Message-ID: <00090B5C.1924@freedom.rsoc.rockwell.com> ______________________________ Reply Separator _________________________________ Subject: [PYTHON DOC-SIG] Observations about gendoc. Author: Mark Hammond <MHammond@skippinet.com.au> at INTERNET Date: 2/14/97 3:14 AM Reply: Robin Friedrich Im starting to look into some of those changes I mentioned before. On my way Ive noticed a few things... All comments appreciated. I'll take a lack of objections as implicit approval to hack these changes, and submit them back :-) * .htp files. Is Ken on this list? www.python.org wants .htp files, which a script then converts to html. Whats the best way to tackle this? Just setup a "template" to make it look like the finished .html, and skip the conversion process? I'm not sure .htp file format is important enough to provide a separate plugin. The things gendoc is used for is not likely to wind up as integrated python.org pages. It would be easier to provide an HTMLgen resource class that matches the python.org style. * Exceptions - It looks like much of this code pre-dates a useful traceback module. Some handlers print sys.exc_type, sys.exc_value etc (syntax error handling comes to mind) - should these be upgraded to print the full traceback? * Private Methods - I would find it useful if there was a mode which says "use Private Methods, but only if they have a docstring. ie, the existance of a docstring dictates its private-ness. In fact, maybe a more general "only export is docstring'd" flag - regardless of the leading "_". Personally, I prefer the first option better... Good one. I like the first option as well. Although what we do is run gendoc for two purposes -- one is user docs, but the other is detailed docs that we slap into our DDS (detailed design specifications). We thus need to retain the current capability as well. Thats all for today! Is that today or yesterday, and if so what are you doing tomorrow... oh forget it. -Robin Mark. _______________ _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From MHammond@skippinet.com.au Sun Feb 16 11:40:29 1997 From: MHammond@skippinet.com.au (Mark Hammond) Date: Sun, 16 Feb 1997 21:40:29 +1000 Subject: [PYTHON DOC-SIG] Observations about gendoc. Message-ID: <199702161043.VAA29956@minotaur.labyrinth.net.au> > Thats all for today! > Is that today or yesterday, and if so what are you doing > tomorrow... oh forget it. Hey - its tomorrow today! And today, Im hacking even more relentlessly... Ive decided my previous "ni" hacks are inappropriate. My strategy now is: * In gendoc.py, wrote a new collector called "ni_collect()". This does a file system search of sub-modules, and imports them all! (honouring the skiplist, etc) * doc_collect has a new collector called "PackageCollector" - currently sub-classes from ModuleCollector, but should probably be rolled into it. * Changed some of the generate stuff to be recursive. Thus, the list of manpages is now a list of [manpage|list of manpages], etc. All this leads to a nice heriarchical index of the entire package. So my questions: * Does this sound reasonable? The recursive changes mean that it still works as before. This _seems_ the correct design for ni, which is recursive by nature. This could possibly be put to good use elsewhere. * Re the index. How should I generate it? With no frame, an indented list seems right. But if I have frames, an indented list will be too "wide". Best thing that comes to mind is some sort of nested set of index pages or something...Maybe dont use an actual HTML list (eg, heading levels) , to keep the width down. How about generating for an MSIE tree control :-):-) Any advice on this? Mark. ---------------------------------------------------------------------- Mark Hammond - MHammond@skippinet.com.au Check out Python - _the_ language for the Web/CGI/Windows/MFC/Unix/etc <http://www.python.org> & <http://www.python.org/ftp/python/pythonwin> _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From dlarsson@sw.seisy.abb.se Sun Feb 16 11:07:21 1997 From: dlarsson@sw.seisy.abb.se (Daniel Larsson) Date: Sun, 16 Feb 1997 12:07:21 +0100 Subject: [PYTHON DOC-SIG] Observations about gendoc. References: <199702161043.VAA29956@minotaur.labyrinth.net.au> Message-ID: <3306EA69.4095@sw.seisy.abb.se> ------------6BE469A627D94 Content-Transfer-Encoding: 7bit Content-Type: text/plain; charset=us-ascii Mark Hammond wrote: > ... > All this leads to a nice heriarchical index of the entire package. > > So my questions: > * Does this sound reasonable? The recursive changes mean that it > still works as before. This _seems_ the correct design for ni, which > is recursive by nature. This could possibly be put to good use > elsewhere. Yes, I think it sounds good. This is more or less the idea I had for supporting ni. > * Re the index. How should I generate it? With no frame, an > indented list seems right. But if I have frames, an indented list > will be too "wide". Best thing that comes to mind is some sort of > nested set of index pages or something...Maybe dont use an actual > HTML list (eg, heading levels) , to keep the width down. How about > generating for an MSIE tree control :-):-) > Any advice on this? I would vote for nested indices. This would at least solve the nested list problem. -- Daniel ------------6BE469A627D94 Content-Transfer-Encoding: 7bit Content-Type: text/html; charset=us-ascii <HTML><BODY> <DT>Mark Hammond wrote:<BR> > ...<BR> > All this leads to a nice heriarchical index of the entire package.<BR> > <BR> > So my questions:<BR> > * Does this sound reasonable?  The recursive changes mean that it<BR> > still works as before.  This _seems_ the correct design for ni, which<BR> > is recursive by nature.  This could possibly be put to good use<BR> > elsewhere.<BR> <BR></DT> <DT>Yes, I think it sounds good. This is more or less the idea I had for supporting</DT> <DT>ni.</DT> <DT><BR> > * Re the index.  How should I generate it?  With no frame, an<BR> > indented list seems right.  But if I have frames, an indented list<BR> > will be too "wide".  Best thing that comes to mind is some sort of<BR> > nested set of index pages or something...Maybe dont use an actual<BR> > HTML list (eg, heading levels) , to keep the width down.  How about<BR> > generating for an MSIE tree control :-):-)<BR> > Any advice on this?<BR> <BR></DT> <DT>I would vote for nested indices. This would at least solve the nested list</DT> <DT>problem.</DT> <DT><BR> -- Daniel</DT> </BODY> </HTML> ------------6BE469A627D94-- _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From MHammond@skippinet.com.au Tue Feb 18 11:42:03 1997 From: MHammond@skippinet.com.au (Mark Hammond) Date: Tue, 18 Feb 1997 21:42:03 +1000 Subject: [PYTHON DOC-SIG] Templatising gendoc, and more. Message-ID: <199702181046.VAA06003@minotaur.labyrinth.net.au> Couple of quick questions - how can a ni package provide doc strings? Eg, a package named "xyz" is a directory, _not_ a file. I added a convention to gendoc that a file called "__doc__" in a packages directory will be read, and treated as docstrings for the module itself (which makes lots of sense to me, as then you dont need to distribute it) Also, I "flatten" the "__init__" module, so that all docstrings and methods are documented in the package itself - ie, __init__ never gets a mention in the docs. Do these sound OK? Secondly - by default, there are a few places it is assumed the file name of the generated file is the same as the object itself. Thus, the module "a.b" is created as "a.b.html". Is it worth making a change to that it is created as "a_b.html"? Up until recently, even Python could not correctly parse the extension from a.b.html, so Im inclined to think it is. 2 ways to tackle this - unconditionally replace "." with "_" in object names, or allow the classes to have the concept of _2_ names - the objects name, and the generated file name. The latter is more general, but touches more code... Now, the main one. This may sound a little wierd and hard, but here goes anyway... Something I didnt really like about gendoc was the way it enforced a "synopsis"/"description"/"See also" type format on your documentation. As I read about the StructuredText module that Jim did, what I really expected what that _my_ structure would be used for the documentation. Eg, what I expected to be able to write was: """Some Module: Description This is the desc Known Bugs Lots and lots See Also Some extra stuff Synopsis At the bottom! :-) """ and I expected that my "See Also" stuff would automatically go into the "See Also" section on the Web page, and that a top-level "Known Bugs" section would appear in the HTML - it doesnt :-( I have a few ideas on how you could do this. My idea is basically to have 2 modes - a "template" mode, and a "freeform" mode. The (default?) "template" mode is much like now, but would use a text file of "known" section names. Eg, the "default" template, which would generate doc identical to now would be like: Synopsis|<H2>%s</H2>|<P> Description See Also [The stuff after the | could be optional, and defines how the heading itself it rendered, and also how para in the body is pre/a-pended. Thats off the top of my head - consider the concept, not my impl idea :-) And someone else could change it if required for their documentation needs. Free-form mode would still use "known" section names, but would use the top-level structure of the structured doc-string to determine the order and inclusion of sections. Eg, in the example above, the "generated" see also entries (as now) would be appended/prepended to the "explicit" see also entries (which the module author specifies as relevant, but gendoc didnt), and no "synopsis" section at all would be generated (which may make sense for sample modules, for example, where an implication of importing the sample code is not correct) Any comments on this? Mark. ---------------------------------------------------------------------- Mark Hammond - MHammond@skippinet.com.au Check out Python - _the_ language for the Web/CGI/Windows/MFC/Unix/etc <http://www.python.org> & <http://www.python.org/ftp/python/pythonwin> _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From MHammond@skippinet.com.au Wed Feb 19 23:18:04 1997 From: MHammond@skippinet.com.au (Mark Hammond) Date: Thu, 20 Feb 1997 09:18:04 +1000 Subject: [PYTHON DOC-SIG] Hacking relentlessly :-) Message-ID: <199702192221.JAA15359@minotaur.labyrinth.net.au> Ive added cross-references in the text. I dont know what syntax to use. My current hacks allow docstrings such as: "See also @a.b.c@", and "a.b.c" will be translated into a hyperlink if such an object has been collected in this run, else into Bold. What syntax should I use for this? I thought of a regex that dectected _any_ "a.b.c", but in some cases, the link will be a single word - ie, no "." sep'd. Also, I noticed that manpage.py did _not_ process markups or internal hyperlinks for list definitions, etc - only paragraphs. Is there a reason for this? Having markups and links in definition lists seems pretty logical to me... Mark. ---------------------------------------------------------------------- Mark Hammond - MHammond@skippinet.com.au Check out Python - _the_ language for the Web/CGI/Windows/MFC/Unix/etc <http://www.python.org> & <http://www.python.org/ftp/python/pythonwin> _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From dlarsson@sw.seisy.abb.se Wed Feb 19 23:03:28 1997 From: dlarsson@sw.seisy.abb.se (Daniel Larsson) Date: Thu, 20 Feb 1997 00:03:28 +0100 Subject: [PYTHON DOC-SIG] Hacking relentlessly :-) Message-ID: <330B86C0.6AF2@sw.seisy.abb.se> ------------39545E9334D49 Content-Transfer-Encoding: 7bit Content-Type: text/plain; charset=us-ascii Mark Hammond wrote: > > Ive added cross-references in the text. I dont know what syntax to > use. My current hacks allow docstrings such as: > "See also @a.b.c@", and "a.b.c" will be translated into a hyperlink > if such an object has been collected in this run, else into Bold. > > What syntax should I use for this? I thought of a regex that > dectected _any_ "a.b.c", but in some cases, the link will be a single > word - ie, no "." sep'd. Originally, I had a syntax for doing this, but I removed it. I always made the link, however, regardless of whether the source was collected or not. Why did you decide to skip the link if it wasn't collected? Presumably to avoid having dead links, but that also means you have to "collect" possibly a lot of files in one run. > Also, I noticed that manpage.py did _not_ process markups or internal > hyperlinks for list definitions, etc - only paragraphs. Is there a > reason for this? Having markups and links in definition lists seems > pretty logical to me... Ooops, yes of course that's logical. Stupid darn mistake of mine. While on the gendoc thread: I usually run gendoc on everything in the standard distribution to put up docs for people in my department. I thought of adding an option to "collect" every module (and package) along the sys.path. Comments? -- Daniel Larsson, ABB Industrial Systems AB ------------39545E9334D49 Content-Transfer-Encoding: 7bit Content-Type: text/html; charset=us-ascii <HTML><BODY> <DT>Mark Hammond wrote:</DT> <DT>></DT> <DT> > Ive added cross-references in the text.  I dont know what syntax to</DT> <DT>> use.  My current hacks allow docstrings such as:</DT> <DT>> "See also @a.b.c@", and "a.b.c" will be translated into a hyperlink</DT> <DT>> if such an object has been collected in this run, else into Bold.</DT> <DT>></DT> <DT>> What syntax should I use for this?  I thought of a regex that</DT> <DT>> dectected _any_ "a.b.c", but in some cases, the link will be a single</DT> <DT>> word - ie, no "." sep'd.</DT> <DT> </DT> <DT>Originally, I had a syntax for doing this, but I removed it. I always made  the link, however, regardless of whether the source was collected or not.  Why did you decide to skip the link if it wasn't collected? Presumably to  avoid having dead links, but that also means you have to "collect" possibly  a lot of files in one run. </DT> <DT> </DT> <DT>> Also, I noticed that manpage.py did _not_ process markups or internal</DT> <DT>> hyperlinks for list definitions, etc - only paragraphs.  Is there a</DT> <DT>> reason for this?  Having markups and links in definition lists seems</DT> <DT>> pretty logical to me...</DT> <DT> </DT> <DT>Ooops, yes of course that's logical. Stupid darn mistake of mine.</DT> <DT> </DT> <DT>While on the gendoc thread: I usually run gendoc on everything in the standard distribution to put up docs for people in my department. I thought of adding  an option to "collect" every module (and package) along the sys.path. Comments?</DT> <DT> </DT> <DT>--  Daniel Larsson, ABB Industrial Systems AB</DT> </BODY> </HTML> ------------39545E9334D49-- _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From dlarsson@sw.seisy.abb.se Wed Feb 19 23:10:33 1997 From: dlarsson@sw.seisy.abb.se (Daniel Larsson) Date: Thu, 20 Feb 1997 00:10:33 +0100 Subject: [PYTHON DOC-SIG] Hacking relentlessly :-) References: <199702192254.JAA17094@minotaur.labyrinth.net.au> Message-ID: <330B8869.1686@sw.seisy.abb.se> ------------2B107203164210 Content-Transfer-Encoding: 7bit Content-Type: text/plain; charset=us-ascii Mark Hammond wrote: > > [You dropped the SIG - was that intentional?] Nope! I resent my message to the group. > > > Why did you decide to skip the link if it wasn't collected? Presumably > > to > > avoid having dead links, but that also means you have to "collect" > > possibly > > a lot of files in one run. > > Yup - this was the idea. These links are "internal" by definition. > If they cant be found in the current build, they wont be found later > :-) Ok. I sometimes used links to standard classes, but then gendoc assumed the resulting HTML files would reside in the same directory. > Note that _no_ URL is entered. The whole point of these markups is > for the generater to _deduce_ the URL name, based on the object name. Yes, I understand that. That's what I did as well. > IMHO, it should be possible to create a single package with gendoc > that has _zero_ bad links. This currently is pretty hard :-) Hmm, true. I insert all kinds of links, such as when you import modules, inherit from classes, etc. Maybe add YAO (yet another option) to avoid generating links to things we're not sure are there (or perhaps the other way around, an option to generate links regardless if they are seen during this collect). > > While on the gendoc thread: I usually run gendoc on everything in the > > standard distribution to put up docs for people in my department. I > > thought of adding > > an option to "collect" every module (and package) along the sys.path. > > Comments? > > Makes sense to me. This is what I do for ni(), so I suppose it is > pretty similar. > > I also added a "-s" option to gendoc, so the skiplist can be added > to. > -- Daniel Larsson, ABB Industrial Systems AB ------------2B107203164210 Content-Transfer-Encoding: 7bit Content-Type: text/html; charset=us-ascii <HTML><BODY> <DT>Mark Hammond wrote:<BR> > <BR> > [You dropped the SIG - was that intentional?]</DT> <DT> </DT> <DT>Nope! I resent my message to the group.</DT> <DT><BR> > <BR> > > Why did you decide to skip the link if it wasn't collected? Presumably<BR> > > to<BR> > > avoid having dead links, but that also means you have to "collect"<BR> > > possibly<BR> > > a lot of files in one run.<BR> > <BR> > Yup - this was the idea.  These links are "internal" by definition.<BR> > If they cant be found in the current build, they wont be found later<BR> > :-)<BR> <BR></DT> <DT>Ok. I sometimes used links to standard classes, but then gendoc assumed the</DT> <DT>resulting HTML files would reside in the same directory.</DT> <DT><BR> > Note that _no_ URL is entered.  The whole point of these markups is<BR> > for the generater to _deduce_ the URL name, based on the object name.<BR> <BR></DT> <DT>Yes, I understand that. That's what I did as well.</DT> <DT><BR> > IMHO, it should be possible to create a single package with gendoc<BR> > that has _zero_ bad links.  This currently is pretty hard :-)<BR> <BR></DT> <DT>Hmm, true. I insert all kinds of links, such as when you import modules, inherit from classes, etc. Maybe add YAO (yet another option) to avoid generating</DT> <DT>links to things we're not sure are there (or perhaps the other way around, an option to generate links regardless if they are seen during this collect).</DT> <DT><BR> > > While on the gendoc thread: I usually run gendoc on everything in the<BR> > > standard distribution to put up docs for people in my department. I<BR> > > thought of adding<BR> > > an option to "collect" every module (and package) along the sys.path.<BR> > > Comments?<BR> > <BR> > Makes sense to me.  This is what I do for ni(), so I suppose it is<BR> > pretty similar.<BR> > <BR> > I also added a "-s" option to gendoc, so the skiplist can be added<BR> > to.<BR> > <BR> <BR> -- <BR> Daniel Larsson, ABB Industrial Systems AB<BR>  </DT> </BODY> </HTML> ------------2B107203164210-- _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From MHammond@skippinet.com.au Thu Feb 27 14:25:22 1997 From: MHammond@skippinet.com.au (Mark Hammond) Date: Fri, 28 Feb 1997 00:25:22 +1000 Subject: [PYTHON DOC-SIG] New ni style example. Message-ID: <199702271329.AAA06429@minotaur.labyrinth.net.au> All the hacks I have done have resulted in documentation for the win32com module. Ive uploaded the html, for anyone to peruse if they are interested. Key things to note: * Entire manual generated by telling gendoc to document the "win32com" package, and specifying some "skip-modules". All sub-modules were found and documented automaticaly. * Index is still ugly, no frames, and too wide * References can appear in the body text. * More module names are written as links, rather than text. * Added the "one-liner" to a few more places. Please let me know what you think... http://www.labyrinth.net.au/~mhammond/win32com/ Mark. ---------------------------------------------------------------------- Mark Hammond - MHammond@skippinet.com.au Check out Python - _the_ language for the Web/CGI/Windows/MFC/Unix/etc <http://www.python.org> & <http://www.python.org/ftp/python/pythonwin> _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From x-aes@telelogic.se Thu Feb 27 14:35:01 1997 From: x-aes@telelogic.se (Andy Eskilsson) Date: 27 Feb 1997 15:35:01 +0100 Subject: [PYTHON DOC-SIG] New ni style example. In-Reply-To: Mark Hammond's message of Thu, 27 Feb 1997 15:25:22 +0100 References: <199702271329.AAA06429@minotaur.labyrinth.net.au> Message-ID: <ks4teys4fe.fsf@telelogic.se> / Mark Hammond <MHammond@skippinet.com.au> wrote: | | Please let me know what you think... | | http://www.labyrinth.net.au/~mhammond/win32com/ | |<()()|_N|=SS :-) Looks quite good.. but.. it would be nice to have some kind of folding mechanism *SLAP* oh yeah this is html.. (humm maybe some coffe would do fine, java or javascript that can fold/unfold lists?) Ahh well... IMHO The indentation is far too wide.. /Andy _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From MHammond@skippinet.com.au Fri Feb 28 05:12:29 1997 From: MHammond@skippinet.com.au (Mark Hammond) Date: Fri, 28 Feb 1997 15:12:29 +1000 Subject: [PYTHON DOC-SIG] New ni style example. Message-ID: <199702280416.PAA16973@minotaur.labyrinth.net.au> > |<()()|_N|=SS :-) Looks quite good.. but.. it would be nice to have > some kind of folding mechanism *SLAP* oh yeah this is html.. (humm > maybe some coffe would do fine, java or javascript that can fold/unfold > lists?) Well, Im more likely to generate Python ActiveX Scripting code - only Explorer, tho, but I dont care :-) [Then I could even display the HTML in Pythonwin, too :-] Mark. ---------------------------------------------------------------------- Mark Hammond - MHammond@skippinet.com.au Check out Python - _the_ language for the Web/CGI/Windows/MFC/Unix/etc <http://www.python.org> & <http://www.python.org/ftp/python/pythonwin> _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From MHammond@skippinet.com.au Fri Feb 28 23:56:19 1997 From: MHammond@skippinet.com.au (Mark Hammond) Date: Sat, 1 Mar 1997 09:56:19 +1000 Subject: [PYTHON DOC-SIG] New ni style example. Message-ID: <199702282300.KAA10365@minotaur.labyrinth.net.au> > Ahh well... IMHO The indentation is far too wide.. Im glad we all agree here. In this particular case, one obvious problem is that _all_ objects are shown in the index. IMO, it would be vastly improved if only modules and sub-modules were included in the index. Unfortunately, the index generater has long ago lost what the original objects are - it only has the man-pages and filenames. This would be a reasonable change, to have the index generator work from the collectors too. And another Microsoft-centric rant, which I'd like to pass by you all. Microsoft is moving its entire help system to HTML!!! It is doing this in 2 ways: * By adding special keyword and indexing tags to the HTML standard, and submitting them for approval. Apparently, the relevant body modified it, renamed it, and ratified it. * By designing yet another something-or-other which allows many HTML files to be concatenated into some sort of container, including I think compression. They will then submit this to whoever does this stuff. The special tags for indexing and keywords are something I would find particularly useful - (even necessary) - the C based .HLP generator I have still produces far far superior documentation than HTMLgen - and largely for these reasons. Is anyone else interested in this? I definately wont find the time to look at this on my own, and Id really like to get gendoc where it makes really really good documentation - I fear my new optimism for all this stuff will wane... Mark. ---------------------------------------------------------------------- Mark Hammond - MHammond@skippinet.com.au Check out Python - _the_ language for the Web/CGI/Windows/MFC/Unix/etc <http://www.python.org> & <http://www.python.org/ftp/python/pythonwin> _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________