Mailman 3 September 1998 - Doc-SIG

New Python documentation translation project announcement
by Olivier BERGER Sept. 22, 1998

Sept. 22, 1998

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(a)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(a)Capway.com) Ingenieur Projet - MCO Téléconduite Cap Gemini France - Division Services Publics Not speaking for his employer

1 0

RE: [Doc-SIG] SGML Python docs
by Richard Folwell Sept. 14, 1998

Sept. 14, 1998

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(a)redbox.net http://www.redbox.net Voice: +44 181 585 8565 Fax: +44 181 585 8665

3 3

SGML Python docs
by Laurence Tratt Sept. 11, 1998

Sept. 11, 1998

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

3 8

Re: [Doc-SIG] SGML Python docs
by John Skaller Sept. 11, 1998

Sept. 11, 1998

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(a)maxtal.com.au http://www.maxtal.com.au/~skaller phone: 61-2-96600850 snail: 10/1 Toxteth Rd, Glebe NSW 2037, Australia

3 2

Re: [Doc-SIG] SGML Python docs
by John Skaller Sept. 10, 1998

Sept. 10, 1998

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(a)maxtal.com.au http://www.maxtal.com.au/~skaller phone: 61-2-96600850 snail: 10/1 Toxteth Rd, Glebe NSW 2037, Australia

1 0

Re: [Doc-SIG] SGML Python docs
by John Skaller Sept. 9, 1998

Sept. 9, 1998

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(a)maxtal.com.au http://www.maxtal.com.au/~skaller phone: 61-2-96600850 snail: 10/1 Toxteth Rd, Glebe NSW 2037, Australia

2 1