discuss: LDP Style discussion (cont.)
Subject:
Re: LDP Style discussion (cont.)
From:
Charles Curley ####@####.####
Date:
9 Apr 2002 02:12:02 -0000
Message-Id: <20020408201124.E7815@trib.com>
On Mon, Apr 08, 2002 at 01:25:37PM -0500, Joy Y Goodreau wrote:
> As we prepare to begin the Style Guide effort at the LDP, I thought it
> important to answer some of the questions David Lawyer posted to the list
> about the Style Guide in case many of you had the same questions. My
> apologies for this being so late of a response. I also apologize for this
> being so long. My passion for this project and for documentation that is
> easy to read makes me somewhat of a zealot! :)
After reading this, let me refer everyone to "Read Me First! A Style
Guide for the Computer Industry", by Sun Technical Publications, First
edition, 272 pages, ISBN 0-13-455347-0,
http://www.sun.com/books/catalog/EdStyle/index.html. I just read it,
and found it to be an excellent reference book. Both professional and
amateur writers can benefit from it.
After reading Joy's comments, I think this book might be a good
starting point for designing and writing the LDP style guide. There
are some things in there we should, ah, research (as Tom Lehrer would
have it :-), but there are other things we don't need.
I think we miss a point in making things easy on our authors. Doing an
LDP document is a good way to get some training in technical
communications. I'm a professional technical writer (inter alia), and
I learned from Joy's editing. (Thank you again, Joy.) While the LDP is
not (and should not be) as rigorous as a typical technical
communications department would be, it is useful experience. Maybe we
can entice prospective authors with that.
>
> My argument precisely against many of the style guides in existence today.
> They are not written for someone who is not a writer by profession. We
> don't want that here. We want more of a style reference.
I agree. A well written style guide _is_ a style reference. If you
don't know, say, the difference between "it's" and "its" you should be
able to find it in the index or TOC and look it up. Or search the
on-line version. (Quick, how many of you know the difference? :-)
Wherefore, good indexing will be essential.
>
> A style guide's primary goal is clarity and accuracy--exactly what you are
> arguing is important. Style is more than grammar and more than what
> something looks like. For technical documentation, style is a matter of
> usability. Style focuses on how easily what you write translates into other
> languages. Style guides let authors know that when you have authors who
> read English as a second language, they may get confused if you use certain
> phrases or types of humor. Because our authors are not necessarily writers
> by trade, it is essential that we provide a reference for them that helps
> them make their documentation the most easily-read document it can
> be.
Agreed. Exactly why I mentioned the Sun book above.
--
Charles Curley /"\ ASCII Ribbon Campaign
Looking for fine software \ / Respect for open standards
and/or web pages? X No HTML/RTF in email
http://w3.trib.com/~ccurley / \ No M$ Word docs in email
--> -->
<type 'exceptions.IOError'> | Python 2.5.2: /usr/bin/python
Wed Jul 3 15:55:53 2024 |
A problem occurred in a Python script. Here is the sequence of
function calls leading up to the error, in the order they occurred.
| /opt/ezmlm-browse-0.20/main.py in main() |
424
|
425 if path is not None:
|
426 main_path(path)
|
427 else:
|
428 main_form()
|
| global main_form = <function main_form at 0x863fc6c> |
| /opt/ezmlm-browse-0.20/main.py in main_form() |
378 except ImportError:
|
379 die(ctxt, "Invalid command")
|
380 module.do(ctxt)
|
381
|
382 def main():
|
| module = <module 'commands.showmsg' from '/opt/ezmlm-browse-0.20/commands/showmsg.pyc'>, module.do = <function do at 0x8646e9c>, global ctxt = {'cmd': 'showmsg', 'threadidx': 2, 'HTTP_X_FORWA...HTTP_ACCEPT_ENCODING': 'gzip, br, zstd, deflate'} |
| /opt/ezmlm-browse-0.20/commands/showmsg.py in do(ctxt={'cmd': 'showmsg', 'threadidx': 2, 'HTTP_X_FORWA...HTTP_ACCEPT_ENCODING': 'gzip, br, zstd, deflate'}) |
18 write(html('msg-pager') % ctxt)
|
19 write('<hr>')
|
20 sub_showmsg(ctxt, ctxt[MSGNUM])
|
21 write('<hr>')
|
22 write(html('msg-pager') % ctxt)
|
| global sub_showmsg = <function sub_showmsg at 0x863f1ec>, ctxt = {'cmd': 'showmsg', 'threadidx': 2, 'HTTP_X_FORWA...HTTP_ACCEPT_ENCODING': 'gzip, br, zstd, deflate'}, global MSGNUM = 'msgnum' |
| /opt/ezmlm-browse-0.20/globalfns.py in sub_showmsg(ctxt={'cmd': 'showmsg', 'threadidx': 2, 'HTTP_X_FORWA...HTTP_ACCEPT_ENCODING': 'gzip, br, zstd, deflate'}, msgnum=2727) |
229 format_timestamp(ctxt, ctxt)
|
230 write(html('msg-header') % ctxt)
|
231 rec_showpart(ctxt, msg, 0)
|
232 write(html('msg-footer') % ctxt)
|
233 ctxt.pop()
|
| global rec_showpart = <function rec_showpart at 0x863f1b4>, ctxt = {'cmd': 'showmsg', 'threadidx': 2, 'HTTP_X_FORWA...HTTP_ACCEPT_ENCODING': 'gzip, br, zstd, deflate'}, msg = <email.message.Message instance at 0x86b3f4c> |
| /opt/ezmlm-browse-0.20/globalfns.py in rec_showpart(ctxt={'cmd': 'showmsg', 'threadidx': 2, 'HTTP_X_FORWA...HTTP_ACCEPT_ENCODING': 'gzip, br, zstd, deflate'}, part=<email.message.Message instance at 0x86b3f4c>, partnum=1) |
205 else:
|
206 for p in part.get_payload():
|
207 partnum = rec_showpart(ctxt, p, partnum+1)
|
208 else:
|
209 write(html('msg-sep') % ctxt)
|
| partnum = 1, global rec_showpart = <function rec_showpart at 0x863f1b4>, ctxt = {'cmd': 'showmsg', 'threadidx': 2, 'HTTP_X_FORWA...HTTP_ACCEPT_ENCODING': 'gzip, br, zstd, deflate'}, p = <email.message.Message instance at 0x86b904c> |
| /opt/ezmlm-browse-0.20/globalfns.py in rec_showpart(ctxt={'cmd': 'showmsg', 'threadidx': 2, 'HTTP_X_FORWA...HTTP_ACCEPT_ENCODING': 'gzip, br, zstd, deflate'}, part=<email.message.Message instance at 0x86b904c>, partnum=2) |
208 else:
|
209 write(html('msg-sep') % ctxt)
|
210 sub_showpart(ctxt, part)
|
211 return partnum
|
212
|
| global sub_showpart = <function sub_showpart at 0x863f144>, ctxt = {'cmd': 'showmsg', 'threadidx': 2, 'HTTP_X_FORWA...HTTP_ACCEPT_ENCODING': 'gzip, br, zstd, deflate'}, part = <email.message.Message instance at 0x86b904c> |
| /opt/ezmlm-browse-0.20/globalfns.py in sub_showpart(ctxt={'cmd': 'showmsg', 'threadidx': 2, 'HTTP_X_FORWA...HTTP_ACCEPT_ENCODING': 'gzip, br, zstd, deflate'}, part=<email.message.Message instance at 0x86b904c>) |
164 type = ctxt[TYPE] = part.get_content_type()
|
165 ctxt[FILENAME] = part.get_filename()
|
166 template = html('msg-' + type.replace('/', '-'))
|
167 if not template:
|
168 template = html('msg-' + type[:type.find('/')])
|
| global template = <function template at 0x8637e9c>, global html = <function html at 0x8637ed4>, type = 'application/pgp-signature', type.replace = <built-in method replace of str object at 0x86b8c28> |
| /opt/ezmlm-browse-0.20/globalfns.py in html(name='msg-application-pgp-signature') |
40
|
41 def html(name):
|
42 return template(name + '.html')
|
43
|
44 def xml(name):
|
| global template = <function template at 0x8637e9c>, name = 'msg-application-pgp-signature' |
| /opt/ezmlm-browse-0.20/globalfns.py in template(filename='msg-application-pgp-signature.html') |
31 except IOError:
|
32 if not _template_zipfile:
|
33 _template_zipfile = zipfile.ZipFile(sys.argv[0])
|
34 try:
|
35 f = _template_zipfile.open(n).read()
|
| global _template_zipfile = None, global zipfile = <module 'zipfile' from '/usr/lib/python2.5/zipfile.pyc'>, zipfile.ZipFile = <class zipfile.ZipFile at 0x85d0a7c>, global sys = <module 'sys' (built-in)>, sys.argv = ['-c', '/opt/ezmlm-browse-0.20'] |
| /usr/lib/python2.5/zipfile.py in __init__(self=<zipfile.ZipFile instance at 0x864f46c>, file='-c', mode='r', compression=0, allowZip64=False) |
337 self.filename = file
|
338 modeDict = {'r' : 'rb', 'w': 'wb', 'a' : 'r+b'}
|
339 self.fp = open(file, modeDict[mode])
|
340 else:
|
341 self._filePassed = 1
|
| self = <zipfile.ZipFile instance at 0x864f46c>, self.fp = None, builtin open = <built-in function open>, file = '-c', modeDict = {'a': 'r+b', 'r': 'rb', 'w': 'wb'}, mode = 'r' |
<type 'exceptions.IOError'>: [Errno 2] No such file or directory: '-c'
args =
(2, 'No such file or directory')
errno =
2
filename =
'-c'
message =
''
strerror =
'No such file or directory'
