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
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. <fdrake@acm.org> Corporation for National Research Initiatives 1895 Preston White Dr. Reston, VA 20191
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 <cg@pobox.com> http://www.sgmltools.org <cg@sgmltools.org> --- We're hiring Java developers => www.acriter.com
participants (3)
-
cg＠pobox.com -
Fred L. Drake -
John Skaller