From tratt@dcs.kcl.ac.uk Sat Sep 5 11:56:34 1998 From: tratt@dcs.kcl.ac.uk (Laurence Tratt) Date: Sat, 05 Sep 1998 11:56:34 +0100 Subject: [Doc-SIG] SGML Python docs Message-ID: <4c22c78048%tratt@dcs.kcl.ac.uk> A while ago (around Easter time), it was said that the Python documentation (manual reference, etc) would at some point be converted to SGML. The current LaTeX is, frankly, rather useless compared to say the Perl POD stuff if one wants to produce anything other than paper output or LaTeX2HTML HTML (which results in a rather clumsy in the Python manual context in my opinion, although that's not really the point), so this seemed like a very good idea. I would welcome the change to SGML as it would allow various people to generate the documentation in a more suitable format for their needs (be it a non-HTML format, or just to customise it for their own personal preferences). Around the same time, I posted a version of the manuals in a new HTML format using a quick PythonManualLaTeX -> x converter (where there were two 'x's: one was HTML, the other was StrongHelp which is a help system on my platform. Imagine the winhelp thing, without the speed losses, bugs, and with a touch more power (not a great deal) then you've got StrongHelp) I put together. The "parser" (so to speak) was a fairly hideous hack, which was rather reliant on the LaTeX format staying the same: needless to say, it changed quite substantially about 2 weeks afterwards :) I had a quick look at it the other day, and it's not going to work on the new LaTeX without a rewrite of the base converter (not surprising, given the time I had to do the thing). I suggested at the time that something along the lines of what I had written could be used as an SGML converter, as I don't know of there being any "general" software out there which would generate suitable SGML (ie with all the information about modules/methods still present). So I was wondering if any progress has been made with converting the LaTeX source to SGML, which would be the "manual source" of the future, so to speak? Is it now tied in with the SGMLTools stuff posted on this sig a couple of weeks back? Is it paused/stopped/waiting for extra help? Have I been stupid, and it's on www.python.org already? :) Basically, I would imagine I'm not the only person who's keen to see the SGML documentation at some point, so if anyone could let me - and presumably some other people on this sig who are also interested - know what the expected time schedule is, I would be grateful. Laurie From cg@pobox.com Sat Sep 5 12:17:01 1998 From: cg@pobox.com (Cees de Groot) Date: Sat, 05 Sep 1998 13:17:01 +0200 Subject: [Doc-SIG] SGML Python docs In-Reply-To: Your message of "Sat, 05 Sep 1998 11:56:34 BST." <4c22c78048%tratt@dcs.kcl.ac.uk> Message-ID: <199809051117.NAA13732@bofh.cdg.acriter.nl> tratt@dcs.kcl.ac.uk said: > Is it now tied in with the SGMLTools stuff posted on this sig a couple > of weeks back? No, and I don't think it belongs there for two reasons: first, I think that generating DocBook (which SGMLtools targets) is overkill; people shouldn't be forced to have to install Jade et al just to get usable documentation; and second, like POD, a Python doc generator should be part of the base Python distribution so that people will actually start using it. As I'm talking anyway, here's my two cents of ideas (I shouldn't really be doing this, because I've been here too short and I haven't had the time to check the archives nor the code that's relevant...): I'd favour XML generation with a simple XML DTD (containing element definitions for boldface, italic, code, ordered and unordered list, basically HTML--). Include with Python a simple XML backend that can generate HTML, manpage source, ASCII and DocBook SGML - the latter one can then be used for the heavier stuff, like collecting documentation of numerous modules into one volume (eg., generate the library reference from the .py modules plus some SGML glue). Regards Cees -- Cees de Groot http://pobox.com/~cg http://www.sgmltools.org --- We're hiring Java developers => www.acriter.com From skaller@maxtal.com.au Mon Sep 7 02:12:30 1998 From: skaller@maxtal.com.au (John Skaller) Date: Mon, 07 Sep 1998 11:12:30 +1000 Subject: [Doc-SIG] SGML Python docs Message-ID: <1.5.4.32.19980907011230.00effae4@triode.net.au> At 11:56 5/09/98 +0100, Laurence Tratt wrote: >A while ago (around Easter time), it was said that the Python documentation >(manual reference, etc) would at some point be converted to SGML. > >Around the same time, I posted a version of the manuals in a new HTML >format using a quick PythonManualLaTeX -> x converter >So I was wondering if any progress has been made with converting the LaTeX >source to SGML, which would be the "manual source" of the future, so to >speak? Well, it is possible I think with the new Latex format, which is clean and comparatively well formalised, to produce a parser filter for Interscript which will generate any of the interscript supported formats, including Latex and HTML. This could also generate 'pure SGML' or 'XML' if a suitable weaver were constructed. Interscript can already parse SGML and map it to interscript functions and thence to any format for which there is a weaver, including Latex and HTML. >Basically, I would imagine I'm not the only person who's keen to see the >SGML documentation at some point, so if anyone could let me - and >presumably some other people on this sig who are also interested - know >what the expected time schedule is, I would be grateful. You will first have to get Guido and others to give up their pet formats -- be it Latex or Frame maker. Or you could consider the alternative -- to literate program the whole of Python using interscript, which would serve to guarrantee at least that _all_ the code was documented, even if only by stubs 'yet to be documented'. An XML weaver is on my 'todo' list. I've also been considering a Latex input filter for some time, precisely for the purpose of mapping the Python Latex documentation. [I'm also gradually absorbing python modules into interscript, because I need non-python programmers to be able to use Python quickly to program interscript, and hence I need the 'standard' modules documented adequately. This will take some time, and doesn't solve the problem for Python programmers.] ------------------------------------------------------- John Skaller email: skaller@maxtal.com.au http://www.maxtal.com.au/~skaller phone: 61-2-96600850 snail: 10/1 Toxteth Rd, Glebe NSW 2037, Australia From Fred L. Drake, Jr." References: <4c22c78048%tratt@dcs.kcl.ac.uk> Message-ID: <13813.39671.3295.188971@weyr.cnri.reston.va.us> Laurence Tratt writes: > A while ago (around Easter time), it was said that the Python documentation > (manual reference, etc) would at some point be converted to SGML. The > current LaTeX is, frankly, rather useless compared to say the Perl POD > stuff if one wants to produce anything other than paper output or > LaTeX2HTML HTML (which results in a rather clumsy in the Python manual This is still planned. The preliminary conversion script I'd been working on has been massively broken due to the changes in the LaTeX markup, and I think the breakage is permanent: at this point, I'm more likely to start a conversion script from scratch than try to revive the old one yet again. On the other hand, the LaTeX markup has become much more logical, which reduces the immediacy of the need for a conversion. While I still think SGML/XML will be the final form of the documentation, I don't see a compelling need for a conversion at this time. No matter how we do things, there is no trivial conversion of the documentation and related tools that gives us any benefits over the current situation that I'm aware of; feel free to enlighten me on this one. > So I was wondering if any progress has been made with converting the LaTeX > source to SGML, which would be the "manual source" of the future, so to Like I said, I had a script that did a substantial portion of the conversion from the documentation of almost a year ago to a simple DTD, but it's pretty been relegated to the great bit bucket in the sky. There is no relation of the recent SGML-Tools conversation and the Python documentation, though I'd definately be interested in using SGML-Tools 1.1+ (DocBook & DSSSL) if we use the DocBook DTD. > Basically, I would imagine I'm not the only person who's keen to see the > SGML documentation at some point, so if anyone could let me - and You're not the only one. I'm just way to busy to devote any additional time myself at this point. If anyone is interested in converting the documentation to DocBook 3.x or DocBook-XML 1.0, I'd like to see a "conversion plan" which explains how you intend to map the LaTeX markup to *ML markup. I'd also be very interested in seeing alternate DTDs that are targeted more tightly for these sorts of documents, possibly specific to this particular documentation set. I am very concerned about actually authoring in DocBook. -Fred -- Fred L. Drake, Jr. Corporation for National Research Initiatives 1895 Preston White Dr. Reston, VA 20191 From Fred L. Drake, Jr." References: <4c22c78048%tratt@dcs.kcl.ac.uk> <199809051117.NAA13732@bofh.cdg.acriter.nl> Message-ID: <13813.39894.376291.475807@weyr.cnri.reston.va.us> Cees de Groot writes: > check the archives nor the code that's relevant...): I'd favour XML generation > with a simple XML DTD (containing element definitions for boldface, italic, > code, ordered and unordered list, basically HTML--). Include with Python a Combining the "book" style documents with docstring-based documentation is probably a non-starter; I'm not at all convinced that it would be any more useful than the current situation. Good docstrings and good reference documentation are not necessarily related. Docstrings should remain a very simple, text-only format, whereas I expect much more from the book-style manuals. -Fred -- Fred L. Drake, Jr. Corporation for National Research Initiatives 1895 Preston White Dr. Reston, VA 20191 From Fred L. Drake, Jr." References: <1.5.4.32.19980907011230.00effae4@triode.net.au> Message-ID: <13813.40244.821275.420987@weyr.cnri.reston.va.us> John Skaller writes: > Well, it is possible I think with the new Latex format, > which is clean and comparatively well formalised, to produce Thanks! There are still a few rough edges, but things are improving, especially if you look at the latest stuff in the CVS archive. > You will first have to get Guido and others to give up their > pet formats -- be it Latex or Frame maker. FrameMaker is no longer used, so we only have to worry about one legacy format, LaTeX. I don't think this is a "pet format" issue; there are advantages to SGML/XML conversion, once there's a specific DTD and the SGML v. XML decision is made (it's not at all clear which to use). There are also advantages to *not* performing a conversion, primarily that the time saved can be used to actually improve the content of the documentation. -Fred -- Fred L. Drake, Jr. Corporation for National Research Initiatives 1895 Preston White Dr. Reston, VA 20191 From richardf@redbox.net Wed Sep 9 09:45:38 1998 From: richardf@redbox.net (Richard Folwell) Date: Wed, 9 Sep 1998 09:45:38 +0100 Subject: [Doc-SIG] SGML Python docs Message-ID: <01BDDBD6.9AEA1BC0.richardf@redbox.net> On Tuesday, September 08, 1998 10:01 PM, Fred L. Drake [SMTP:fdrake@cnri.reston.va.us] wrote: > to this particular documentation set. I am very concerned about > actually authoring in DocBook. What are your concerns here? Richard --------------------------------------------- Richard Folwell RedBox Technologies, Email: richardf@redbox.net http://www.redbox.net Voice: +44 181 585 8565 Fax: +44 181 585 8665 From tratt@dcs.kcl.ac.uk Wed Sep 9 14:18:31 1998 From: tratt@dcs.kcl.ac.uk (Laurence Tratt) Date: Wed, 09 Sep 1998 14:18:31 +0100 Subject: [Doc-SIG] SGML Python docs In-Reply-To: <13813.39671.3295.188971@weyr.cnri.reston.va.us> Message-ID: <4e79e38248%tratt@dcs.kcl.ac.uk> In message <13813.39671.3295.188971@weyr.cnri.reston.va.us> "Fred L. Drake" wrote: >> A while ago (around Easter time), it was said that the Python documentation >> (manual reference, etc) would at some point be converted to SGML. > This is still planned. The preliminary conversion script I'd been > working on has been massively broken due to the changes in the LaTeX > markup, and I think the breakage is permanent: at this point, I'm > more likely to start a conversion script from scratch than try to > revive the old one yet again. This is basically what happened to my LaTeX -> x converter... > On the other hand, the LaTeX markup has become much more logical, > which reduces the immediacy of the need for a conversion. While I > still think SGML/XML will be the final form of the documentation, I > don't see a compelling need for a conversion at this time. No matter > how we do things, there is no trivial conversion of the documentation > and related tools that gives us any benefits over the current > situation that I'm aware of; feel free to enlighten me on this one. My personal opinion is that the format that the documentation is written in is irrelevant: whatever is decided upon needs to have a converter written for it which can then be used to convert into varying types of documentation. My only problem with LaTeX is that it's pretty hard to write a reliable parser for, and that at the push of a button any program which relies on parts of the markup staying roughly the same dies horribly. If there could be a guarantee that the LaTeX markup wasn't going to change then I think it would be OK to use the LaTeX as the base converter. However - from experience - the temptation with LaTeX is always to have a quick fiddle to tidy things up, and that breaks things very easily :) > I'd also be very interested in seeing alternate DTDs that are > targeted more tightly for these sorts of documents, possibly specific > to this particular documentation set. I would imagine this is the only way to reliably retain all the information that the LaTeX now holds (eg about when "string" is a module, and when it's an attribute in an RE object). I don't believe in reinventing the wheel when it's not necessary, but I would imagine we would be trying to mangle two different wheels together if we used a non-specific DTD. Laurie From Fred L. Drake, Jr." References: <01BDDBD6.9AEA1BC0.richardf@redbox.net> Message-ID: <13814.36893.111247.43425@weyr.cnri.reston.va.us> On Tuesday, September 08, 1998 10:01 PM, Fred L. Drake wrote: > to this particular documentation set. I am very concerned about > actually authoring in DocBook. Richard Folwell writes: > What are your concerns here? Richard, My primary concern here is in the volume of the DTD and some of the intricacies of things like indexing. The current LaTeX markup is fairly friendly to someone working on the index, making it reasonably easy to insert new entries. This includes things which should be visible at multiple points in the index, using \indexii, \indexiii, \indexiv. When I was working on the conversion script, I looked at the index-generating elements from DocBook at found them very verbose. Perhaps some form of tag omission or the use of empty tags (SGML only, not XML) can make it tolerable; I'd have to take another look at it to remember the specifics. I think it is very important to make authoring fairly comfortable. We may be able to use a DocBook variant for authoring, with more allowable tag omission, but I don't want to require a conversion stage or expensive tools. Authors should be able to use vi or notepad if that's what they want, and still not to have to do anything more than is currently needed to mark documents in LaTeX. I suspect that to maintain all the semantic codings from the current LaTeX markup, new elements would need to be added (or define values for the ROLE attribute). I'd personally prefer new elements over ROLE values to reduce the volume of the markup. -Fred -- Fred L. Drake, Jr. Corporation for National Research Initiatives 1895 Preston White Dr. Reston, VA 20191 From skaller@maxtal.com.au Wed Sep 9 14:58:02 1998 From: skaller@maxtal.com.au (John Skaller) Date: Wed, 09 Sep 1998 23:58:02 +1000 Subject: [Doc-SIG] SGML Python docs Message-ID: <1.5.4.32.19980909135802.00f04038@triode.net.au> At 17:10 8/09/98 -0400, Fred L. Drake wrote: > I don't think this is a "pet format" issue; Actually, I think it is. There are a lot of formats around, and all have advantages and disadvantages. The biggest advantage for any one author is probably familiarity. The biggest advantage for clients is availability of and familiarity with processing tools. This is not to say there are not _technical_ advantages to different approaches. See below. >there are advantages to >SGML/XML conversion, once there's a specific DTD and the SGML v. XML >decision is made (it's not at all clear which to use). There are also >advantages to *not* performing a conversion, primarily that the time >saved can be used to actually improve the content of the >documentation. To demonstrate what I mean: my prefered format is 'interscript'. The 'reason' is that I believe in literate programming, but the_real_ reason is that I'm familiar with it and can adapt it to do what I want because I'm the author of it :-) Interscript has decisive 'technical' advantages over all the other formats. For a start, it can generate the lot, automatically, so it subsumes them all. Secondly, it can generate Python, so it is most likely to be used and maintained by program authors, alieviating the current problem of lots of undocumented modules, or, worse, incorrectly documented modules. There are two technical disadvantages -- interscript is new and unstable, and, it would be a fair amount of work to merge the existing documentation with the existing code. The 'real' disadvantage of course is familiarity and availability. I'm not trying to argue for interscript format, I'm trying to explain that the _real_ issue truly is 'pet' formats and that will not be put aside easily by any amount of technical argument. There's work involved, to be done by volunteers. The 'pet' format issue is not only real -- but valid. ------------------------------------------------------- John Skaller email: skaller@maxtal.com.au http://www.maxtal.com.au/~skaller phone: 61-2-96600850 snail: 10/1 Toxteth Rd, Glebe NSW 2037, Australia From Fred L. Drake, Jr." References: <1.5.4.32.19980909135802.00f04038@triode.net.au> Message-ID: <13814.39097.609843.469974@weyr.cnri.reston.va.us> John Skaller writes: > Actually, I think it is. There are a lot of formats around, > and all have advantages and disadvantages. The biggest advantage > for any one author is probably familiarity. The biggest advantage My understanding of your statement that precipitated this was that you thought "we" (prob. meaning Guido & I) were using the formats we're using (LaTeX) simply because that's what we like. I don't know what went into the original decision to use LaTeX, but I expect it included the issue of availability. I've continued to use it in part because there's a lot of documentation on TeX/LaTeX (both free on the web and published in books), because I know it (*not* because I like it -- I'm quite ambivilant), because it's free, and because I can make it do pretty much everything we need it to do. When that last item is no longer true, I will not hesitate to switch formats to something that will do what we want it to do. > Interscript has decisive 'technical' advantages over all the other > formats. > For a start, it can generate the lot, automatically, so it subsumes them all. I'm not at all convinced that this is a benefit, but that can be reasonably debated either way. Documenting that something is not yet documented (which seems the only real option when there isn't documentation) does not seem valuable, and can be distracting. > by program authors, alieviating the current problem of lots of undocumented > modules, or, worse, incorrectly documented modules. The problem of undocumented modules can only be fixed by someone writing documentation. Whether the documentation is embedded in the module or encoded in a separate file (as LaTeX, SGML, XML, or whatever) is a minor technical issue. The problem of incorrect documentation doesn't go away. Perhaps it becomes easier to keep the documentation up to date, but it will never be "free", so documentation will not follow implementation in lock-step. This is not a technical issue so much as a human issue; we are limited and so is our time. (Is this a bug or a feature of time? Careful; trick question!) -Fred -- Fred L. Drake, Jr. Corporation for National Research Initiatives 1895 Preston White Dr. Reston, VA 20191 From Fred L. Drake, Jr." References: <13813.39671.3295.188971@weyr.cnri.reston.va.us> <4e79e38248%tratt@dcs.kcl.ac.uk> Message-ID: <13814.40453.748852.965008@weyr.cnri.reston.va.us> Laurence Tratt writes: > only problem with LaTeX is that it's pretty hard to write a reliable parser > for, and that at the push of a button any program which relies on parts of Yes, this is a real problem. Perhaps there should be a LaTeXParser class available for Python, similar to sgmllib.SGMLParser? ;-) I don't know when I'll fit that in, but I'll probably have to whenever I get around to the next shot at a conversion script! > the markup staying roughly the same dies horribly. If there could be a > guarantee that the LaTeX markup wasn't going to change then I think it would > be OK to use the LaTeX as the base converter. However - from experience - the > temptation with LaTeX is always to have a quick fiddle to tidy things up, and > that breaks things very easily :) I don't know that this will change substantially if we use a Python- specific DTD. There are a couple of issues here: - Requirements change, even if slowly. The most substantial recent changes for the Python docs have been the introduction of the API document and the howto document class. - When new markup structures are identified which better serve existing requirements. For example, we're now coding the short "module synopsis" provided in chapter introductions in the module section, which improves the maintainability and flexibility of the documents. > I would imagine this is the only way to reliably retain all the information > that the LaTeX now holds (eg about when "string" is a module, and when it's I think the DocBook ROLE attribute could be used to help make these distinctions, but that brings back up the authoring issue again: who's going to type all that stuff? For the contributed documentation, we still receive more sections that use \code for everything that should be typeset in Courier than anything else (though some authors are using the "logical" markup; thanks!). What happens is that I have to spend a fair amount of time adjusting the markup to us \module, \function, \method, or whatever is called for. This is time consuming and prevents me from spending much time writing (as do other things, like needing to get things done!). Perhaps it's time to dust off the DTD I was writing as the target for the old conversion script and bring that somewhat up to date and add comments on the semantic interpretation of the elements and attributes, perhaps with notes on processing expectations for the current output formats. -Fred -- Fred L. Drake, Jr. Corporation for National Research Initiatives 1895 Preston White Dr. Reston, VA 20191 From skaller@maxtal.com.au Thu Sep 10 07:58:05 1998 From: skaller@maxtal.com.au (John Skaller) Date: Thu, 10 Sep 1998 16:58:05 +1000 Subject: [Doc-SIG] SGML Python docs Message-ID: <1.5.4.32.19980910065805.00ef35ec@triode.net.au> At 11:03 9/09/98 -0400, Fred L. Drake wrote: > >John Skaller writes: > > Actually, I think it is. There are a lot of formats around, > > and all have advantages and disadvantages. The biggest advantage > > for any one author is probably familiarity. The biggest advantage > > My understanding of your statement that precipitated this was that >you thought "we" (prob. meaning Guido & I) were using the formats >we're using (LaTeX) simply because that's what we like. In some sense .. that's a necessary truth. :-) > I don't know what went into the original decision to use LaTeX, but >I expect it included the issue of availability. I've continued to use >it in part because there's a lot of documentation on TeX/LaTeX (both >free on the web and published in books), because I know it (*not* >because I like it -- I'm quite ambivilant), because it's free, and >because I can make it do pretty much everything we need it to do. But it produces paper! Today, we want Web enabled documents. Do you know anyone that has a paper copy of the docs?? I don't. I never will, either. >When that last item is no longer true, I will not hesitate to switch >formats to something that will do what we want it to do. It's no longer true. See above. Paper isn't useless: but it isn't the first use media for free software. IMHO. > > Interscript has decisive 'technical' advantages over all the other > > formats. > > For a start, it can generate the lot, automatically, so it subsumes them all. > > I'm not at all convinced that this is a benefit, but that can be >reasonably debated either way. Documenting that something is not yet >documented (which seems the only real option when there isn't >documentation) does not seem valuable, and can be distracting. The point is that to generate the module at all it _has_ to be converted to interscript and given a heading. That leaves annotating the code and adding user doco, which is the _easy_ part even though it reqiures more work -- it can be updated by users with patches and contributions. BOTH the software and doco. > > by program authors, alieviating the current problem of lots of undocumented > > modules, or, worse, incorrectly documented modules. > > The problem of undocumented modules can only be fixed by someone >writing documentation. Whether the documentation is embedded in the >module or encoded in a separate file (as LaTeX, SGML, XML, or >whatever) is a minor technical issue. I disagree, very strongly. The whole point of literate programming is to put the code and docs together in a single file so they can be maintained together. Donald Knuth agrees with me. :-) ------------------------------------------------------- John Skaller email: skaller@maxtal.com.au http://www.maxtal.com.au/~skaller phone: 61-2-96600850 snail: 10/1 Toxteth Rd, Glebe NSW 2037, Australia From tratt@dcs.kcl.ac.uk Wed Sep 9 22:30:37 1998 From: tratt@dcs.kcl.ac.uk (Laurence Tratt) Date: Wed, 09 Sep 1998 22:30:37 +0100 Subject: [Doc-SIG] SGML Python docs In-Reply-To: <13814.40453.748852.965008@weyr.cnri.reston.va.us> Message-ID: <187108348%tratt@dcs.kcl.ac.uk> In message <13814.40453.748852.965008@weyr.cnri.reston.va.us> "Fred L. Drake" wrote: >> only problem with LaTeX is that it's pretty hard to write a reliable parser >> for > Yes, this is a real problem. Perhaps there should be a LaTeXParser > class available for Python, similar to sgmllib.SGMLParser? ;-) I > don't know when I'll fit that in Quit your day job :) > but I'll probably have to whenever I get around to the next shot at a > conversion script! I don't think one needs to make a general parser, and writing a hard-coded-to- one-style parser is definitely a lot easier. But that's what I mean about breaking: a hard-coded parser is totally at the mercy of the LaTeX style staying the same. > I don't know that this will change substantially if we use a Python- > specific DTD. There are a couple of issues here: > > - Requirements change, even if slowly. The most substantial > recent changes for the Python docs have been the > introduction of the API document and the howto document > class. > - When new markup structures are identified which better > serve existing requirements. For example, we're now coding > the short "module synopsis" provided in chapter > introductions in the module section, which improves the > maintainability and flexibility of the documents. It's a bit easier to update things in a conversion program with a more, er, strict layout like XML than LaTeX: with LaTeX, if you write a conversion script, you pretty much have to stipulate that if the style changes, the program gets rewritten. With XML/SGML/whatever, you have a fighting chance :) Personally I'm not a great fan of XML, but I would like to be able to generate different types of output from the documentation - which contains all the information I need, but in a very hard to digest format. Something like XML won't really solve any problems for the people writing the documentation as far as I can see, but it will solve the output problem. Does this sound like a fair comment? > Perhaps it's time to dust off the DTD I was writing as the target > for the old conversion script and bring that somewhat up to date and > add comments on the semantic interpretation of the elements and > attributes, perhaps with notes on processing expectations for the > current output formats. That sounds like a good idea. Laurie From cg@pobox.com Fri Sep 11 11:52:49 1998 From: cg@pobox.com (Cees de Groot) Date: Fri, 11 Sep 1998 12:52:49 +0200 Subject: [Doc-SIG] SGML Python docs In-Reply-To: Your message of "Tue, 08 Sep 1998 17:10:12 EDT." <13813.40244.821275.420987@weyr.cnri.reston.va.us> Message-ID: <199809111052.MAA11886@bofh.cdg.acriter.nl> fdrake@cnri.reston.va.us said: > I don't think this is a "pet format" issue; there are advantages to > SGML/XML conversion, once there's a specific DTD and the SGML v. XML > decision is made (it's not at all clear which to use). I've been through the SGML vs XML debate a couple of times. For larger documentation projects, I have opted for SGML for two reasons: - More knowledge, more tools, more support, etcetera; - If you need the advanced features of SGML, they're there; if you don't, you can always "downgrade" to XML by the time that the standard is in widespread use. This (plus the non-availability of DocBook) where the main reasons for the SGMLtools project sticking with SGML, and I think they're valid here as well. Regards, Cees -- Cees de Groot http://pobox.com/~cg http://www.sgmltools.org --- We're hiring Java developers => www.acriter.com From cg@pobox.com Fri Sep 11 11:48:20 1998 From: cg@pobox.com (Cees de Groot) Date: Fri, 11 Sep 1998 12:48:20 +0200 Subject: [Doc-SIG] SGML Python docs In-Reply-To: Your message of "Tue, 08 Sep 1998 17:04:22 EDT." <13813.39894.376291.475807@weyr.cnri.reston.va.us> Message-ID: <199809111048.MAA11863@bofh.cdg.acriter.nl> fdrake@cnri.reston.va.us said: > Good docstrings and good reference documentation are not necessarily > related. That, of course, depends on how far you want to go with literate programming aspects in docstrings - more a voting issue than anything else. I vote for the inclusion of reference documentation in the sources, on a level comparable with Javadoc or POD (more the former than the latter, though). By adopting a "first-sentence" convention like Javadoc, docstrings can still be used for a compact on-line reference. The reason: I've never seen a project where separate source and documentation files where kept in synch. -- Cees de Groot http://pobox.com/~cg --- We're hiring Java developers => www.acriter.com From cg@pobox.com Fri Sep 11 12:24:31 1998 From: cg@pobox.com (Cees de Groot) Date: Fri, 11 Sep 1998 13:24:31 +0200 Subject: [Doc-SIG] SGML Python docs In-Reply-To: Your message of "Wed, 09 Sep 1998 14:18:31 BST." <4e79e38248%tratt@dcs.kcl.ac.uk> Message-ID: <199809111124.NAA12227@bofh.cdg.acriter.nl> tratt@dcs.kcl.ac.uk said: > I would imagine this is the only way to reliably retain all the > information that the LaTeX now holds (eg about when "string" is a > module, and when it's an attribute in an RE object). I don't believe > in reinventing the wheel when it's not necessary, but I would imagine > we would be trying to mangle two different wheels together if we used > a non-specific DTD. Fred made a statement about energy better spent at writing documentation than converting it - this becomes very true in the area of DTDs. A DTD like DocBook isn't non-specific, it is very specific: writing software documentation, and with it are all the tools to adapt it to your own piece of software (starting with very simple things like role attributes). With inventing your own DTD you'll have little gains, but a big burden: endless discussions on tags, the need to maintain it, the need to write conversion software, etcetera. I'd advise anything short of a full-time SGML publishing business against doing so. The string module. The string attribute of an RE object. As I mentioned, with the decision to use DocBook, you'd need to make a sort of stylesheet where you define the markup to apply to the common elements of the software being documented; in the case of Python, this list is probably something like [module, class, function, parameter, default value of parameter, attribute], in other words: not very long and way easier to maintain than a complete DTD. -- Cees de Groot http://pobox.com/~cg --- We're hiring Java developers => www.acriter.com From cg@pobox.com Fri Sep 11 12:37:10 1998 From: cg@pobox.com (Cees de Groot) Date: Fri, 11 Sep 1998 13:37:10 +0200 Subject: [Doc-SIG] SGML Python docs In-Reply-To: Your message of "Wed, 09 Sep 1998 10:26:37 EDT." <13814.36893.111247.43425@weyr.cnri.reston.va.us> Message-ID: <199809111137.NAA12317@bofh.cdg.acriter.nl> fdrake@cnri.reston.va.us said: > I think it is very important to make authoring fairly comfortable. Don't forget that writing a document is only a small piece of a document's life cycle; personally, I don't think that the verbose markup style of DocBook is therefore a big problem. On the other hand, it should be quite easy to edit with a SGML declaration/DocBook variant that allows absolutely minimal input and run it through 'sgmlnorm' (part of Jade) to get something to continue working on. > We may be able to use a DocBook variant for authoring, with more > I'd personally prefer new elements over ROLE > values to reduce the volume of the markup. Note that when adding new elements you need to provide DSSSL enhancements as well if you want to have them stand out in the final text. When using ROLE values, you'll generally have the correct rendition. Furthermore, you need to publish DTD fragments with the SGML source, and within some editing environments it may be cumbersome to load these DTD fragments in order to augment the environment for "python-enhanced DocBook". Especially in a setting like Python, where you cannot possibly predict what tools are going to be used to render/edit/... documents, you'll need to be very careful here. -- Cees de Groot http://pobox.com/~cg --- We're hiring Java developers => www.acriter.com From Fred L. Drake, Jr." References: <13814.36893.111247.43425@weyr.cnri.reston.va.us> <199809111137.NAA12317@bofh.cdg.acriter.nl> Message-ID: <13821.25033.294296.370461@weyr.cnri.reston.va.us> Fred L. Drake, Jr. said: > I think it is very important to make authoring fairly comfortable. Cees de Groot writes: > Don't forget that writing a document is only a small piece of a document's > life cycle; personally, I don't think that the verbose markup style of DocBook Cees, This points to one of the quirks in the world of Python documentation: many sections are contributed (most especially in the library reference), but are maintained centrally after acceptance. From that perspective, authoring needs to be easy since it is commonly done by people who only write a small number of sections. Maintenance is done by someone working on most of the documentation on a moderately regular basis (me), where the learning curve is more effectively ammortized. For the contributing author, there are typically no maintenance efforts, and if there are, it is usually accomplished by submitting a bug report. > Note that when adding new elements you need to provide DSSSL enhancements as > well if you want to have them stand out in the final text. When using ROLE I don't see this as a problem; I'd expect to provide at least one print and one online stylesheet for the system. > values, you'll generally have the correct rendition. Furthermore, you need to Most of the semantic markings currently used produce a type-style change, so the style enhancements will be required one way or the other. > publish DTD fragments with the SGML source, and within some editing > environments it may be cumbersome to load these DTD fragments in order to I'm not terribly concerned about the ease of working with any of the commercially available SGML/XML editors, since those are usually too expensive to have hanging around, and I really don't expect many contributors already have them for other purposes. I don't know if emacs' PSGML mode would have difficulty with DocBook sub-/super-sets, which is more of an issue. I know vi and notepad would be ok. ;-) -Fred -- Fred L. Drake, Jr. Corporation for National Research Initiatives 1895 Preston White Dr. Reston, VA 20191 From Olivier BERGER" Dear members of the Doc-SIG, First I have to appologize for this (allmost) cross-posting with comp.lang.python... But as I think this might concern both python documentation's authors or people interested in python's future, I have posted this announcement here too.... I have set-up a Python documentation translation project whith the idea to provide translated documents about Python for different native languages. The goal is to let introductory material be available to more and more people (potentially) interested in Python programming, but who don't have a good knowledge of english, especially people new to IT or programming. The project will be "managed" with the facility of a dedicated Mailing List accessible at http://www.egroups.com/list/python_doc_translation All details about the project on the ML's site... (archives are open to anyone) (Maybe some of you may wonder why I have decided to create a separate ML... well, it's too soon to say if the project will produce valuable documents, and federate enough efforts... so a specific place will be more practical for now... we'll see what's goin on in the future) Note that the submissions to this mailing-list should be posted in english if for a general purpose. Specific languages' discussions will be held in other languages.... Now for the project itself, ... well, up to now, the only started translation is a french translation of Guido Van Rossum's Tutorial. I let you know when it's out (or in comp.lang.python). We currently have at least 3 people willing to contribute to this french translation. I have also heard about japanese translations, and Dutch or German (original) documents too... which were previously available. Other languages (than french) translation efforts will be of course most wellcome. Thanx in advance for your comments or contribution about the project. (Note, as I am not currently registered on the Doc-Sig, please reply to my e-mail address : Olivier.Berger@capway.com). Olivier Berger. P.S.: Suggestion : if this project had to last and produce succesfull results, why not integrate it in a specific SIG ?... but far too soon to predict it ;) --------------------------------------------------- Olivier BERGER mailto:OlBerger@capgemini.fr (si probleme essayer Olivier.Berger@Capway.com) Ingenieur Projet - MCO Téléconduite Cap Gemini France - Division Services Publics Not speaking for his employer