[Twisted-Python] typos

[Andrew Dalke]

Moshe:
>> Others said the doc build takes an hour.
>
> It shouldn't, on a sane machine. It takes about several minutes.
> Of course, you only need to rebuild the docs when you want to,
> not after every CVS update.

Andrew Bennets:
 > I think it would be too much effort to update the API docs 
automatically;
 > epydoc takes something like an hour to process all of Twisted

One says "several minutes" and the other "an hour" ...

Andrew Bennets:
 > Moshe, I'm not sure if he means that he wants to use the generated 
API docs
 > from epydoc (in which case he is correct), or if he didn't realise the
 > Howtos were independent of that timeframe (in which case I'm sure 
that's an
 > honest mistake).

I didn't realize.

>> I would rather not learn how to do that
>> myself
>
> I won't give you that option.
> % ./admin/process-docs
>
> There, now you learned how to do it yourself, whether you wanted
> to or not.

Just because you told me doesn't mean I'll remember.  I have a small
brain, and the less I have to learn, the better.

BTW, I just did that on my machine.  I see it assumes I have some
software I don't actually have.

  ...
doc/howto/controllerindepth
sh: pngtopnm: command not found
sh: pnmtops: command not found
Traceback (most recent call last):
   File "./bin/lore", line 29, in ?
     run()
   File "./twisted/scripts/lore.py", line 88, in run
     w.generate()
   File "twisted/lore/process.py", line 60, in generate
     self.df(fullpath, linkrel)
   File "./twisted/lore/default.py", line 55, in <lambda>
     df = lambda file, linkrel: latex.convertFile(file, spitter)
   File "./twisted/lore/latex.py", line 450, in convertFile
     processFile(spitter, fin)
   File "./twisted/lore/latex.py", line 443, in processFile
     spitter.visitNode(dom)
   File "./twisted/lore/latex.py", line 81, in visitNode
     getattr(self, 'visitNode_'+node.tagName, 
self.visitNodeDefault)(node)
   File "./twisted/lore/latex.py", line 86, in visitNodeDefault
     self.visitNode(child)
   File "./twisted/lore/latex.py", line 81, in visitNode
     getattr(self, 'visitNode_'+node.tagName, 
self.visitNodeDefault)(node)
   File "./twisted/lore/latex.py", line 86, in visitNodeDefault
     self.visitNode(child)
   File "./twisted/lore/latex.py", line 81, in visitNode
     getattr(self, 'visitNode_'+node.tagName, 
self.visitNodeDefault)(node)
   File "./twisted/lore/latex.py", line 172, in visitNode_img
     f(fileName, target)
   File "./twisted/lore/latex.py", line 179, in convert_png
     raise OSError(r)
OSError: 32512

I then installed the netpbm package ("fink install netpbm"), which
took about 14 minutes and reran the process-docs program

./admin/process-docs: latex: command not found

That's it - I'm not wasting any more time to get a local copy
of the docs.  Yes, I could install latex, and iterate install
packages until it all works, but my point is that getting the
docs working is a non-trivial task, at least for some people.
And woe be to those running something without a 'sh' derived
shell.

(BTW, it appears the latex call is only needed for the PDF
howto, and occurs after the HTML generation, so the error message
above only means that PS/PDF output won't be generated, and not
that latex is needed to finish the HTML output; eg, if there are
equations generated by LaTeX.  I do see the howto html files.)


> Why can't you run that cronjob on your CVS updated copy every day
> or so?

I originally brought this up because I sent in some doc corrections
which had been updated in CVS.  Thus, the time I spent writing the
bug report was wasted.  If the latest ("unstable") docs were published
on the twisted site then I would have easily noticed that it had
since been corrected.

Now, I could make my own mirror of twisted on my local machine (though
since it's a laptop, a simple cron wouldn't work, and I hate having
jobs run when I'm on battery power because of the extra power demands;
I've got wireless and like working on the porch).

However, that suggestion implies some disregard on others' time because
you are raising the barrier for people to provide meaningful help.
It's very little work for you all to provide the latest docs on-line,
so why not do it?  Esp. as you've now seen, the doc build makes some
requirements on a system (sh, netpbm, latex, others?) which might not
exist.

Glyph:
 > We say this about functionality as well, and CVS docs should have 
parity
 > with CVS code, not released code.  (In other words - if you want CVS
 > docs, download CVS code.)

Okay, then make an "UNSTABLE" release which corresponds to the most
recent docs, both of which are created anew each day. This provide the
parity you want, and also helps developers who want to see if the most
recent code fixes a problem they've come across, or who like working
on the bleeding edge.  This is also helpful for people at companies
which don't allow anything but port 80 through their firewalls (and so
block CVS access) to get a copy of the latest CVS version.

Moshe:

> It's not hard. It's just that the only people who want to read docs 
> about
> CVS will need to have a checkout anyway, and those people can easily
> run ./admin/process-docs.
> This script was specifically written (and taken outside 
> release-twisted)
> so we can easily build docs ourself.

How does someone new to twisted learn about this?  Eg, there's nothing
in the README which mentions it.  (Actually, it should be something like
"README_CVS" which is directed to people using Twisted from CVS rather
than from a release.)  And it doesn't look like it's mentioned anywhere
in anything.

% grep -s "process_docs" `find . -print`
%

					Andrew
					dalke at dalkescientific.com