Mailman 3 August 1996 - Doc-SIG

[PYTHON DOC-SIG] archives
by Samuel L. Bayer Aug. 22, 1996

Aug. 22, 1996

Having just joined, can somebody tell me if this list is archived? Sam ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig(a)python.org administrivia to: doc-sig-request(a)python.org =================

1 0

Re: [PYTHON DOC-SIG] doc string style question
by friedric＠rose.rsoc.rockwell.com Aug. 22, 1996

Aug. 22, 1996

|> From: mclay(a)eeel.nist.gov (Michael McLay) |> |> My docstring style keeps dithering since I haven't found a well |> defined convention to follow. Is there a WWW page on this that I've |> missed? No. but there should be when we can all converge on a tool. |> What's the recommended style for writting doc strings inside |> classes and function. I use the following style. def mif_escape(text): """Substitute the appropriate tokens for problematic characters. As you can see the python-mode will wrap the verbose author's text to tab level 1 when the return is struck. """ split = string.split join = string.join gendoc currently figures out the initial indent for the doc string and strips it off the text body. Also remember the "one liner" rule. The doc string should have the first line a summary of the purpose and the rest of the doc string is after a blank line. ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig(a)python.org administrivia to: doc-sig-request(a)python.org =================

1 0

[PYTHON DOC-SIG] doc string style question
by mclay＠eeel.nist.gov Aug. 22, 1996

Aug. 22, 1996

My docstring style keeps dithering since I haven't found a well defined convention to follow. Is there a WWW page on this that I've missed? What's the recommended style for writting doc strings inside classes and function. Here is a foo and a bar example that can be used for discussing the issue: class foo: """holds a foo, but if the doc string is long the lines needs to be wrapped to the next line""" def foofunc(self): """foofunc definitions can often be longer than one line. Should they wrap and not indent""" class bar: """holds a bar, but if the doc string is long the lines needs to be wrapped to the next line""" def barfunc(self): """barfunc definitions can often be longer than one line. Should they wrap and indent""" If indent is correct, should the next line be lined up with the first '"' mark or the first character in the quote? def barfunc(self): """barfunc definitions can often be longer than one line. Should they wrap and indent""" or def barfunc(self): """barfunc definitions can often be longer than one line. Should they wrap and indent""" Opiniions? Michael ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig(a)python.org administrivia to: doc-sig-request(a)python.org =================

2 1

[PYTHON DOC-SIG] PyCAPI 1.00a2 (now 133 entries and an index)
by Fredrik Lundh Aug. 22, 1996

Aug. 22, 1996

Same address: http://www.python.org/sigs/image-sig/PyCAPI.html Corrections and more comments are welcome. /F ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig(a)python.org administrivia to: doc-sig-request(a)python.org =================

4 5

[PYTHON DOC-SIG] Re: Do reference/user docs exist for the Py* API?
by lutz＠rmi.net Aug. 21, 1996

Aug. 21, 1996

>> [stuff about Python C API documentation] > > I had been hoping that Mark Lutz' book would cover things in more detail > than the existing Python docs -- is that wrong (Mark?)? I suppose it depends on what you mean by "more detail". Yes, my book does go beyond the docs, and discusses C integration in considerable detail. In fact, that was one of its original goals: to provide the extra perspective and context you can't get from manuals. OTOH, my book doesn't replace the manuals; it's not an exhaustive reference to every "extern" symbol in the Python system. I think manuals are a better vehicle for that sort of documentation. A few more details... The O'Reilly book discusses C integration, by working through examples. There's a C extension module, a C extension type, extension wrapper classes, an enhanced embedded-call API, and case studies on embedding Python in C/C++. Commonly-used API tools are documented along the way. But it doesn't exhaustively document _every_ C API symbol in detail. That's material for a reference manual IMHO. For one thing, such a reference could add hundreds of pages to an already-huge book. For another, the C API changes often; manuals can handle this better. Of course, there is alot of language reference material in my book too, and it's possible that more might creep in over time. Which will all make much more sense when the book finally comes out next month :-). So, my $0.02 -- I think a C API doc outside any book would be a very useful thing. Better still, if this material can be put online in HTML form, it can provide links that a book can't. > I'm not sure what it would mean to help, but I've been writing a reasonable > number of sets of Python bindings to C over the last several months, and I'd be > happy to help if I can. Sounds like a volunteer! :-). BTW, the doc sig mail-list is digging into this too; check out "doc-sig-request(a)python.org", unless you already have. Cheers, Mark L. ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig(a)python.org administrivia to: doc-sig-request(a)python.org =================

1 0

Re: [PYTHON DOC-SIG] PyCAPI 1.00a1, or something
by friedric＠rose.rsoc.rockwell.com Aug. 21, 1996

Aug. 21, 1996

|> |> Okay, I'm intentionally misusing the image-sig corner on python.org, |> but here we go anyway: |> |> http://www.python.org/sigs/image-sig/PyCAPI.html Cool. Great start. I like the format so far. Also, maybe a crossref index where you can look at it sorted by new name or old name can be generated. Can someone move the html over to the doc sig area or make a symlink? (also HTMLgen is available for this kind of thing <0.6wink>.) ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig(a)python.org administrivia to: doc-sig-request(a)python.org =================

2 1

[PYTHON DOC-SIG] PyCAPI 1.00a1, or something
by Fredrik Lundh Aug. 20, 1996

Aug. 20, 1996

Okay, I'm intentionally misusing the image-sig corner on python.org, but here we go anyway: http://www.python.org/sigs/image-sig/PyCAPI.html Far from complete and very rough, but probably enough to begin discussing the style and layout, as well as the content itself. /F ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig(a)python.org administrivia to: doc-sig-request(a)python.org =================

1 0

Re: [PYTHON DOC-SIG] Re: Do reference/user docs exist for the Py* API?
by friedric＠rose.rsoc.rockwell.com Aug. 20, 1996

Aug. 20, 1996

|> From: Fredrik Lundh <Fredrik_Lundh(a)ivab.se> |> |> From: Michael McLay |> > An immediate problem is that Framemaker isn't universally available |> > this choice will limit who can participate in the documentation project. |> |> True. Rule me out, for example. Untrue. A Framemaker standard would apply to the primary printed format and doesn't limit the methods/formats used in the authoring phase. There's nothing to say that we can't do just what Fredrik states. Once the text is written/generated then it would be imported into Frame to generate the printed/indexed/postscript version. Relying on cobbled together free tools pieces for the whole job is just unnecessary. Anyone can write the doc inputs in text and hand it over to someone with Framemaker for the integration. I just didn't want to see the distribution docs, which are currently nicely typeset in latex, in a reduced quality format. There's no need to reinvent the wheel here. This doen't mean that everyone helping with the doc projects will need Framemaker, just the docmaster. I agree with Fredrik's approach for the C API programmer reference, but I just don't want to stop there. I tend to use the printed docs much more than the various online references and I don't see that changing. -Robin ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig(a)python.org administrivia to: doc-sig-request(a)python.org =================

2 1

[PYTHON DOC-SIG] Re: Do reference/user docs exist for the Py* API?
by Fredrik Lundh Aug. 20, 1996

Aug. 20, 1996

Skip wrote: > The only other obvious alternative I see is HTML. It's big > disadvantage is that it's a moving target. Well, I don't think the basics will change any time soon. And as I hinted in my last mail, even mail clients include HTML editors nowadays. AMAZING, ISN'T IT? Regards /F

1 0

Re: [PYTHON DOC-SIG] Re: Do reference/user docs exist for the Py* API?
by friedric＠rose.rsoc.rockwell.com Aug. 20, 1996

Aug. 20, 1996

|> From: Skip Montanaro <skip(a)automatrix.com> |> |> Okay, Guido agrees the docs I'm looking for are needed: |> |> > I haven't been able to find any sort of reference or user documentation for |> > the Python C API other than the extending/embedding manual and the comments |> > in Include/abstract.h. Does anything else exist? ... |> |> Someone just donated a LaTeX file containing a translation from |> abstract.h (mostly), but apart from that, this stuff is still sorely |> missing... |> |> > At this point I'm mostly interested in a reference document ... |> > Longer term, I'd like to see some user documentation with short code |> > examples ... |> |> All totally agreed... We need more volunteer help to complete this |> job! The user documentation you seek will probably be met by the two books to be on the bookselves RSN;-) As for the definitive reference, I agree 100%; we need a big upgrade to the Extending & Embedding docs. |> |> I'd like to generate one or more template documents automatically from the C |> source or some other easily created template file that I can then make |> available to people with an interest in completing individual sections. I |> don't want to get into a quagmire right off the bat, so I will initially |> move this discussion from the main list to the doc-sig(a)python.org list. |> (Don't worry, I'll move it back when I need more help... :-) Would someone |> involved with the DOC-SIG (Michael McLay perhaps?) give me a quick |> brain-dump of the current state of the musings on the DOC-SIG, especially |> about issues of documentation format, input source, etc? I've subscribed to |> the doc-sig at this point, so further discussion should take place there. |> I'll also try and wade through the list's archives. |> |> Thx, |> |> Skip Montanaro The skinny recently has been the proposition that we come up with a new standard documentation format for the distribution docs. Currently things are baselined in LaTeX and other formats are spun off from that. I have argued that we should switch over to FrameMaker as the baseline tool. As I sit here I am working to steamline such an effort with some tools to aid the LaTeX->FrameMaker conversion. (Already finished the tutorial but that was easy as it didn't have an index.) At this point I would recommend _not_ using LaTeX markup. If we/you create a tool to generate docs for the API let's tune it for FrameMaker. We could either use the MML (maker markup language) or go through MIF (maker interchange format). The former is a very simple paragraph markup resembling HTML and the later is a full blown markup supporting everything Frame supports. ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig(a)python.org administrivia to: doc-sig-request(a)python.org =================

2 1