From hgg9140@seanet.com Tue Feb 1 03:30:19 2000 From: hgg9140@seanet.com (Harry George) Date: Mon, 31 Jan 2000 19:30:19 -0800 Subject: [Doc-SIG] Re: text markups References: <20000131170017.C8A791CE73@dinsdale.python.org> Message-ID: <3896534A.995DB20B@seanet.com> Here is some "pod" style encoding, with SDF extensions. The translator is written in python (this is test01 for that package). It handles tables, nested lists, table-of-contents and indexes, and links. Output is to HTML, Latex, and Docbook. Would this be of interest? ========================================= =include default_cfg.pdx =cfg title = test01 desc=hello, world author = Harry George author_email = hgg9140@seanet.com owner = @author@ toc_p=0 =end cfg =include article_style.pdx =def greeting = hello =def expand_p = 0 Hello: @greeting@, world =def expand_p = 1 Hello: @greeting@, world Hello. B, C, I, U. =for html This should be red. =for html and this is back to black. Here are some escaped chars: E, E, E, E, E. =center This is will be centered. As will this (using a skipped line). =end center But not this.  =center This is will be centered.
As will this (using a break). =end center But not this. ====================================== > ------------------------------------------------------------------------ > Today's Topics: > > 1. Re: Monty: A structured text syntax idea (Greg Ward) > ` > ------------------------------------------------------------------------ > > Subject: Re: [Doc-SIG] Monty: A structured text syntax idea > Date: Mon, 31 Jan 2000 09:21:01 -0500 > From: Greg Ward > To: doc-sig@python.org > References: <3.0.6.32.20000129102716.009cd5c0@gpo.iol.ie> > > On 29 January 2000, Sean Mc Grath said: > > """ > > idea: > > para: > > I was editing some text in Python emacs mode the > > other day. > > para: > > I got to thinking how Python mandatory indentation > > emph: > > removes > > much of the need for delimiters > > Auughh!!! Shades of troff here. (That's not a good thing.) Newlines > are a fine delimiter in a programming language, where the semantic > chunks tend to be on the order of 20-60 characters, and we need all the > help we can get to guide our eyes. Natural language can have much > smaller semantic chunks -- eg. emphasized words -- so artificially > splitting lines so often is a waste of vertical real-estate. > > I think I'll wait for whatever Moshe proposes... (I just hope it uses > something B to emphasise text... >grin<) > > Greg -- Harry George hgg9140@seanet.com From fdrake@acm.org Tue Feb 1 03:54:11 2000 From: fdrake@acm.org (Fred L. Drake, Jr.) Date: Mon, 31 Jan 2000 22:54:11 -0500 (EST) Subject: [Doc-SIG] Doc-SIG session results, partial report Message-ID: <14486.22755.637468.13612@weyr.cnri.reston.va.us> I've published two new pages regarding the Doc-SIG session at IPC8. The general report (still needs work) is available at: http://www.python.org/workshops/2000-01/doc-report.html (This is not yet linked from the other conference pages; Barry, can you add a link when you have a place for the reports?) A first draft of a description of our audiences is at: http://www.python.org/sigs/doc-sig/audiences.html Discussion on both is welcome. -Fred -- Fred L. Drake, Jr. Corporation for National Research Initiatives From Moshe Zadka Wed Feb 2 23:51:42 2000 From: Moshe Zadka (Moshe Zadka) Date: Thu, 3 Feb 2000 01:51:42 +0200 (IST) Subject: [Doc-SIG] Apology Message-ID: I'm sorry I still haven't come up with a proposal. We're working heads down now, so I will probably only put up the formal spec on Friday (that's when the weekend starts around here). Thank you for your patience.y -- Moshe Zadka . INTERNET: Learn what you know. Share what you don't. From Moshe Zadka Thu Feb 3 00:29:25 2000 From: Moshe Zadka (Moshe Zadka) Date: Thu, 3 Feb 2000 02:29:25 +0200 (IST) Subject: [Doc-SIG] Doc-String Syntax Message-ID: Yet another one in my series of fuzzy outlines before the real spec, here is my suggestion for doc-string syntax. There are two kinds of tags: "short" tags and "long" tags. Short tags have the syntax exemplified by [emph this is emphasized] (the first word is the tag, and it continues to a nested bracket. Rational: this way tags can be written without touching the "shift" keys on most keyboards. Long tags have the syntax exemplified by arg name=s type=string:: string to be parsed The special long tag 'example' will not be intepreted by the program, so example:: ['this', 'is', 'a', 'list'] will work with no problems the special long tag 'code' will work the same way, but will be translated to inline code: you can also write code:: (lambda x: [x])(5) to return a list containing 5. Paragraphs are seperated by new lines. Another long tag, which is only valid in a classe's docstring, are 'instance-attrs' (unlike 'data', which would be class attributes). All of the current semantic markup would be moved to short tags: [module urllib], [class URLOpener] and [function urlopen] are all examples. Spec, as promised, on Friday. -- Moshe Zadka . INTERNET: Learn what you know. Share what you don't. From gward@cnri.reston.va.us Thu Feb 3 14:21:54 2000 From: gward@cnri.reston.va.us (Greg Ward) Date: Thu, 3 Feb 2000 09:21:54 -0500 Subject: [Doc-SIG] Doc-String Syntax In-Reply-To: ; from moshez@math.huji.ac.il on Thu, Feb 03, 2000 at 02:29:25AM +0200 References: Message-ID: <20000203092153.A19176@cnri.reston.va.us> On 03 February 2000, Moshe Zadka said: > There are two kinds of tags: "short" tags and "long" tags. Good distinction. Common markup -- emphasis, code snippets -- must be dead easy to type. > Short tags have the syntax exemplified by [emph this is emphasized] (the > first word is the tag, and it continues to a nested bracket. > Rational: this way tags can be written without touching the "shift" keys > on most keyboards. Well, if you're going to get so anal-retentive as to worry about the "difficulty" of using shift keys, then I will retaliate in kind and insist that angle brackets are easier to type than square brackets: square brackets either require use of the right-hand pinky, or a right-hand jump to use the bigger fingers. For me, angle brackets are closer to the middle finger, so I find them easier to type. A usability experiment: type the same chunk of text using three possible syntaxes; we're trying to test both typability and readability. First, straight POD as documented in the "perlpod" man page: It must be easy to B certain words, and to mark others as C (or even whole C). Similar, but a little more verbose and explicit (mix POD with Moshe's idea): It must be easy to emph certain words, and to mark others as code (or even whole code). Finally, Moshe's syntax: It must be easy to [emph emphasise] certain words, and to mark others as [code code] (or even whole [code code snippets]). First, I was wrong; square versus angle brackets make very little difference to typability. However, for readability I like seeing the tag separated from the text it tags, ie. I prefer "emph" to "[emph foo]" not because of the shape of the brackets, but because the tag is outside of the brackets, So if you're really keen on square brackets, how about this: It must be easy to emph[emphasise] certain words, and to mark others as code[code] (or even whole code[code snippets]). Oh, here's another thing to consider regarding the shape of brackets: what kind of bracket is more likely to occur inside typical Python code snippets? Ie. are you more likely to write ... code[foo[0]] is always an integer ... or ... if code[x < 0], the function returns ... ? (Here, whether the tag is inside or outside the brackets is irrelevant. How the particular bracket used is escaped does matter, though!) > Long tags have the syntax exemplified by > > arg name=s type=string:: > string to be parsed I'm confused: is this a syntax diagram or an example? I'm guessing the latter: you're talking about a long tag called "arg", which takes "name" and "type" arguments, and is followed by text describing the argument. In other words, this is similar to the Javadoc @param s string to be parsed except in Python we (so far) need a way to specify the argument type in the documentation, since it's not in the code. Is my interpretation correct? > The special long tag 'example' will not be intepreted by the program, > so > > example:: > ['this', 'is', 'a', 'list'] > > will work with no problems Looks reasonable. I assume the idea is that the text following "example::" will be set in a fixed-width font, indented and vertically separated from the surrounding text? How do you know when the example ends? (I know -- use "]]>" as the end marker! [Just kidding!]) > the special long tag 'code' will work the same way, but will be translated > to inline code: > > you can also write > code:: > (lambda x: [x])(5) > to return a list containing 5. Yuck. Inline code should be marked up inline. See my code[...] or code<...> examples above. > Paragraphs are seperated by new lines. You mean blank lines (/\n{2,}/), I hope... > Another long tag, which is only valid in a classe's docstring, are > 'instance-attrs' (unlike 'data', which would be class attributes). If we call them "class attributes" colloquially, why not call them "class attributes" in the documentation? Also, may I tentatively suggest just "attribute" for instance attributes, because they are far more common than class attributes? > All of the current semantic markup would be moved to short tags: > [module urllib], [class URLOpener] and [function urlopen] are all > examples. Good. That means just about the only use for the code[] tag would be, well, code (as opposed to names). Err, what about variables (including function parameters): is there special markup for them, or would you just use code[]? Greg -- Greg Ward - software developer gward@cnri.reston.va.us Corporation for National Research Initiatives 1895 Preston White Drive voice: +1-703-620-8990 Reston, Virginia, USA 20191-5434 fax: +1-703-620-0913 From Moshe Zadka Fri Feb 4 00:14:16 2000 From: Moshe Zadka (Moshe Zadka) Date: Fri, 4 Feb 2000 02:14:16 +0200 (IST) Subject: [Doc-SIG] Doc-String Syntax In-Reply-To: <20000203092153.A19176@cnri.reston.va.us> Message-ID: On Thu, 3 Feb 2000, Greg Ward wrote: > On 03 February 2000, Moshe Zadka said: > > There are two kinds of tags: "short" tags and "long" tags. > > Good distinction. Common markup -- emphasis, code snippets -- must be > dead easy to type. Except I'm still having trouble with code snippets -- mainly the escaping thing you noted. Let me just note one thing here about schedule of suggestions: Today I'll write up -- 1. The complete inline syntax 2. The complete intermediary format (this will be in XML) However, the OOL syntax, which will include "links" which are snarfed from a module documentation and is transformed to the intermediary format will wait a bit. SGML experts are hereby invited to mail me about minimization in SGML and how hard it is to support. The two minimizations which bother me most is test and > First, I was wrong; square versus angle brackets make very little > difference to typability. Hmmm...Greg, I see Randy has really gotten to you. Shouldn't we just meet at noon for a flamewar and settle it like real internetters? <0.8 wink> > However, for readability I like seeing the > tag separated from the text it tags, ie. I prefer "emph" to "[emph > foo]" not because of the shape of the brackets, but because the tag is > outside of the brackets, Fair enough > So if you're really keen on square brackets, how about this: > > It must be easy to emph[emphasise] certain words, and to mark others > as code[code] (or even whole code[code snippets]). The only problem is that it takes to much look ahead from a human to parse it. It's all right for one letters, which is what POD uses, but is hardly good enough for words. Let me just note my initial suggestion was [emph= like this] or [emph: like this]. I'm still debating. I'll have an answer ready this afternoon. > Oh, here's another thing to consider regarding the shape of brackets: > what kind of bracket is more likely to occur inside typical Python code > snippets? Ie. are you more likely to write > > ... code[foo[0]] is always an integer ... > > or > > ... if code[x < 0], the function returns ... > > ? (Here, whether the tag is inside or outside the brackets is > irrelevant. How the particular bracket used is escaped does matter, > though!) Amazingly enough, I did consider that. Note that in most Python code snippets, [ and ] are matched and < and > are not, so for most Python code snippets, the rule, "continue until matching ], but treat this as raw text" works wonderfully, hence it is less important how I escape it. BTW: my escape char will probably be @, because it isn't used in Python code, and is already used as special character by texinfo, so it won't be *that* novell. > > Long tags have the syntax exemplified by > > > > arg name=s type=string:: > > string to be parsed > > I'm confused: is this a syntax diagram or an example? I'm guessing the > latter And you're right. Bad example on my part, I just realize on rereading this that it *can* go both way. return type=string:: concatanation of all argment strings is probably a clearer example. > except in Python we (so far) need a way to specify the argument type in > the documentation, since it's not in the code. Is my interpretation > correct? Yes. Not that the type will stay a human-only string for a long time. Oh, the joys of quasy-defined interfaces like "file-like". > Looks reasonable. I assume the idea is that the text following > "example::" will be set in a fixed-width font, indented and vertically > separated from the surrounding text? How do you know when the example > ends? (I know -- use "]]>" as the end marker! [Just kidding!]) The indentation stops. Here's a snippet from a future docstring (Guido was kind enough to let me use his time machine) ''' Let us consider this example: example:: a, b = 1, 1L while 1: print a a, b = b, a+b This example runs [emph forever], computing the fibonacci function. ''' > Yuck. Inline code should be marked up inline. See my code[...] or > code<...> examples above. code will be special cased to be both long and short. > > Paragraphs are seperated by new lines. > > You mean blank lines (/\n{2,}/), I hope... Sorry, my bad. > > Another long tag, which is only valid in a classe's docstring, are > > 'instance-attrs' (unlike 'data', which would be class attributes). > > If we call them "class attributes" colloquially, why not call them > "class attributes" in the documentation? Also, may I tentatively > suggest just "attribute" for instance attributes, because they are far > more common than class attributes? Coherency. Look at this example module: ''' data name=factor: the factor to multiply our gurkles by. ''' factor = 100 def eggs(): '''return a well known string''' return 'eggs' class spam: ''' data name=gurkle: just a simple gurkle instance-data name=name: the instance's name ''' def camelot(self): '''return the name many times''' return self.gurkle*factor*self.name This way every namespace has data, which are things without their own doc-strings defined in the namespace. instance-data is a bit weird anyway in current day Python, since it is technically *not* a feature of the class: every instance can have different attributes, so I have no problems special casing the weird case. > Good. That means just about the only use for the code[] tag would be, > well, code (as opposed to names). Err, what about variables (including > function parameters): is there special markup for them, or would you > just use code[]? There will be a special markup. code[] is just for that: (more or less) valid snippets of Python. More to come later! -- Moshe Zadka . INTERNET: Learn what you know. Share what you don't. From Moshe Zadka Fri Feb 4 10:41:18 2000 From: Moshe Zadka (Moshe Zadka) Date: Fri, 4 Feb 2000 12:41:18 +0200 (IST) Subject: [Doc-SIG] DocStrings 0.3: Suggestion for documentation syntax (very long) Message-ID: Special tokens: @ -- escapes any character following it (i.e., @c is always translated to c) [ -- a short tag opener. Closed with a matching ] ::(newline) -- beginning a a long tag. everything until the indent level returns to that of the line which started the long tag is part of the contents. (newline)(newline) -- new paragraph. The syntax of short tags is '[' tagname ' ' contents ']' where contents is any valid snippet of docstring, with the exception of a long tag. The syntax of long tags is tagname (attr '=' value)*'::' contents Where contents is any valid snippet of docstring. List of tags, and where they are valid: code (both as long and short) -- anywhere example (long, no attributes) -- anywhere arg, return (attributes: name, type, default (optional) ) -- function docstring, never inside another long tag. rest-arg, kw-arg (long, no attributes) -- function docstring, never inside another long tag. data (attributes: name, type) -- class/module doc-string, never inside another long tag. exception (attributes: name) -- class/module doc-string, never inside another long tag. member (attributes: name, type) -- class doc-string, never inside another long tag. function, module, class, exception, var, method, keyword, member, pytype, file, url, arg (short tag) -- anywhere (these are for general markup syntax, so I've probably forgotten some): list (long tag) -- anywhere item (long tag) -- anywhere emph (short tag) -- anywhere (Note: there are some long tags with the same name as short tags. This poses no problems: the tags are different tags!) This was brief on purpose: I don't believe hardly anyone will actually read the spec: most people will just start writing doc-strings based on what they have seen. So, here is an example of a marked up module. I want to thank Gordon McMillan for providing a well-documented module: I just modified the syntax. (search for ======= if you want to skip the example module and get to the description of the intermediary format) """Utilities for comparing files and directories.""" import os import stat import statcache _cache = {} BUFSIZE=8*1024 def cmp(f1, f2, shallow=1,use_statcache=0): """Compare two files. arg name=f1 type=string:: First file name arg name=f2 type=string:: Second file name arg name=shallow type=bool default=1:: Just check stat signature (do not read the files). arg name=use_statcache type=bool default=0:: Do not stat() each file directly: go through the statcache module for more efficiency. return type=bool:: 1 if the files are the same, 0 otherwise. This function uses a cache for past comparisons and the results, with a cache invalidation mechanism relying on stale signatures. Of course, if [arg use_statcache] is true, this mechanism is defeated, and the cache will never grow stale. """ stat_function = (os.stat, statcache.stat)[use_statcache] s1, s2 = _sig(stat_function(f1)), _sig(stat_function(f2)) if s1[0]!=stat.S_IFREG or s2[0]!=stat.S_IFREG: return 0 if shallow and s1 == s2: return 1 if s1[1]!=s2[1]: return 0 result = _cache.get((f1, f2)) if result and (s1, s2)==result[:2]: return result[2] outcome = _do_cmp(f1, f2) _cache[f1, f2] = s1, s2, outcome return outcome def _sig(st): return (stat.S_IFMT(st[stat.ST_MODE]), st[stat.ST_SIZE], st[stat.ST_MTIME]) def _do_cmp(f1, f2): bufsize = BUFSIZE fp1 , fp2 = open(f1, 'rb'), open(f2, 'rb') while 1: b1, b2 = fp1.read(bufsize), fp2.read(bufsize) if b1!=b2: return 0 if not b1: return 1 # Directory comparison class. # class dircmp: """A class that manages the comparison of 2 directories. High level usage: list:: item:: [code x = dircmp(dir1, dir2)] item:: [code x.report()] -> prints a report on the differences between dir1 and dir2 item:: [code x.report_partial_closure()] -> prints report on differences between dir1 and dir2, and reports on common immediate subdirectories. item:: [code x.report_full_closure()] -> like report_partial_closure, but fully recursive. member name=left_list type=list:: files in [var dir1], except for the ones in [var hide] and [var ignore] lists. member name=right_list type=list:: files in [var dir2], except for the ones in [var hide] and [var ignore] lists. member name=common type=list:: names in both [var dir1] and [var dir2] member name=left_only type=list:: names in [var dir1] but not in [var dir2] member name=right_only type=list:: names in [var dir2] but not in [var dir1] member name=common_dirs type=list:: subdirectories in both [var dir1] and [var dir2]. member name=common_files type=list:: files in both [var dir1] and [var dir2]. member name=common_funny type=list:: names in both [var dir1] and [var dir2] where the type differs between [var dir1] and [var dir2], or the name is not [function stat]-able. member name=same_files type=list:: list of identical files. member name=diff_files type=list:: list of filenames which differ. member name=funny_files type=list:: list of files which could not be compared. member name=funny_files type=list:: list of files which could not be compared. member name=subdirs type=dictionary:: values are [class dircmp] objects, keyed by names in [member common_dirs]. """ def __init__(self, a, b, ignore=None, hide=None): # Initialize '''\ initialize an directory comparison arg name=a type=string:: first directory arg name=b type=string:: second directory arg name=ignore type=list or None:: list of directories to ignore when comparing. None means to ignore [code ['RCS', 'CVS', 'tags']]. arg name=hide type=list or None:: list of directories to hide when comparing. None means to hide defaults to [code [os.curdir, os.pardir]]. ''' self.left = a self.right = b if hide is None: self.hide = [os.curdir, os.pardir] # Names never to be shown else: self.hide = hide if ignore is None: self.ignore = ['RCS', 'CVS', 'tags'] # Names ignored in comparison else: self.ignore = ignore def phase0(self): # Compare everything except common subdirectories self.left_list = _filter(os.listdir(self.left), self.hide+self.ignore) self.right_list = _filter(os.listdir(self.right), self.hide+self.ignore) self.left_list.sort() self.right_list.sort() __p4_attrs = ('subdirs',) __p3_attrs = ('same_files', 'diff_files', 'funny_files') __p2_attrs = ('common_dirs', 'common_files', 'common_funny') __p1_attrs = ('common', 'left_only', 'right_only') __p0_attrs = ('left_list', 'right_list') def __getattr__(self, attr): if attr in self.__p4_attrs: self.phase4() elif attr in self.__p3_attrs: self.phase3() elif attr in self.__p2_attrs: self.phase2() elif attr in self.__p1_attrs: self.phase1() elif attr in self.__p0_attrs: self.phase0() else: raise AttributeError, attr return getattr(self, attr) def phase1(self): # Compute common names a_only, b_only = [], [] common = {} b = {} for fnm in self.right_list: b[fnm] = 1 for x in self.left_list: if b.get(x, 0): common[x] = 1 else: a_only.append(x) for x in self.right_list: if common.get(x, 0): pass else: b_only.append(x) self.common = common.keys() self.left_only = a_only self.right_only = b_only def phase2(self): # Distinguish files, directories, funnies self.common_dirs = [] self.common_files = [] self.common_funny = [] for x in self.common: a_path = os.path.join(self.left, x) b_path = os.path.join(self.right, x) ok = 1 try: a_stat = statcache.stat(a_path) except os.error, why: # print 'Can\'t stat', a_path, ':', why[1] ok = 0 try: b_stat = statcache.stat(b_path) except os.error, why: # print 'Can\'t stat', b_path, ':', why[1] ok = 0 if ok: a_type = stat.S_IFMT(a_stat[stat.ST_MODE]) b_type = stat.S_IFMT(b_stat[stat.ST_MODE]) if a_type <> b_type: self.common_funny.append(x) elif stat.S_ISDIR(a_type): self.common_dirs.append(x) elif stat.S_ISREG(a_type): self.common_files.append(x) else: self.common_funny.append(x) else: self.common_funny.append(x) def phase3(self): # Find out differences between common files xx = cmpfiles(self.left, self.right, self.common_files) self.same_files, self.diff_files, self.funny_files = xx def phase4(self): # Find out differences between common subdirectories # A new dircmp object is created for each common subdirectory, # these are stored in a dictionary indexed by filename. # The hide and ignore properties are inherited from the parent self.subdirs = {} for x in self.common_dirs: a_x = os.path.join(self.left, x) b_x = os.path.join(self.right, x) self.subdirs[x] = dircmp(a_x, b_x, self.ignore, self.hide) def phase4_closure(self): # Recursively call phase4() on subdirectories self.phase4() for x in self.subdirs.keys(): self.subdirs[x].phase4_closure() def report(self): '''\ Print a report on the differences between [member a] and [member b]. Output format is purposely lousy ''' print 'diff', self.left, self.right if self.left_only: self.left_only.sort() print 'Only in', self.left, ':', self.left_only if self.right_only: self.right_only.sort() print 'Only in', self.right, ':', self.right_only if self.same_files: self.same_files.sort() print 'Identical files :', self.same_files if self.diff_files: self.diff_files.sort() print 'Differing files :', self.diff_files if self.funny_files: self.funny_files.sort() print 'Trouble with common files :', self.funny_files if self.common_dirs: self.common_dirs.sort() print 'Common subdirectories :', self.common_dirs if self.common_funny: self.common_funny.sort() print 'Common funny cases :', self.common_funny def report_partial_closure(self): '''Print reports on [arg self] and on [member subdirs]''' self.report() for x in self.subdirs.keys(): print self.subdirs[x].report() def report_full_closure(self): '''Report on [var self] and [member subdirs] recursively.''' self.report() for x in self.subdirs.keys(): print self.subdirs[x].report_full_closure() # Compare common files in two directories. # Return: # - files that compare equal # - files that compare different # - funny cases (can't stat etc.) # def cmpfiles(a, b, common): """Compare common files in two directories. arg name=a type=string:: name of first directory. arg name=b type=string:: name of second directory. arg name=common type=list:: names of common files to be compared return type=tuple:: list:: item:: files that compare equal item:: files that are different item:: filenames that aren't regular files. """ res = ([], [], []) for x in common: res[_cmp(os.path.join(a, x), os.path.join(b, x))].append(x) return res # Compare two files. # Return: # 0 for equal # 1 for different # 2 for funny cases (can't stat, etc.) # def _cmp(a, b): try: return not abs(cmp(a, b)) except os.error: return 2 # Return a copy with items that occur in skip removed. # def _filter(list, skip): result = [] for item in list: if item not in skip: result.append(item) return result # Demonstration and testing. # def demo(): import sys import getopt options, args = getopt.getopt(sys.argv[1:], 'r') if len(args) <> 2: raise getopt.error, 'need exactly two args' dd = dircmp(args[0], args[1]) if ('-r', '') in options: dd.report_full_closure() else: dd.report() if __name__ == '__main__': demo() ======= The intermediary format is XML. I have not yet written a DTD, but this is a general sketch -- The root element is "module" Inside "module", you can have "description", "class", "function", "exception" and "data". Inside "class", you can have "description", "class", "function", "exception", "function", "data" and "member" Inside "function", and "description", "arg", "kw-arg", "rest-arg". and "return" elements. Inside "exception", there is a "description". Inside "data", there is a "description". Inside "member", there is a "description". Inside "arg", "kw-arg", "rest-arg" and "return" there is a "description" The following elements have a "type" attribute: "member", "data", "arg", "return". The following elements have a "name" attribute: "class", "function", "exception", "data", "member", "arg". Inside a "description" there are "p" elements. Inside "p" element, there is PCDATA, "code" element, "example" element, "module-ref", "class-ref", "exception-ref", "member-ref", "data-ref", "function-ref", "arg-ref", "var", "keyword", "pytype", "file", "url", "emph" and "list". Inside the *-ref elements, "code", "example", "var", "keyword", "pytype", "file" and "url" there is PCDATA. Inside "list" there are "item" elements. The content model of "item" and "emph" is the same as that for "p". ============= The OOL format will be similar to the intermediary format, with two important changes: 1. It will have "link" elements, which allow it to pull data out of a module doc-strings. These link elements should be powerful enough so that for most modules, a canonical OOL file will suffice. 2. It will have some SGML minimization to make writing it less painful. Please comment! -- Moshe Zadka . INTERNET: Learn what you know. Share what you don't. From tony@lsl.co.uk Fri Feb 4 11:40:42 2000 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Fri, 4 Feb 2000 11:40:42 -0000 Subject: [Doc-SIG] DocStrings 0.3: Suggestion for documentation syntax (very long) In-Reply-To: Message-ID: <002c01bf6f04$ab116720$f0c809c0@lslp7o.lsl.co.uk> (Apologies to Moshe, to whom I inadvertently sent a separate copy of this - the perils of hitting "Reply" instead of "Reply All" in Outlook ) Either I'm terminally confused (I hope that's it), or else several people must have been murdered at IPC8... If I'm understanding things, Moshe is proposing (officially) a text-intensive form of markup for use within doc strings. This is designed to be easily mapped to (for instance) XML, and is nearly as verbose. If I have understood that correctly, then I have two immediate comments: 1. Why don't we just use XML? - the proposed format is almost as verbose, and has the disadvantage that it is a new format "for the sake of it" [1]. 2. What happened to all the people who were going to refuse to use such a format if it were more verbose than the proposal being circulated pre-IPC8 (which I thouhgt was generally agreed on)? There's been no explanation of why they've suddenly reversed position, if they indeed have. As a smaller note, Moshe seems to be leaving out "cross references" as unwanted in the inline documentation, whereas I would have thought it's as necessary there as out of line... [1] If we're going to have our own format, it has to give *significant* benefits to readability/typability/etc, because having to translate into something else to determine if it is legitimate (in the "valid XML" sense) already makes it that much harder to correlate errors back to the original text. I don't see those benefits here. If this proposal is serious, can we please have an explanation of why the various points raised in the pre-IPC8 discussion are being junked (things like wanting list elements not to be separated by blank lines, wanting to keep the typing/markup mode limited, Tim Peters' points about not needing to markup code blocks if they had >>>/... markers, etc.). Desperately hoping I've missed LOTS of points, Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.demon.co.uk/ My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) [I've read it twice. I've thought it over. I'm sending it anyway.] From pf@artcom-gmbh.de Fri Feb 4 18:28:45 2000 From: pf@artcom-gmbh.de (Peter Funk) Date: Fri, 4 Feb 2000 19:28:45 +0100 (MET) Subject: [Doc-SIG] DocStrings 0.3: Suggestion for documentation syntax (very long) In-Reply-To: from Moshe Zadka at "Feb 4, 2000 12:41:18 pm" Message-ID: Hi! Moshe Zadka: [...] > def cmp(f1, f2, shallow=1,use_statcache=0): > """Compare two files. > > arg name=f1 type=string:: > First file name > > arg name=f2 type=string:: > Second file name > > arg name=shallow type=bool default=1:: > Just check stat signature (do not read the files). > > arg name=use_statcache type=bool default=0:: > Do not stat() each file directly: go through > the statcache module for more efficiency. > > return type=bool:: > 1 if the files are the same, 0 otherwise. > > This function uses a cache for past comparisons and the results, > with a cache invalidation mechanism relying on stale signatures. > Of course, if [arg use_statcache] is true, this mechanism is defeated, > and the cache will never grow stale. > > """ [...] > def report_partial_closure(self): > '''Print reports on [arg self] and on [member subdirs]''' [...] > Please comment! I don't like it. I don't believe, that there will ever exist much Python sourcecode containing such doc strings. I'm watching the CVS-checkin mailing list and Guido has just committed three large batches of std lib modules containing much nicer and smaller doc strings. These will definitely set standards for other people writing inline doc strings, as soon as Python 1.6 comes out. I can't imagine, that the average Joe Random Python programmer will ever bother to write inline doc in such a complex format as you proposed. I am sad to see, that you have spend a great deal of energy and time on this spec. May be I've missed something important? Maybe the goal of the whole effort should have been made clearer? The 'future direction' chapter of the current Python documentation and the status report posted by Fred Drake J. recently in this SIG descibe the goal not so clear (at least not for me). Maybe I've not enough knowledge the planned workflows when dealing with python documentation. The OOL documentation of Pythons std library is remarkable good and can only be improved in minor details. Therefore I can't see what a 1:1 relation between OOL doc and inline doc strings would buy us? Sure, there is some content overlap between OOL and doc strings, which intrduces some double work for the maintainers. But often the OOL is more elaborated (so should it be), contains tables and other material, which would only bloat doc strings and distract from the code. What about Tkinter? There is Fredrik Lundhs effort, which is still incomplete in some minor areas, but was nevertheless a very valuable reference for me. Unfortunately it can't be included into the python distribution because of copyright issues AFAIK. Inline doc strings are pratically nonexistent in Tkinter. Who will ever volunteer to write some, if they must be written in an ugly and hard to learn format? What about free third party packages? Many have no doc at all. Others have rather good documentation (e.g. Pmw which is only incomplete in some areas). Other packages have doc strings, but the format varies much depending on the taste of the author. That is situation now with an exponetially growing set of new open source Python packages written all over the world. I don't believe that many people are eager to rewrite their doc strings according to a new spec looking radically other than normal text. In the meantime Java has Javadoc and its capabilities are remarkable compared to what Python programmers can use today. So IMOHO it doesn't make much sense to develop a very complex new grammar for doc strings. This effort should be better spend on a set of simple grammars and modular StructuredText like tools, which are able to extract a reasonable doctree structure from existing doc strings. Danilo's 'python-doc'-Package has taken some steps into this direction. However I am not really happy with the current implementation, which still relies heavily on Jim Fultons original StructuredText.py and does further recognition of tags on the paragraph structure spit out by StructuredText. But it is better than gendoc and much better than having nothing at all. So far Daniel L. has certainly provided a good starting point. May be John Aycocks easy to use generic parser could be used to build flexible and customizable doc string eaters? So anybody interested in his own complicated and sophisticated doc string grammar could easily hack up his parser, while we can stay with simple and easy to write doc string formats like those written by Guido and others. Okay: that was sure a demoralizing rant. It's just my peronal view. Regards, Peter -- Peter Funk, Oldenburger Str.86, 27777 Ganderkesee, Tel: 04222 9502 70, Fax: -60 From Moshe Zadka Fri Feb 4 18:44:44 2000 From: Moshe Zadka (Moshe Zadka) Date: Fri, 4 Feb 2000 20:44:44 +0200 (IST) Subject: [Doc-SIG] more user testing Message-ID: This message is in MIME format. The first part should be readable text, while the remaining parts are likely unreadable without MIME-aware tools. Send mail to mime@docserver.cac.washington.edu for more info. ---559023410-959030623-949689884=:4222 Content-Type: TEXT/PLAIN; charset=US-ASCII I've tested both painfullness and time of my inline docs suggestion. On a whim (with no relation to the doc-sig) I wrote a small generic dict module. Then I decided to document it and see how much it puts me off. I discovered that it was pretty easy. (This was with vi -- if you're using an editor that's less friendly it might be harder). I then decided to re-do fileinput.py's doc-string (it has only a module level doc-string) in the new output. I've discovered that most of my time was in filling out neccessary information, rather then in markup technicalities. Attached are the results of this test. It rather suprised me, because it reminded me more of writing LaTeX then writing HTML or XML: I did both pretty heavily be hand, and LaTeX writing is much easier. I have a small request: would anyone be willing to take a doc-string'ed module a redo it in my suggested syntax and return to tell us of the experience? (See, Randy got to me too) -- Moshe Zadka . INTERNET: Learn what you know. Share what you don't. ---559023410-959030623-949689884=:4222 Content-Type: TEXT/PLAIN; charset=US-ASCII; name="fileinput.py" Content-ID: Content-Description: Content-Transfer-Encoding: BASE64 IiIiSGVscGVyIGNsYXNzIHRvIHF1aWNrbHkgd3JpdGUgYSBsb29wIG92ZXIg YWxsIHN0YW5kYXJkIGlucHV0IGZpbGVzLg0KDQpUeXBpY2FsIHVzZSBpczoN Cg0KICAgIGV4YW1wbGU6Og0KICAgICAgICBpbXBvcnQgZmlsZWlucHV0DQog ICAgICAgIGZvciBsaW5lIGluIGZpbGVpbnB1dC5pbnB1dCgpOg0KICAgICAg ICAgICAgcHJvY2VzcyhsaW5lKQ0KDQpUaGlzIGl0ZXJhdGVzIG92ZXIgdGhl IGxpbmVzIG9mIGFsbCBmaWxlcyBsaXN0ZWQgaW4gW3N5cy5hcmd2WzE6XV0s DQpkZWZhdWx0aW5nIHRvIFt2YXIgc3lzLnN0ZGluXSBpZiB0aGUgbGlzdCBp cyBlbXB0eS4gIElmIGEgZmlsZW5hbWUgaXMgDQpbY29kZSAnLSddIGl0IGlz IGFsc28gcmVwbGFjZWQgYnkgW2NvZGUgc3lzLnN0ZGluXS4gIFRvIHNwZWNp ZnkgYW4gYWx0ZXJuYXRpdmUgDQpsaXN0IG9mIGZpbGVuYW1lcywgcGFzcyBp dCBhcyB0aGUgYXJndW1lbnQgdG8gW2Z1bmN0aW9uIGlucHV0KCldLiAgQSBz aW5nbGUgDQpmaWxlIG5hbWUgaXMgYWxzbyBhbGxvd2VkLg0KDQpGdW5jdGlv bnMgW2Z1bmN0aW9uIGZpbGVuYW1lKCldLCBbZnVuY3Rpb24gbGluZW5vKCld IHJldHVybiB0aGUgZmlsZW5hbWUgYW5kIA0KY3VtdWxhdGl2ZSBsaW5lIG51 bWJlciBvZiB0aGUgbGluZSB0aGF0IGhhcyBqdXN0IGJlZW4gcmVhZDsgDQpb ZnVuY3Rpb24gZmlsZWxpbmVubygpXSByZXR1cm5zIGl0cyBsaW5lIG51bWJl ciBpbiB0aGUgY3VycmVudCBmaWxlOyANCltmdW5jdGlvbiBpc2ZpcnN0bGlu ZSgpXSByZXR1cm5zIHRydWUgaWZmIHRoZSBsaW5lIGp1c3QgcmVhZCBpcyB0 aGUgZmlyc3QgbGluZSANCm9mIGl0cyBmaWxlOyBbZnVuY3Rpb24gaXNzdGRp bigpXSByZXR1cm5zIHRydWUgaWZmIHRoZSBsaW5lIHdhcyByZWFkIGZyb20g DQpbdmFyIHN5cy5zdGRpbl0uICBGdW5jdGlvbiBbZnVuY3Rpb24gbmV4dGZp bGUoKV0gY2xvc2VzIHRoZQ0KY3VycmVudCBmaWxlIHNvIHRoYXQgdGhlIG5l eHQgaXRlcmF0aW9uIHdpbGwgcmVhZCB0aGUgZmlyc3QgbGluZSBmcm9tDQp0 aGUgbmV4dCBmaWxlIChpZiBhbnkpOyBsaW5lcyBub3QgcmVhZCBmcm9tIHRo ZSBmaWxlIHdpbGwgbm90IGNvdW50DQp0b3dhcmRzIHRoZSBjdW11bGF0aXZl IGxpbmUgY291bnQ7IHRoZSBmaWxlbmFtZSBpcyBub3QgY2hhbmdlZCB1bnRp bA0KYWZ0ZXIgdGhlIGZpcnN0IGxpbmUgb2YgdGhlIG5leHQgZmlsZSBoYXMg YmVlbiByZWFkLiAgRnVuY3Rpb24gDQpbZnVuY3Rpb24gY2xvc2UoKV0gY2xv c2VzIHRoZSBzZXF1ZW5jZS4NCg0KQmVmb3JlIGFueSBsaW5lcyBoYXZlIGJl ZW4gcmVhZCwgW2Z1bmN0aW9uIGZpbGVuYW1lKCldIHJldHVybnMgW3ZhciBO b25lXSBhbmQgDQpib3RoIGxpbmUgbnVtYmVycyBhcmUgemVybzsgW2Z1bmN0 aW9uIG5leHRmaWxlKCldIGhhcyBubyBlZmZlY3QuICBBZnRlciBhbGwgDQps aW5lcyBoYXZlIGJlZW4gcmVhZCwgW2Z1bmN0aW9uIGZpbGVuYW1lKCldIGFu ZCB0aGUgbGluZSBudW1iZXIgZnVuY3Rpb25zIA0KcmV0dXJuIHRoZSB2YWx1 ZXMgcGVydGFpbmluZyB0byB0aGUgbGFzdCBsaW5lIHJlYWQ7IFtmdW5jdGlv biBuZXh0ZmlsZSgpXSBoYXMgDQpubyBlZmZlY3QuDQoNCkFsbCBmaWxlcyBh cmUgb3BlbmVkIGluIHRleHQgbW9kZS4gIElmIGFuIEkvTyBlcnJvciBvY2N1 cnMgZHVyaW5nDQpvcGVuaW5nIG9yIHJlYWRpbmcgYSBmaWxlLCB0aGUgW2V4 Y2VwdGlvbiBJT0Vycm9yXSBleGNlcHRpb24gaXMgcmFpc2VkLg0KDQpJZiBb dmFyIHN5cy5zdGRpbl0gaXMgdXNlZCBtb3JlIHRoYW4gb25jZSwgdGhlIHNl Y29uZCBhbmQgZnVydGhlciB1c2Ugd2lsbA0KcmV0dXJuIG5vIGxpbmVzLCBl eGNlcHQgcGVyaGFwcyBmb3IgaW50ZXJhY3RpdmUgdXNlLCBvciBpZiBpdCBo YXMgYmVlbg0KZXhwbGljaXRseSByZXNldCAoZS5nLiB1c2luZyBbY29kZSBz eXMuc3RkaW4uc2VlaygwKSldLg0KDQpFbXB0eSBmaWxlcyBhcmUgb3BlbmVk IGFuZCBpbW1lZGlhdGVseSBjbG9zZWQ7IHRoZSBvbmx5IHRpbWUgdGhlaXIN CnByZXNlbmNlIGluIHRoZSBsaXN0IG9mIGZpbGVuYW1lcyBpcyBub3RpY2Vh YmxlIGF0IGFsbCBpcyB3aGVuIHRoZQ0KbGFzdCBmaWxlIG9wZW5lZCBpcyBl bXB0eS4NCg0KSXQgaXMgcG9zc2libGUgdGhhdCB0aGUgbGFzdCBsaW5lIG9m IGEgZmlsZSBkb2Vzbid0IGVuZCBpbiBhIG5ld2xpbmUNCmNoYXJhY3Rlcjsg b3RoZXJ3aXNlIGxpbmVzIGFyZSByZXR1cm5lZCBpbmNsdWRpbmcgdGhlIHRy YWlsaW5nDQpuZXdsaW5lLg0KDQpDbGFzcyBbY2xhc3MgRmlsZUlucHV0XSBp cyB0aGUgaW1wbGVtZW50YXRpb247IGl0cyBtZXRob2RzIA0KW2Z1bmN0aW9u IGZpbGVuYW1lKCldLCBbZnVuY3Rpb24gbGluZW5vKCldLCBbZnVuY3Rpb24g ZmlsZWxpbmUoKV0sIA0KW2Z1bmN0aW9uIGlzZmlyc3RsaW5lKCldLCBbZnVu Y3Rpb24gaXNzdGRpbigpXSwgW2Z1bmN0aW9uIG5leHRmaWxlKCldIGFuZCAN CltmdW5jdGlvbiBjbG9zZSgpXSBjb3JyZXNwb25kIHRvIHRoZSBmdW5jdGlv bnMgaW4gdGhlIG1vZHVsZS4gIEluIGFkZGl0aW9uIGl0IA0KaGFzIGEgW2Z1 bmN0aW9uIHJlYWRsaW5lKCldIG1ldGhvZCB3aGljaCByZXR1cm5zIHRoZSBu ZXh0IGlucHV0IGxpbmUsIGFuZCBhDQpbZnVuY3Rpb24gX19nZXRpdGVtX18o KV0gbWV0aG9kIHdoaWNoIGltcGxlbWVudHMgdGhlIHNlcXVlbmNlIGJlaGF2 aW9yLiAgVGhlDQpzZXF1ZW5jZSBtdXN0IGJlIGFjY2Vzc2VkIGluIHN0cmlj dGx5IHNlcXVlbnRpYWwgb3JkZXI7IHNlcXVlbmNlDQphY2Nlc3MgYW5kIFtm dW5jdGlvbiByZWFkbGluZSgpXSBjYW5ub3QgYmUgbWl4ZWQuDQoNCk9wdGlv bmFsIGluLXBsYWNlIGZpbHRlcmluZzogaWYgdGhlIGtleXdvcmQgYXJndW1l bnQgW3ZhciBpbnBsYWNlXSBpcyBwYXNzZWQNCnRvIFtmdW5jdGlvbiBpbnB1 dCgpXSB3aXRoIGEgdHJ1ZSB2YWx1ZSBvciB0byB0aGUgW2NsYXNzIEZpbGVJ bnB1dF0gDQpjb25zdHJ1Y3RvciwgdGhlIGZpbGUgaXMgbW92ZWQgdG8gYSBi YWNrdXAgZmlsZSBhbmQgc3RhbmRhcmQgb3V0cHV0IGlzIA0KZGlyZWN0ZWQg dG8gdGhlIGlucHV0IGZpbGUuICBUaGlzIG1ha2VzIGl0IHBvc3NpYmxlIHRv IHdyaXRlIGEgZmlsdGVyIHRoYXQgDQpyZXdyaXRlcyBpdHMgaW5wdXQgZmls ZSBpbiBwbGFjZS4gIElmIHRoZSBrZXl3b3JkIGFyZ3VtZW50IFt2YXIgYmFj a3VwXSBpcyANCnBhc3NlZCB0byBbZnVuY3Rpb24gaW5wdXQoKV0gb3IgdG8g dGhlIGNvbnN0cnVjdG9yIG9mIFtjbGFzcyBGaWxlSW5wdXRdLA0KaXQgaXMg dHJlYXRlZCBhcyB0aGUgZXh0ZW5zaW9uIGZvciB0aGUgYmFja3VwIGZpbGUs IGFuZCB0aGUgYmFja3VwDQpmaWxlIHJlbWFpbnMgYXJvdW5kOyBieSBkZWZh dWx0LCB0aGUgZXh0ZW5zaW9uIGlzIFtjb2RlICIuYmFrIl0gYW5kIGl0IGlz DQpkZWxldGVkIHdoZW4gdGhlIG91dHB1dCBmaWxlIGlzIGNsb3NlZC4gIElu LXBsYWNlIGZpbHRlcmluZyBpcw0KZGlzYWJsZWQgd2hlbiBzdGFuZGFyZCBp bnB1dCBpcyByZWFkLiAgWFhYIFRoZSBjdXJyZW50IGltcGxlbWVudGF0aW9u DQpkb2VzIG5vdCB3b3JrIGZvciBNUy1ET1MgOCszIGZpbGVzeXN0ZW1zLg0K DQpYWFggUG9zc2libGUgYWRkaXRpb25zOg0KDQpsaXN0OjoNCiAgICBpdGVt Ojogb3B0aW9uYWwgW21vZHVsZSBnZXRvcHRdIGFyZ3VtZW50IHByb2Nlc3Np bmcNCiAgICBpdGVtOjogc3BlY2lmeSBvcGVuIG1vZGUgKFtjb2RlICdyJ10g b3IgW2NvZGUgJ3JiJ10pDQogICAgaXRlbTo6IHNwZWNpZnkgYnVmZmVyIHNp emUNCiAgICBpdGVtOjogW2Z1bmN0aW9uIGZpbGVubygpXQ0KICAgIGl0ZW06 OiBbZnVuY3Rpb24gaXNhdHR5KCldDQogICAgaXRlbTo6IFtmdW5jdGlvbiBy ZWFkKCldLCBbZnVuY3Rpb24gcmVhZChzaXplKV0sIGV2ZW4gW2Z1bmN0aW9u IHJlYWRsaW5lcygpXQ0KIiIiDQo= ---559023410-959030623-949689884=:4222 Content-Type: TEXT/PLAIN; charset=US-ASCII; name="GeneralDict.py" Content-ID: Content-Description: Content-Transfer-Encoding: BASE64 Y2xhc3MgR2VuZXJhbERpY3Q6DQoNCgknJydcDQoJQSBkaWN0aW9uYXJ5IHdo aWNoIGNhbiBiZSBpbmRleGVkIGJ5IGFueSB0eXBlLCBpbmNsdWRpbmcgbXV0 YWJsZSB0eXBlcy4gDQoNCglUaGlzIGNsYXNzIGltcGxlbWVudHMgYSBkaWN0 aW9uYXJ5IHdoaWNoIGNhbiBiZSBpbmRleGVkIGJ5IGFueSB0eXBlLA0KCWlu Y2x1ZGluZyBtdXRhYmxlcyBsaWtlIGxpc3RzIGFuZCBkaWN0aW9uYXJpZXMu IA0KCScnJw0KCQ0KDQoJZGVmIF9faW5pdF9fKHNlbGYpOg0KCQlzZWxmLl9k aWN0PXt9DQoJCXNlbGYuX3RlbXBfa2V5cz17fQ0KDQoJZGVmIF9fZ2V0aXRl bV9fKHNlbGYsIG5hbWUpOg0KCQknJydcDQoJCWdldCBhbiBpdGVtIGJ5IG5h bWUuDQoNCgkJW2VtcGggY2F2ZWF0XTogaWYgW3ZhciBuYW1lXSBpcyBtdXRh YmxlLCB0aGVuIG9iamVjdA0KCQllcXVhbGl0eSBhbW9uZyBrZXlzIGlzIG5v dCBlbm91Z2guIEluIG90aGVyIHdvcmRzLA0KCQlleGFtcGxlOjoNCgkJCT4+ PiBhID0gR2VuZXJhbERpY3QoKQ0KCQkJPj4+IGFbWzEsMiwzXV09MQ0KCQkJ Pj4+IHRyeToNCgkJCS4uLiAgICAgYVtbMSwyLDNdXQ0KCQkJLi4uIGV4Y2Vw dCBLZXlFcnJvcjoNCgkJCS4uLiAgICAgcHJpbnQgIkNhdmVhdCEiDQoJCQku Li4gDQoJCQlDYXZlYXQhDQoNCgkJYXJnIG5hbWU9bmFtZTo6DQoJCQl0aGUg bmFtZSB0byBsb29rdXAgaW4gdGhlIGRpY3Rpb25hcnkNCgkJJycnDQoJCXRy eToNCgkJCWhhc2gobmFtZSkNCgkJZXhjZXB0IFR5cGVFcnJvcjoNCgkJCXJl dHVybiBzZWxmLl9kaWN0W2lkKG5hbWUpXQ0KCQllbHNlOg0KCQkJcmV0dXJu IHNlbGYuX2RpY3RbMSwgbmFtZV0NCg0KCWRlZiBfX3NldGl0ZW1fXyhzZWxm LCBuYW1lLCB2YWx1ZSk6DQoJCScnJ1wNCgkJc2V0IGEgbmFtZS92YWx1ZSBt YXBwaW5nDQoNCgkJYXJnIG5hbWU9bmFtZTo6DQoJCQl0aGUgbmFtZSB0byBh c3NvY2lhdGUgYSB2YWx1ZSB3aXRoLg0KDQoJCWFyZyBuYW1lPXZhbHVlOjoN CgkJCXRoZSB2YWx1ZSB0byBhc3NvY2lhdGUgd2l0aCB0aGUgbmFtZQ0KCQkn JycNCgkJdHJ5Og0KCQkJc2VsZi5fZGljdFsxLCBuYW1lXT12YWx1ZQ0KCQll eGNlcHQgVHlwZUVycm9yOg0KCQkJIyBrZWVwIGEgcmVmZXJlbmNlIHRvICdu YW1lJw0KCQkJc2VsZi5fdGVtcF9rZXlzW2lkKG5hbWUpXT1uYW1lIA0KCQkJ c2VsZi5fZGljdFtpZChuYW1lKV09dmFsdWUNCg0KCWRlZiBfX2RlbGl0ZW1f XyhzZWxmLCBuYW1lKToNCgkJJycnXA0KCQlkZWxldGUgYW4gYXNzb2NpYXRp b24gZnJvbSB0aGUgbWFwcGluZy4NCg0KCQlhcmcgbmFtZT1uYW1lOjoNCgkJ CXRoZSBuYW1lIHRvIGRlbGV0ZSB0aGUgYXNzb2NpYXRpb24gdG8uDQoJCScn Jw0KCQkjIEknZCByYXRoZXIgZXhwbGljaXRseSB0ZXN0IGZvciBoYXNoLCBi ZWNhdXNlDQoJCSMgb3RoZXJ3aXNlIHRoZSBleGNlcHRpb25zIGdldCBtaXhl ZA0KCQl0cnk6DQoJCQloYXNoKG5hbWUpDQoJCWV4Y2VwdCBUeXBlRXJyb3I6 DQoJCQlkZWwgc2VsZi5fZGljdFtpZChuYW1lKV0NCgkJCWRlbCBzZWxmLl90 ZW1wX2tleXNbaWQobmFtZSldDQoJCWVsc2U6DQoJCQlkZWwgc2VsZi5fZGlj dFsxLCBuYW1lXQ0KDQoJZGVmIGtleXMoc2VsZik6DQoJCScnJ3JldHVybiBh IGxpc3Qgb2YgYWxsIGtleXMgaW4gdGhlIG1hcHBpbmcnJycNCgkJcmV0ID0g W10NCgkJZm9yIGsgaW4gc2VsZi5fZGljdC5rZXlzKCk6DQoJCQlpZiB0eXBl KGspIGlzIHR5cGUoKCkpOg0KCQkJCXJldC5hcHBlbmQoa1sxXSkNCgkJCWVs c2U6DQoJCQkJcmV0LmFwcGVuZChzZWxmLl90ZW1wX2tleXNba10pDQoJCXJl dHVybiByZXQNCg0KDQpkZWYgX3Rlc3QoKToNCglhPUdlbmVyYWxEaWN0KCkN CglhWyBbMSwgMiwgM10gXSA9IDENCglzZXEgPSBrID0gYS5rZXlzKClbMF0N Cglhc3NlcnQgYVtrXSA9PSAxDQoJYVsgMiBdID0gNg0KCWZvciBrIGluIGEu a2V5cygpOg0KCQlpZiBrID09IDI6DQoJCQlhc3NlcnQgYVtrXSA9PSA2DQoJ CWlmIGsgPT0gWzEsIDIsIDNdOg0KCQkJYXNzZXJ0IGFba10gPT0gMQ0KCWRl bCBhW3NlcV0NCglhc3NlcnQgbGVuKGEua2V5cygpKSA9PSAxDQoJYXNzZXJ0 IGFbYS5rZXlzKClbMF1dID09IDYNCg0KaWYgX19uYW1lX18gPT0gJ19fbWFp bl9fJzogDQoJX3Rlc3QoKQ0K ---559023410-959030623-949689884=:4222-- From gward@cnri.reston.va.us Fri Feb 4 19:10:55 2000 From: gward@cnri.reston.va.us (Greg Ward) Date: Fri, 4 Feb 2000 14:10:55 -0500 Subject: [Doc-SIG] more user testing In-Reply-To: ; from moshez@math.huji.ac.il on Fri, Feb 04, 2000 at 08:44:44PM +0200 References: Message-ID: <20000204141054.E19977@cnri.reston.va.us> On 04 February 2000, Moshe Zadka said: > I've tested both painfullness and time of my inline docs suggestion. > On a whim (with no relation to the doc-sig) I wrote a small generic dict > module. Then I decided to document it and see how much it puts me off. I > discovered that it was pretty easy. (This was with vi -- if you're using > an editor that's less friendly it might be harder). I hate to chime in with the second negative feedback of the day, but I don't like it either. You don't have to look much further than this paragraph to see why: > Functions [function filename()], [function lineno()] return the > filename and cumulative line number of the line that has just been > read; [function filelineno()] returns its line number in the current > file; [function isfirstline()] returns true iff the line just read is > the first line of its file; [function isstdin()] returns true iff the > line was read from [var sys.stdin]. Function [function nextfile()] > closes the current file so that the next iteration will read the first > line from the next file (if any); lines not read from the file will > not count towards the cumulative line count; the filename is not > changed until after the first line of the next file has been read. > Function [function close()] closes the sequence. In a word, yuck. I'll grant that this is a long way from XML in terms of sheer unreadability, but it's still pretty opaque. I'm going to take a risk by putting on a Tom Christiansen hat (along with some asbestos underwear) and make a bold assertion: The doc parser should know that 'filename', 'lineno', etc. are function names and act accordingly. I.e., it shouldn't be up to the module author to say "foo is a function name", when he has already *done so* by typing "def foo" somewhere in the file. This implies a lot of cooperation between the parse tree and the documentation processor. So be it. This is Python, at least there *is* a parse tree available to mere mortals. I would much prefer to write that paragraph as Functions 'filename()', 'lineno()' return the filename and cumulative line number of the line that has just been read; 'filelineno()' returns its line number in the current file; 'isfirstline()' returns true iff the line just read is the first line of its file; 'isstdin()' returns true iff the line was read from 'sys.stdin'. Function 'nextfile()' closes the current file so that the next iteration will read the first line from the next file (if any); lines not read from the file will not count towards the cumulative line count; the filename is not changed until after the first line of the next file has been read. Function 'close()' closes the sequence. ...although I am perfectly willing to entertain delimiters other than '' for identifiers (or code snippets, or whatever you want to call them). > Attached are the results of this test. > It rather suprised me, because it reminded me more of writing LaTeX then > writing HTML or XML: I did both pretty heavily be hand, and LaTeX writing > is much easier. I agree there: I'd rather type (and read) markup closer in spirit and conciseness to LaTeX than to *ML. Greg From Manuel Gutierrez Algaba Fri Feb 4 21:10:12 2000 From: Manuel Gutierrez Algaba (Manuel Gutierrez Algaba) Date: Fri, 4 Feb 2000 21:10:12 +0000 (GMT) Subject: [Doc-SIG] DocStrings 0.3: Suggestion for documentation syntax (very long) In-Reply-To: <002c01bf6f04$ab116720$f0c809c0@lslp7o.lsl.co.uk> Message-ID: On Fri, 4 Feb 2000, Tony J Ibbs (Tibs) wrote: > (Apologies to Moshe, to whom I inadvertently sent a separate copy of this - > the perils of hitting "Reply" instead of "Reply All" in Outlook ) > > > Either I'm terminally confused (I hope that's it), or else several people > must have been murdered at IPC8... Since the beginning, I knew that the "official" line will succeed and any other "lines" ( some of them with a lot of common sense) will be easily erased: - eval docstrings - hyperreferences - indexes I proposed or I contributed an approach: http://www.ctv.es/USERS/irmina/mandoc/mandoc.py but I didn't finish it, partly because I got bored, partly because I knew the official line had XML in mind. > > If I'm understanding things, Moshe is proposing (officially) a > text-intensive form of markup for use within doc strings. This is designed > to be easily mapped to (for instance) XML, and is nearly as verbose. If I > have understood that correctly, then I have two immediate comments: > > 1. Why don't we just use XML? - the proposed format is almost as verbose, > and has the disadvantage that it is a new format "for the sake of it" [1]. The question is which are the benefits of a XML-ish doc string system? Certainly, the casual programmer is not going to write doc in a grammar that is far more complex than the language ( python) itself. So I think, this so complex doc strings aims other objectives, it's intended to be robust, and to be used by "proffesional" people. When I mean "professional" I mean what people thinks professional is. Professional usually means little complex but clearly defined and massively used. Most people would consider Java more professional than python, because it's more used and less complex ( or its complexity is biased towards "professional things"). Visual Basic and Windows are very "professional" too. "Professional" always involves two words: "fashionable", "stupid-enough". XML is both: fashionable and "stupid-enough". Even admitting that XML is very useful, I think it's completely stupid to use XML whenever there's an exchange of data between programs or whenever we have to declare a structure. I think XML is the glue that unites "Black boxes", each program should be a black box, but inside that Black box I can live without XML. Now, documenting can be considered a black box, we can always support a XML layer in the most external step of documentation, and use an internal mini-language or tags or whatever suits our needs better. But all this is against "professional" stuff because: - It gives an unnecessary flexibility ( professionals want stiff systems) - It gives more than one way to do it (professionals want only one solution) - It uses academic rubish : black boxes, modularity. Any professional want to hard-wire and write the less code as possible. Any professional will tell you that the less interfaces the better. The TRUTH is that the more interfaces you use , the more freedom degrees are available for you, and better maintainance. But "professional" like the hard way, rewrite code and such. Of course, being "professional" is the logical step for python, it will lose most of its charm but it'll make more money. Linux is suffering the same evolution, btw. > > 2. What happened to all the people who were going to refuse to use such a > format if it were more verbose than the proposal being circulated pre-IPC8 > (which I thouhgt was generally agreed on)? There's been no explanation of > why they've suddenly reversed position, if they indeed have. I can't fight against the world. I must add that few people is interested in the problem itself. The problem is as simple as this: - A rich, flexible and used by many people, way of doc This implies more than a solution, but generating XML in the last step. Used by many people implies extremely simple and encouraging, I think my "mandoc" is simple, and I must add that there should be more than one way of simple documentation. > > As a smaller note, Moshe seems to be leaving out "cross references" as Cross references are extremely useful but they're never as impressive as a set of magic words. Many people suggest their own recipe of magic words for the problem , of course, professional like magic words. But they're not magic at all, but just a tool for describing things, the interesting thing is expression capability. Crossreferences express the inner structure and as many relationships as we want to, unfortunately they're not magic. > > [1] If we're going to have our own format, it has to give *significant* > benefits to readability/typability/etc, because having to translate into > something else to determine if it is legitimate (in the "valid XML" sense) > already makes it that much harder to correlate errors back to the original > text. I don't see those benefits here. I can't agree with this, pure XML would be always more buggy. Regards/Saludos Manolo www.ctv.es/USERS/irmina /TeEncontreX.html /texpython.htm /pyttex.htm I have an existential map. It has "You are here" written all over it. -- Steven Wright From Moshe Zadka Fri Feb 4 21:19:23 2000 From: Moshe Zadka (Moshe Zadka) Date: Fri, 4 Feb 2000 23:19:23 +0200 (IST) Subject: [Doc-SIG] More documentation Message-ID: Here is some more user testing -- the docstrings in getopt.py converted to use my syntax, with the change I've made: Now long args can have either the syntax :: Or :: The same way the Python interpreter allows. Note that although my official escape character is '@', in all the tests I've never had to escape once! in-defense-of-thesis-mode-ly y'rs, Z. """Parser for command line options. This module helps scripts to parse the command line arguments in [var sys.argv]. It supports the same conventions as the Unix [cfunction getopt()] function (including the special meanings of arguments of the form [code `-'] and [code `--']). Long options similar to those supported by GNU software may be used as well via an optional third argument. This module provides a single function and an exception: Gerrit Holl moved the string-based exceptions to class-based exceptions. list:: item:: [function getopt()] -- Parse command line options item:: [exception GetoptError] -- exception (class) raised when [function getopt()] detects a problem with the options. exception name=GetoptError:: An exception throws for incorrect options. It has a member [member opt], which is the option which triggered the exception. """ # Long option support added by Lars Wirzenius . import string class GetoptError(Exception): opt = '' msg = '' def __init__(self, *args): self.args = args if len(args) == 1: self.msg = args[0] elif len(args) == 2: self.msg = args[0] self.opt = args[1] def __str__(self): return self.msg error = GetoptError # backward compatibility def getopt(args, shortopts, longopts = []): """\ Return the list of options and values used. arg name=args type=list:: Arguments to be parsed. Note that the first argument is assumed to be a real argument, [emph not] the name of the program. arg name=shortopts type=string:: Option letters the program recognizes that. Option that require an argument are followed by a colon ([code :]). Note that this is the same format the Unix [cfunction getopt()] uses. arg name=longopts type=list default=[code []]:: Long options names which should be recognized. Options which require and argument should be followed by an equal sign ([code '=']). Note that the leading double hyphen ([code '--']) should [emph not] be included in the option name. return type=tuple:: The return value consists of two elements: list:: item:: A list of [code (option, value)] pairs. The option appears as it appears on the command line: including a hyphen or double hyphen. Long and short options may be mixed. item:: List of program arguments left after the options were stripped (this is a trailing slice of the first argument). """ -- Moshe Zadka . INTERNET: Learn what you know. Share what you don't. From da@ski.org Fri Feb 4 22:16:13 2000 From: da@ski.org (David Ascher) Date: Fri, 4 Feb 2000 14:16:13 -0800 Subject: [Doc-SIG] DocStrings 0.3: Suggestion for documentation syntax (very long) References: <002c01bf6f04$ab116720$f0c809c0@lslp7o.lsl.co.uk> Message-ID: <00e201bf6f5d$735cda90$0100000a@ski.org> > 2. What happened to all the people who were going to refuse to use such a > format if it were more verbose than the proposal being circulated pre-IPC8 > (which I thouhgt was generally agreed on)? There's been no explanation of > why they've suddenly reversed position, if they indeed have. I certainly haven't. There was (alas) no serious discussion on this topic during developer's day, which in my opinion was a very frustrating and pointless event. Too many folks with no involvement in the SIG just felt it was an opportunity to express their 'feelings' without committing resources or proposals. We had yet another discussion about XML, SGML, absence of tools, whether DocBook, PDF or Word, having user needs drive the process or not, etc. etc., but I don't think that Fred learned anything that he didn't know before. FWIW, I am tentatively opposed to Moshe's proposal, the tentatively because I haven't had a chance to give his proposal a fair look. The 'look and feel' of the markup, however, doesn't sit well with me. I will do a more serious critique in the next few days. Moshe, could you step back a little and explain why we should undo the relative agreement we'd established (IMO) before IPC8? --david From Moshe Zadka Fri Feb 4 22:28:33 2000 From: Moshe Zadka (Moshe Zadka) Date: Sat, 5 Feb 2000 00:28:33 +0200 (IST) Subject: [Doc-SIG] DocStrings 0.3: Suggestion for documentation syntax (very long) In-Reply-To: <00e201bf6f5d$735cda90$0100000a@ski.org> Message-ID: David, sorry to pick on you, but this will be a rather collective answer. On Fri, 4 Feb 2000, David Ascher wrote: > not, etc. etc., but I don't think that Fred learned anything that he didn't > know before. I agree. It was a bit pointless. > FWIW, I am tentatively opposed to Moshe's proposal, the tentatively because > I haven't had a chance to give his proposal a fair look. The 'look and > feel' of the markup, however, doesn't sit well with me. I will do a more > serious critique in the next few days. Great! > Moshe, could you step back a little and explain why we should undo the > relative agreement we'd established (IMO) before IPC8? Well, I certainly seemed to steer enough negative feelings! For one thing "I didn't know we had one". For another thing, my proposal had one thing no other proposal I know of had: a clear definition of the driving forces behind it. Now, one thing I would like to know is whether it was bad design (my goals were wrong) or bad implementation (my proposal didn't meet those goals). I must say that no-one seemed to give it as much as a chance -- that is, re-write one docstring in it. As to Greg's objection, well, I can certainly live with something which "guesses" what the words mean based on some delimiters. I'm doubtful that I could write it, and I'm even skeptic that anyone will do a good enough job that it will replace the semantic markup completely, but we can give it a try. In short, what I want (and I think deserve) is more then people saying "Yuck!" -- I want to see if version 0.4 can be better. If people think my proposal is so horrible it can never be fixed, then if someone could show an alternative proposal, it would do us all some good. crushed-by-the-multitudes-ly y'rs, Z. -- Moshe Zadka . INTERNET: Learn what you know. Share what you don't. From fdrake@acm.org Fri Feb 4 22:44:14 2000 From: fdrake@acm.org (Fred L. Drake, Jr.) Date: Fri, 4 Feb 2000 17:44:14 -0500 (EST) Subject: [Doc-SIG] content requirements Message-ID: <14491.22078.735280.690169@weyr.cnri.reston.va.us> In case anyone noticed, the content requirements I promised at IPC8 aren't done. I am working on them and making progress, but it's fairly tedious. I should have something out next week. On the other hand, we do have the audience identification (I know it's been read, any comments?) which wasn't specifically assigned (except to Moshe, who will be doing everything from now on ;). I think it's great that the discussions are active! -Fred -- Fred L. Drake, Jr. Corporation for National Research Initiatives From mhammond@skippinet.com.au Sat Feb 5 23:28:02 2000 From: mhammond@skippinet.com.au (Mark Hammond) Date: Sun, 6 Feb 2000 10:28:02 +1100 Subject: [Doc-SIG] Docstring grammar: a very revised proposal In-Reply-To: Message-ID: [David writes back on Sat 22-Jan-00] > In preparation of a discussion at IPC8's DevDay, Well, I think we all agree on how that went ;-) > and anticipating (perhaps mistakenly) some resistance to > "yet another structured text format" from Jim Fulton, I In the short discussion on that topic, it seemed that Jim had no great objections. So, as DevDay didnt achieve much, I think we should run with this grammar. My comments, generally ignoring what Ken already commented on: > StructuredText as XML without a DTD: Im happy to ignore StructuredText for out-of-line doc for now. The critical issue we have to deal with is docstrings. Did we ever determine what OReilly's position on XML and particular DTDs is? > The requirement that a paragraph end with the word example or > examples or :: goes against my natural style, as I often do not IMO, its not too bad, as it is only used to introduce single paragraph code-block (if I read the rules correctly?) > If the two colons are not displayed by the renderer, > then my objection is diminished, although I would have preferred a > markup which is local to the paragraph which is affected Agreed. > Missing features: > > The definition of references is well-designed for referencing > URLs. The docstring proposal needs to address referencing other > code elements (methods of current class, other classes, other > methods of other classes, builtin modules, imported modules, etc.) > This is also more of a lack of feature than a real flaw, and > defining the namespaces for lookup of 'reference targets' would > probably go most of the way towards fixing the spec for our needs. Definately agreed, and IMO quite a critical issue. In the absense of any other complaints or comments about this proposal, I suggest that this proposal is what we run with for doc-strings. The key problem is getting tools and code to work with this revised proposal, and exactly what this means to StructuredText as used today by the Zope guys. The key feature of this proposal is that it can already give us something to work with. As mentioned a few times on DevDay, we need a blessed doc-string format so people can start writing docstrings in the knowledge tools will follow. So, does anyone else have any comments on David's proposal? Can we work towards a new set of "Structured Text for DocStrings" rules that people can start using for their docstrings? This SIG has been going for ages, and has been amazingly short on results (a critisism that obviously includes myself!). It really is time to get something happening, and this is an excellent start! Mark. From da@ski.org Sun Feb 6 05:26:53 2000 From: da@ski.org (David Ascher) Date: Sat, 5 Feb 2000 21:26:53 -0800 Subject: [Doc-SIG] Docstring grammar: a very revised proposal References: Message-ID: <01b001bf7062$c743abb0$0100000a@ski.org> > Did we ever determine what OReilly's position on XML and particular DTDs is? I did ask Frank Willison (editor in chief of O'Reilly, and for those of you who don't know, a big Python fan) in the hall after the doc-sig extravaganza. He says that they think they have a working system now which works on DocBook, but that it was damn hard to setup the system. The problem was that the DocBook Book tried to tackle every corner of the spec, which was just really hard. This is from memory and was encoded when I was pretty exhausted, so I won't swear to the exactitude of the recall. I am not expert enough on large-scale text processing to fully understand the implications of specific DTD choices, but I think that the impact of a specific DTD choice is a minor one in the absence of XML editors for the masses (i.e., Fred did the work before, and realistically, Fred's going to be doing the work in the foreseeable future at least -- Fred should choose what he wants to use). He's already done the hard part of regularizing the markup and I'm sorry I didn't get a chance to buy him a beer at IPC8. > So, does anyone else have any comments on David's proposal? Can we work > towards a new set of "Structured Text for DocStrings" rules that people can > start using for their docstrings? I think I need to put up working code before folks really get a feel for it, along with a cleaned up description of the format (different strokes for different folks). Not everyone followed every thread of the last couple of months, and I apologize for not having put forth a revised proposal sooner. I'll ping Ken to find out what the status of their internal reworking of StructuredText-the-code is. FWIW, I don't care much whether we use their code or not. I care more about having a common 'base grammar' and then specific extensions for docstrings (and they can have specific extensions for other things as they see fit). --david It's interesting how the percentage of time that I can allocate to Python has grown proportionally less than the number of Python-related items on my todo list =). From jack@oratrix.nl Sun Feb 6 21:32:52 2000 From: jack@oratrix.nl (Jack Jansen) Date: Sun, 06 Feb 2000 22:32:52 +0100 Subject: [Doc-SIG] More documentation In-Reply-To: Message by Moshe Zadka , Fri, 4 Feb 2000 23:19:23 +0200 (IST) , Message-ID: <20000206213258.3CDA6D3761@oratrix.oratrix.nl> I get more and more confused as I see the postings of last week come by. In my mind docstrings have always been intended as quick-and-dirty reference information, to be presented (along with function signatures and such) when you press a "help" button in a Python IDE. But the way Moshe's proposals and examples go are much more toward a tangle/web/weave system, where the source code and the full documentation are intertwined. At least, in my mind the examples are all far too verbose: lots of formatting info, typing info on the variables/functions/exceptions used, etc. I know that for me this will not work. Not only do I abhor weave-like systems (I think writing real documentation should be done with a completely different mindset, and not sort-of in-between while writing the code) but I'm also sure to forget the syntax, so after staring at the opening """ for a few seconds I'll think "ah, forget it. Who needs docs anyway". The scheme we seemed to be converging to before the conference was much more to my liking: basically free-format with a few readable flag-words like "arguments:" or so. -- Jack Jansen | ++++ stop the execution of Mumia Abu-Jamal ++++ Jack.Jansen@oratrix.com | ++++ if you agree copy these lines to your sig ++++ www.oratrix.nl/~jack | see http://www.xs4all.nl/~tank/spg-l/sigaction.htm From jack@oratrix.nl Sun Feb 6 21:38:10 2000 From: jack@oratrix.nl (Jack Jansen) Date: Sun, 06 Feb 2000 22:38:10 +0100 Subject: [Doc-SIG] DocStrings 0.3: Suggestion for documentation syntax (very long) In-Reply-To: Message by Moshe Zadka , Sat, 5 Feb 2000 00:28:33 +0200 (IST) , Message-ID: <20000206213815.BEA10D3761@oratrix.oratrix.nl> Recently, Moshe Zadka said: > In short, what I want (and I think deserve) is more then people saying > "Yuck!" -- I want to see if version 0.4 can be better. Moshe, I'll start with "sorry!!!", because my previous mail could probably also be interpreted as little more than "Yuck!", but it definitely wasn't intended so! I appreciate the work you've put into this, and I think the outcome probably matches the various goals you've set (like XML compatability while being more readable), but I'm not sure I agree with those goals, or at least with the way the examples seem to go. As I explained in a previous message, to me docstrings should be easy-write, easy-read, and in no way a replacement for True Documentation. -- Jack Jansen | ++++ stop the execution of Mumia Abu-Jamal ++++ Jack.Jansen@oratrix.com | ++++ if you agree copy these lines to your sig ++++ www.oratrix.nl/~jack | see http://www.xs4all.nl/~tank/spg-l/sigaction.htm From ping@lfw.org Sun Feb 6 22:19:31 2000 From: ping@lfw.org (Ka-Ping Yee) Date: Sun, 6 Feb 2000 14:19:31 -0800 (PST) Subject: [Doc-SIG] Ease of use is #1 In-Reply-To: Message-ID: To the moderator: please cancel my earlier message, which had an attached example that was too big. Instead of including it in the message, i'll just put it on a website. ------------------ Before i begin, let me make an attempt to propose the two most important goals of any documentation project. I. To encourage people to write lots of documentation. II. To make that documentation as accessible as possible. There is an example at http://www.lfw.org/python/SocketServer.html ; it is discussed in more detail below. On Fri, 4 Feb 2000, Moshe Zadka wrote: > Special tokens: > @ -- escapes any character following it (i.e., @c is always translated > to c) > > [ -- a short tag opener. Closed with a matching ] > > ::(newline) -- beginning a a long tag. everything until the > indent level returns to that of the line which started the long > tag is part of the contents. > > (newline)(newline) -- new paragraph. > > The syntax of short tags is '[' tagname ' ' contents ']' where contents is > any valid snippet of docstring, with the exception of a long tag. > > The syntax of long tags is > > tagname (attr '=' value)*'::' > contents [there follow some 450 lines of description] My first reaction to this is -- Holy crap! This has gotten totally out of control! It will do us no good for geeks like us -- the 1% of uber-geeks *within* that 1% of geeks that Randy described -- to sit in ivory towers describing elaborate syntaxes for marking up documentation when most other readers won't even understand the syntax, let alone use it in their own code. Why, i wouldn't even bother to do all of this marking up in my own documentation. I sincerely wish not for Moshe to take this personally -- i just think that this is one example of far too many steps down a seductive path in the wrong direction. Why does one never see e-mail like the following? crap! has gotten totally ! Because: 1. No one in their right mind would waste all that time typing. The markup has two potential audiences: humans and machines. 2. The markup isn't going to get used by any sort of mechanical parsing tool anyways. 3. Any meaning that a human could obtain from the markup can be fairly well derived from context. Now, let's translate these three points over into the world of source code documentation. [1.] Point 1 stands as is. Every obstacle that we introduce -- whether a cognitive obstacle (more syntax to understand) or just extra effort (more typing) will make it less likely for people to write documentation. Can you imagine how quickly people would simply stop writing any documentation at *all* if we were to have doc-sig police jumping around pointing out "Oh, your docstring has incorrect syntax because you didn't escape this bracket with an @-sign here." or "You used that semantic tag incorrectly; you should have used [var] instead of [code]."? Remember the old adage that says that every math equation in a book will cut its readership in half? Well, imagine something similar -- every additional syntactic construct or tag will cut the *writership* in half (or some fraction). Even though more tags may mean more expressive power, it also means a more difficult choice to make every time one uses a tag -- beyond a certain point it becomes debatable which tag is the correct one to use, and then all is lost. Also, the more complex the system becomes, the less predictable the failure modes will be -- till we get to the point you have to debug docstrings (eek!). The absolute priority here is to make docstrings *dead* easy to write. That entry barrier has to go way down -- in the limit, to zero, where even existing docstrings written without knowledge of our discussion can be considered rich and "correct" docstrings. (The example is generated from SocketServer.py as distributed with Python 1.5 -- nothing has been edited.) [2.] To the proliferation of long and short tags such as arg, code, data, etc. -- first i ask, what is the purpose? Is this a solution in search of a problem? What will an automatic documentation generator use these tags for? For example, you can devise a structure where you list function arguments and mark up each one, but since the descriptions next to them are just in plain English, what good would a nicely-organized table do for a machine anyway? When would you ever need to collect descriptions of random individual arguments without looking at the function docstring as a whole? (Can we expect it to do much better than the example at http://www.lfw.org/python/SocketServer.html ? At what cost to the writers and readers of docstrings do we achieve such additional power?) [3.] The people who are going to be writing and reading these docstrings have already invested considerable mental effort in the syntax of one language, Python. Let's capitalize on the context we can gather from that, rather than introducing an entirely independent syntax for people to learn as well. We can get a lot of mileage out of this. For example, identifiers that appear after "self." are clearly instance attributes; identifiers that are immediately followed by "(" are function or method calls; we can determine class and function names by introspection; and so on. These conventions are already used by many people; all we have to do is introduce a little payoff, and make sure we keep the conventions very straightforward and the payoff predictable, to encourage and strengthen the use of these conventions. (The example uses this technique to mark up class and method names with hyperlinks, and to make attribute names stand out.) Finally, about the example: this is the example i showed at the end of the Doc-SIG meeting on Developer Day at IPC8. It was generated automatically from the stock SocketServer.py by a program that imports the module and introspects into its classes and functions. We use this script (except for the hyperlinking -- that was a recent addition) at ILM and it works for us fairly well. See: http://www.lfw.org/python/SocketServer.html Further improvements: - Many modules contain documentation in # comments at the beginning of the module, or immediately before functions or classes. The script could look for documentation in these places as well, if docstrings are not found. (This is now done in my local copy, though it wasn't in the script when i demonstrated it at IPC8.) (Side note: i've updated all the modules in the standard library that did this, by moving the # comments into proper docstrings, but this is still likely a good feature to have, as i bet lots of other modules out there use # comments instead of docstrings.) - The script oughta scan the module for constants as well. Constants could be documented with a # comment on the same line as the constant assignment. - Given knowledge of other modules in the system, the script could produce hyperlinks where documentation in one module references functions or classes in another. In short -- let's make it so easy to write rich docstrings that people do it correctly without even knowing that they are doing it. -- ?!ng "If I have not seen as far as others, it is because giants were standing on my shoulders." -- Hal Abelson From pf@artcom-gmbh.de Sun Feb 6 22:17:13 2000 From: pf@artcom-gmbh.de (Peter Funk) Date: Sun, 6 Feb 2000 23:17:13 +0100 (MET) Subject: [Doc-SIG] Patch Guide-Lines for Documentation Message-ID: Hi! 'http://www.python.org/patches' contains detailed information how to submit patches. However it is unclear, how to submit patches against the Python Documentation and whether these guidelines also apply on submissions to python-docs@python.org. This should be made clearer. Especially, whether every small patch must indeed contain the standard disclaimer. Regards, Peter -- Peter Funk, Oldenburger Str.86, 27777 Ganderkesee, Tel: 04222 9502 70, Fax: -60 From pf@artcom-gmbh.de Sun Feb 6 22:39:41 2000 From: pf@artcom-gmbh.de (Peter Funk) Date: Sun, 6 Feb 2000 23:39:41 +0100 (MET) Subject: [Doc-SIG] Ease of use is #1 In-Reply-To: from Ka-Ping Yee at "Feb 6, 2000 2:19:31 pm" Message-ID: Hi! [ping]: > There is an example at http://www.lfw.org/python/SocketServer.html ; > it is discussed in more detail below. I've just had look at it: This looks really great! That goes far beyond that what I got out pythondoc or gendoc. Where can I get the tool/script which produced this nice HTML? Please go ahead and get the permission to publish manpy! I'm holding my breath... ;-) [...] Regards, Peter -- Peter Funk, Oldenburger Str.86, 27777 Ganderkesee, Tel: 04222 9502 70, Fax: -60 From willguaraldi@mediaone.net Sun Feb 6 23:22:48 2000 From: willguaraldi@mediaone.net (will) Date: Sun, 6 Feb 2000 18:22:48 -0500 Subject: [Doc-SIG] Ease of use is #1 In-Reply-To: Message-ID: >----------Peter wrote:------------ > [ping]: > > There is an example at > http://www.lfw.org/python/SocketServer.html ; > > it is discussed in more detail below. > > I've just had look at it: This looks really great! > That goes far beyond that what I got out pythondoc or gendoc. > Where can I get the tool/script which produced this nice HTML? > > Please go ahead and get the permission to publish manpy! > I'm holding my breath... ;-) > [...] > > Regards, Peter I also looked at it and that's along the lines of what I'm looking for in terms of generated output (though I think I would choose less pinky colors). More importantly though, I would like to know more about what the doc-strings look like in order to produce that output. /will From ping@lfw.org Sun Feb 6 23:41:37 2000 From: ping@lfw.org (Ka-Ping Yee) Date: Sun, 6 Feb 2000 15:41:37 -0800 (PST) Subject: [Doc-SIG] Ease of use is #1 In-Reply-To: Message-ID: On Sun, 6 Feb 2000, will wrote: > > I also looked at it and that's along the lines of what I'm looking for > in terms of generated output (though I think I would choose less pinky > colors). More importantly though, I would like to know more about > what the doc-strings look like in order to produce that output. The module is unaltered from SocketServer.py in the standard library distributed with Python 1.5.2. I put a copy of it up at http://www.lfw.org/python/SocketServer.py in case you don't have 1.5.2. In short, nothing special. The docstrings are exactly what you see on the HTML page without the formatting. -- ?!ng "If I have not seen as far as others, it is because giants were standing on my shoulders." -- Hal Abelson From willguaraldi@mediaone.net Sun Feb 6 23:37:40 2000 From: willguaraldi@mediaone.net (will) Date: Sun, 6 Feb 2000 18:37:40 -0500 Subject: [Doc-SIG] Ease of use is #1 In-Reply-To: Message-ID: > -----Original Message----- > The module is unaltered from SocketServer.py in the standard > library distributed with Python 1.5.2. I put a copy of it up > at http://www.lfw.org/python/SocketServer.py in case you don't > have 1.5.2. In short, nothing special. The docstrings are > exactly what you see on the HTML page without the formatting. > > -- ?!ng Heh--I feel pretty silly now.... Looking at the doc-strings involved and the output generated, that's exactly what I'm looking for. At the bottom of the SocketServer.html page it says: "manpy by Tommy Burnette. Web interface by Ping...." Does this mean that manpy is the script that generates the documentation in some format-intermediary form and then there is a cgi script/program that takes that form and formats it for html? btw - If this is redundant information from what was at IPC8, then my apologies and such. /will From Moshe Zadka Mon Feb 7 05:13:00 2000 From: Moshe Zadka (Moshe Zadka) Date: Mon, 7 Feb 2000 07:13:00 +0200 (IST) Subject: [Doc-SIG] Re: Ease of use is #1 In-Reply-To: Message-ID: On Sun, 6 Feb 2000, Ka-Ping Yee wrote: > Before i begin, let me make an attempt to propose the two most important > goals of any documentation project. > > I. To encourage people to write lots of documentation. > > II. To make that documentation as accessible as possible. > > The attached file is an example; it is discussed in more detail below. > > > On Fri, 4 Feb 2000, Moshe Zadka wrote: > > Special tokens: > > @ -- escapes any character following it (i.e., @c is always translated > > to c) > > > > [ -- a short tag opener. Closed with a matching ] > > > > ::(newline) -- beginning a a long tag. everything until the > > indent level returns to that of the line which started the long > > tag is part of the contents. > > > > (newline)(newline) -- new paragraph. > > > > The syntax of short tags is '[' tagname ' ' contents ']' where contents is > > any valid snippet of docstring, with the exception of a long tag. > > > > The syntax of long tags is > > > > tagname (attr '=' value)*'::' > > contents > [there follow some 450 lines of description] No, 10 lines of description and 450 lines of a module done up in the way I propose. Ping, it seems you didn't even read my message. While I admire the way you markup by "guessing", I must admit I have my qualms about this approach: too little control for the documenter. Possibly, a mix of the two approaches is in order. From pf@artcom-gmbh.de Mon Feb 7 06:40:09 2000 From: pf@artcom-gmbh.de (Peter Funk) Date: Mon, 7 Feb 2000 07:40:09 +0100 (MET) Subject: [Doc-SIG] Re: Ease of use is #1 In-Reply-To: from Moshe Zadka at "Feb 7, 2000 7:13: 0 am" Message-ID: Hi! [ping]: > > [there follow some 450 lines of description] [Moshe]: > No, 10 lines of description and 450 lines of a module done up in the way I > propose. > > Ping, it seems you didn't even read my message. I don't want to be pernickety, but this is plain wrong! Moshe's syntax makes no sense at all without the list of tags (attributes) which is longer than 10 lines: > List of tags, and where they are valid: > code (both as long and short) -- anywhere > example (long, no attributes) -- anywhere > arg, return (attributes: name, type, default (optional) ) -- > function docstring, never inside another long tag. > rest-arg, kw-arg (long, no attributes) -- > function docstring, never inside another long tag. > data (attributes: name, type) -- > class/module doc-string, never inside another long tag. > exception (attributes: name) -- > class/module doc-string, never inside another long tag. > member (attributes: name, type) -- > class doc-string, never inside another long tag. > function, module, class, exception, var, method, keyword, member, > pytype, file, url, arg (short tag) -- anywhere > > (these are for general markup syntax, so I've probably forgotten > some): > list (long tag) -- anywhere > item (long tag) -- anywhere > emph (short tag) -- anywhere This list is on one hand too complex (as we have seen in this discussion, the average Python programmer will hardly bother with such a beast) and on the other hand still incomplete. As ping pointed out before, the vast majority of the tags listed by moshe above can be discovered from context of the python modules. [Moshe]: > While I admire the way you markup by "guessing", I must admit I have my > qualms about this approach: too little control for the documenter. > Possibly, a mix of the two approaches is in order. I think, it would be very valuable, if we could come up with a more formal description (grammar?) of how this "guessing" markup engine works or should work. As long as this wonderful artificial intelligence code build into the guessing engine works well, no one has to bother with it. But if it fails, the documenter shouldn't be forced into a deep swamp regexp (that is the situation right now, if you are unsatisfied by the results of gendoc or pythondoc). That is the point, where in IMHO the "docstring grammar" comes into play: Giving the documenter who cares about the output the chance to correct misinterpretations of guessing engine. Regards, Peter -- Peter Funk, Oldenburger Str.86, 27777 Ganderkesee, Tel: 04222 9502 70, Fax: -60 From tony@lsl.co.uk Mon Feb 7 09:24:07 2000 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Mon, 7 Feb 2000 09:24:07 -0000 Subject: [Doc-SIG] Monty: A structured text syntax idea In-Reply-To: <20000205084721.A1020@stopcontact.palga.uucp> Message-ID: <001301bf714d$15a182b0$f0c809c0@lslp7o.lsl.co.uk> I've got to dash this off quickly before going into a two-day training course, so haven't had time to read all of the cumulative thread that has happened since Friday morning - sorry. Moshe - I wasn't trying to get at you particularly personally - you've obviously put a lot of thought and work into your proposal. BUT. When the last round of doc string discussions happened (a couple of years ago) I was a strong TeX or HTML proponent (XML didn't exist), but it soon became clear that *for many people* (i.e., not for me) the use of that sort of "verbose" markup is an immediate turnoff. Note that both TeX and HTML, and thus also all SGML variants, count as verbose in this context, and so also does your markup. Whilst I personally find it hard to read your markup because the delimiters don't stand out visually to me (and no, XML needn't be much more verbose - hell, it's only typing anyway), experience both last round and this round shows that verbose markup just won't fly (people in general won't do it). Whereas the single-character style markups *do* work (heh - people use them in email!). This argument was rehashed in the latest round of DOC-SIG discussions as well, and the same result happened. The reference to the Tim Peters' doc string test thingy was because I came in wanting to delimit EXAMPLE sections, and Tim managed to convince me that I didn't need them (i.e., to change my mind - don't you hate it when people do that!). Sorry for the quick and probably by now out of context message, hope this makes sense. Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.demon.co.uk/ .. "equal" really means "in some sense the same, but maybe not .. the sense you were hoping for", or, more succinctly, "is .. confused with". (Gordon McMillan, Python list, Apr 1998) My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From ping@lfw.org Mon Feb 7 11:23:28 2000 From: ping@lfw.org (Ka-Ping Yee) Date: Mon, 7 Feb 2000 03:23:28 -0800 (PST) Subject: [Doc-SIG] DocStrings 0.3: Suggestion for documentation syntax (very long) In-Reply-To: <002c01bf6f04$ab116720$f0c809c0@lslp7o.lsl.co.uk> Message-ID: On Fri, 4 Feb 2000, Tony J Ibbs (Tibs) wrote: > > 1. Why don't we just use XML? - the proposed format is almost as verbose, > and has the disadvantage that it is a new format "for the sake of it" [1]. Because XML is totally unacceptable for typing. Moreover, it is quite easy to type syntactically incorrect XML [1], and the concept of documentation so complex that it requires debugging on a syntactic level just horrifies me. -- ?!ng [1] ...as evidenced by my very own mistake! Can you find the error in the silly XML example in my first message entitled "Ease of use is #1"? From ping@lfw.org Mon Feb 7 11:16:41 2000 From: ping@lfw.org (Ka-Ping Yee) Date: Mon, 7 Feb 2000 03:16:41 -0800 (PST) Subject: [Doc-SIG] Re: Ease of use is #1 In-Reply-To: Message-ID: On Mon, 7 Feb 2000, Peter Funk wrote: > > I think, it would be very valuable, if we could come up with a more > formal description (grammar?) of how this "guessing" markup engine works > or should work. > > As long as this wonderful artificial intelligence code build into > the guessing engine works well, no one has to bother with it. Let's stay away from the dangerous realm of "guessing" and imagining that there is any "artificial intelligence" going on. We do not want this system to do any fancy thinking at all; it must be dead stupid in what it does, so that its behaviour is predictable. As for your formal description, i agree that would be very good. To start things off, here are the rules used in the script that generated the example at http://www.lfw.org/python/SocketServer.html -- there are just three: 1. In a module docstring, any mention of a class defined in that module is hyperlinked to the class documentation. 2. In a class docstring, any mention of a method defined in that class, where the method name is immediately followed by an open-parenthesis, is hyperlinked to the method documentation. 3. In a class or method docstring, any identifier preceded by "self." is set in boldface. I would probably extend the first rule to allow referring to classes in other modules (by saying module.class), and add one more rule to highlight where parameter names are mentioned in function or method docstrings, and leave it at that. -- ?!ng From ping@lfw.org Mon Feb 7 11:09:32 2000 From: ping@lfw.org (Ka-Ping Yee) Date: Mon, 7 Feb 2000 03:09:32 -0800 (PST) Subject: [Doc-SIG] Re: Ease of use is #1 In-Reply-To: Message-ID: On Mon, 7 Feb 2000, Moshe Zadka wrote: > No, 10 lines of description and 450 lines of a module done up in the way I > propose. I apologize. I did read your message, but clearly 450 was an unfair exaggeration. I should have simply stated that the description was longer and more involved that i would have preferred. > While I admire the way you markup by "guessing", I must admit I have my > qualms about this approach: too little control for the documenter. I entirely agree with you that the markup rules cannot be complicated and mysterious. In fact, i cringe at the word "guessing" in much the same way you probably do. It is crucial that the rules be simple and their behaviour easily understood. Let's work together to whittle the problem down to its essentials, then. In your opinion, what kinds of things must the documenter be able to precisely control? Could you prioritize a list? -- ?!ng From Moshe Zadka Mon Feb 7 12:37:48 2000 From: Moshe Zadka (Moshe Zadka) Date: Mon, 7 Feb 2000 14:37:48 +0200 (IST) Subject: [Doc-SIG] Re: Ease of use is #1 In-Reply-To: Message-ID: On Mon, 7 Feb 2000, Ka-Ping Yee wrote: > Let's work together to whittle the problem down to its essentials, then. > In your opinion, what kinds of things must the documenter be able to > precisely control? Could you prioritize a list? Assumption 1: doc-strings should be flexible enough to document most Python modules without any OOL documentation (that is, as I understand, our majority vote). The "most" comes because it shouldn't necessarily be flexible enough to write the reference manual for the debugger. Assumption 2: the documentation must be convertible to XML, so various tools could use the XML to generate output formats in pleasent ways. (HTML, PDF, Word2K via COM) Assumption 3: it must be "easy" to write doc-strings. Assumption 4: the "easy" part shouldn't hamper an interested documenter from doing sophisticated things Assumption 5: the doc-strings rules must be clear. We do not want to recreate Perl in docstrings. Can we decide to agree on these assumptions? If we agree on these, I'm sure we can formulate a spec conforming to them, more or less. OTOH, if we can't, no spec will solve the problem. -- Moshe Zadka . INTERNET: Learn what you know. Share what you don't. From pf@artcom-gmbh.de Mon Feb 7 13:14:18 2000 From: pf@artcom-gmbh.de (Peter Funk) Date: Mon, 7 Feb 2000 14:14:18 +0100 (MET) Subject: M.Z. assumptions (was Re: [Doc-SIG] Re: Ease of use is #1) In-Reply-To: from Moshe Zadka at "Feb 7, 2000 2:37:48 pm" Message-ID: Hi! Moshe Zadka wrote: > Assumption 1: > doc-strings should be flexible enough to document most Python > modules without any OOL documentation (that is, as I understand, > our majority vote). The "most" comes because it shouldn't > necessarily be flexible enough to write the reference manual for > the debugger. I see: IMHO this first assumption is wrong. Good reference documentation often requires complex material like tables, figures, formulas and more text, which will clutter up the source and distract during code maintainance. What you describe is the literate programming approach, which IMHO has always failed in the past. (Look at TeXs tangle and weave). It should be possible to autogenerate *some* kind of reference documentation from doc-strings during early stages of the lifetime of software. Later, when the software becomes more mature and complex, it should be possible to use this autogenerated material as a starting point for more elaborate documentation. So not all features, which would be available at the higher XML level and which you see used in the current python library reference need to have a counterpart in an upcoming doc-string grammar. Regards, Peter -- Peter Funk, Oldenburger Str.86, 27777 Ganderkesee, Tel: 04222 9502 70, Fax: -60 From Edward Welbourne Mon Feb 7 15:10:38 2000 From: Edward Welbourne (Edward Welbourne) Date: Mon, 7 Feb 2000 15:10:38 +0000 Subject: [Doc-SIG] Re: Ease of use is #1 In-Reply-To: References: Message-ID: OK, addressing our assumptions is a right approach. Especially as some of us are belidered at a sudden lurch away from where we used to be going ... > Assumption 1: This addresses `what are doc strings for ?' and I disagree with you (at least partially). To my eye, doc strings are there to provide folk *maintaining* and *deploying* the code with the information they need. This is why your Assumption 3 is, to me, the most important by far: only if doc-strings are easy to write will enough be written that one can use them while working on a lump of code. If folk want to store, in doc-strings, the thoughts which will `one day' become part of the smart (out-of-line, OOL) documentation (I do this plenty), that's fine: but we shouldn't perturb the doc string grammar in any material way in support of this. The OOL docs will get written with tools specialised for sophisticated markup and layout, way beyond the level of sophistication that the assumptions below will allow: those tools will enable the author to transform the simplistic mark-up of the doc-string extractor into whatever sophisticated markup they're using in the smart docs. > Assumption 2: I would re-phrase as: `the doc-string must be parse-able', which implies convertible to XML. Crucially, however, it must be parse-able not only by the special parser some clever person has written in our doc tools, but also by my eyes when I'm staring at too much code crammed into too little screen (I still want a whole wall screen with millifoot resolution). > Assumption 3: it must be "easy" to write doc-strings. This, for me, is the *most* important detail. Second most important is `easy to read'. Ease of either reading or writing argues for the `markup' to be unintrusive: the information should stand out, the markup should do no more than tell the eye its context. > Assumption 4: I reject this outright: reverse it to `we shall only try to build in as much sophistication as we *need* and as is compatible with "easy to write" and "easy to read"'. > Assumption 5: This is just 2 and 3. The purpose of the doc string format is to seduce authors of python code into writing enough documentation that folk deploying and maintaining their code will be able to see what it does. The be effective in this, the format must be easy enough to write that the work involved doesn't disrupt the seduction; it must be easy enough to parse (by eye) that the reader will know what it means; and it must contain enough information that docgen-tools can produce useful XML. That's be big picture. The minutiae then come down to stuff like: we need a common way of expressing what the parameters of functions *mean* (giving defaults and so on is less important, but desirable), what the methods of a class *do* (at the conceptual level, not the implementation level), what the data on instances of a class *mean* and what functionality a module exports. We also need an XML DTD to serve as the *target* to which a doc-string parser converts doc-strings. We had a spec a while back which did this pretty well. I thought David Asher was working on a revised form of it. What happened ? In this: * The base level of information is the structured text idiom, with paragraphs, the three kinds of list (descriptive, numbered, bulleted) and cross-references. Support for *emphasised text* was in, though we seem to lack support for `literal' or `code'. * We included a structured data format idiom in which a restricted vocabulary of keywords could be used, followed by a :, to introduce a block (using python indentation rules) whose grammar would depend on the keyword; but would typically involve support for the structured text just described along with its own restricted vocabulary of keywords for sub-blocks. The basic structured text should account for the bulk of everything we ever type in doc strings. As specified previously, it meets the `easy to write' and `easy to read' constraints, though it might benefit from some form of `code-fragment' markup for use, notably, when referring to a parameter or some other function/class/module, but also for inline (rather than displayed, using Code: or Example: keyword) code fragments. (Note: I don't go for `words which are spelt the same as one of my parameters can safely always be presumed to be references to that parameter - the right name for the parameter is *usually* a word which will be used in the doc-string at least as frequently `to mean what it normally means' as `as a reference to the parameter'.) The keyword-and-indent mechanism should only be provided for that which is necessary to `easy to write', `easy to read' and seducing authors to make clear the information maintainers and deployers will need. Each keyword will, indeed, map to an XML element in the DTD to which we transform the doc string; this DTD will, indeed, be a subset of the DTD for use in the OOL docs; but see my reversed Assumption 4 and note that the keyword need not be spelt the same as the XML tag. The keywords for which I can think up a *need* are: argument, code, return, exception (for a list of the exceptions which may get raised, along with what they mean, etc. - just like argument) and maybe something to indicate the start of a section providing translations for X-refs, if we go that way. In the case of argument and exception, I would expect each to introduce a descriptive list whose keys are the arguments and exceptions: i.e. I'm expecting something like Arguments: first ! sequence -- the data to be permuted *rest ! sequence[integers] -- the permutations to apply Return ! sequence: a sequence whose entries are drawn from first, in an order implied by the subsequent arguments; permute(row, ind, ..., dex)[i] will be row[ind[...[dex[i]]...]]. (using a `! type' idiom borrowed from a type-sig thread) as opposed to what I understand Moshe to be asking us to use (in which I find my eye drawn to the markup, not the information; and the markup contains many-times repeated bits, like name=, type=, while the indentation flies to and fro). Arg name=first, type=sequence: the data to be permuted Rest-arg name=rest type=sequence[integers]: the permutations to apply Return type=sequence: a sequence ... [as before ...] albeit I rather like Moshe's embellishment of the keyword structure, to include name=value items as in an XML tag. I remain to be convinced we want these, but it's a nice way to do them if we want attributes on blocks ... Eddy. Return-Path: Delivered-To: doc-sig@dinsdale.python.org Received: from python.org (parrot.python.org [132.151.1.90]) by dinsdale.python.org (Postfix) with ESMTP id 5B46E1CDA5 for ; Sun, 6 Feb 2000 16:50:25 -0500 (EST) Received: from emu.prod.itd.earthlink.net (emu.prod.itd.earthlink.net [207.217.121.31]) by python.org (8.9.1a/8.9.1) with ESMTP id QAA01042 for ; Sun, 6 Feb 2000 16:50:25 -0500 (EST) Received: from mail.lfw.org (dialup-166.90.43.67.SanFrancisco1.Level3.net [166.90.43.67]) by emu.prod.itd.earthlink.net (8.9.3/8.9.3) with ESMTP id NAA28678; Sun, 6 Feb 2000 13:51:43 -0800 (PST) Received: from localhost (ping@localhost) by mail.lfw.org (8.9.3/8.9.3) with ESMTP id OAA03895; Sun, 6 Feb 2000 14:08:45 -0800 X-Authentication-Warning: skuld.lfw.org: ping owned process doing -bs Date: Sun, 6 Feb 2000 14:08:45 -0800 (PST) From: Ka-Ping Yee To: Moshe Zadka Cc: doc-sig@python.org In-Reply-To: Message-ID: Organization: lfw MIME-Version: 1.0 Content-Type: MULTIPART/MIXED; BOUNDARY="8323328-2057684099-949874924=:2302" Subject: [Doc-SIG] Ease of use is #1 Sender: doc-sig-admin@python.org Errors-To: doc-sig-admin@python.org X-BeenThere: doc-sig@python.org X-Mailman-Version: 1.2 (experimental) Precedence: bulk List-Id: Python Documentation Special Interest Group This message is in MIME format. The first part should be readable text, while the remaining parts are likely unreadable without MIME-aware tools. Send mail to mime@docserver.cac.washington.edu for more info. --8323328-2057684099-949874924=:2302 Content-Type: TEXT/PLAIN; charset=US-ASCII Before i begin, let me make an attempt to propose the two most important goals of any documentation project. I. To encourage people to write lots of documentation. II. To make that documentation as accessible as possible. The attached file is an example; it is discussed in more detail below. On Fri, 4 Feb 2000, Moshe Zadka wrote: > Special tokens: > @ -- escapes any character following it (i.e., @c is always translated > to c) > > [ -- a short tag opener. Closed with a matching ] > > ::(newline) -- beginning a a long tag. everything until the > indent level returns to that of the line which started the long > tag is part of the contents. > > (newline)(newline) -- new paragraph. > > The syntax of short tags is '[' tagname ' ' contents ']' where contents is > any valid snippet of docstring, with the exception of a long tag. > > The syntax of long tags is > > tagname (attr '=' value)*'::' > contents [there follow some 450 lines of description] My first reaction to this is -- Holy crap! This has gotten totally out of control! It will do us no good for geeks like us -- the 1% of uber-geeks *within* that 1% of geeks that Randy described -- to sit in ivory towers describing elaborate syntaxes for marking up documentation when most other readers won't even understand the syntax, let alone use it in their own code. Why, i wouldn't even bother to do all of this marking up in my own documentation. I sincerely wish not for Moshe to take this personally -- i just think that this is one example of far too many steps down a seductive path in the wrong direction. Why does one never see e-mail like the following? crap! has gotten totally ! Because: 1. No one in their right mind would waste all that time typing. The markup has two potential audiences: humans and machines. 2. The markup isn't going to get used by any sort of mechanical parsing tool anyways. 3. Any meaning that a human could obtain from the markup can be fairly well derived from context. Now, let's translate these three points over into the world of source code documentation. [1.] Point 1 stands as is. Every obstacle that we introduce -- whether a cognitive obstacle (more syntax to understand) or just extra effort (more typing) will make it less likely for people to write documentation. Can you imagine how quickly people would simply stop writing any documentation at *all* if we were to have doc-sig police jumping around pointing out "Oh, your docstring has incorrect syntax because you didn't escape this bracket with an @-sign here." or "You used that semantic tag incorrectly; you should have used [var] instead of [code]."? Remember the old adage that says that every math equation in a book will cut its readership in half? Well, imagine something similar -- every additional syntactic construct or tag will cut the *writership* in half (or some fraction). Even though more tags may mean more expressive power, it also means a more difficult choice to make every time one uses a tag -- beyond a certain point it becomes debatable which tag is the correct one to use, and then all is lost. Also, the more complex the system becomes, the less predictable the failure modes will be -- till we get to the point you have to debug docstrings (eek!). The absolute priority here is to make docstrings *dead* easy to write. That entry barrier has to go way down -- in the limit, to zero, where even existing docstrings written without knowledge of our discussion can be considered rich and "correct" docstrings. (The attached example is generated from SocketServer.py as distributed with Python 1.5 -- nothing has been edited.) [2.] To the proliferation of long and short tags such as arg, code, data, etc. -- first i ask, what is the purpose? Is this a solution in search of a problem? What will an automatic documentation generator use these tags for? For example, you can devise a structure where you list function arguments and mark up each one, but since the descriptions next to them are just in plain English, what good would a nicely-organized table do for a machine anyway? When would you ever need to collect descriptions of random individual arguments without looking at the function docstring as a whole? (Can we expect it to do much better than the attached example? At what cost to the writers and readers of the docstrings do we achieve such additional power?) [3.] The people who are going to be writing and reading these docstrings have already invested considerable mental effort in the syntax of one language, Python. Let's capitalize on the context we can gather from that, rather than introducing an entirely independent syntax for people to learn as well. We can get a lot of mileage out of this. For example, identifiers that appear after "self." are clearly instance attributes; identifiers that are immediately followed by "(" are function or method calls; we can determine class and function names by introspection; and so on. These conventions are already used by many people; all we have to do is introduce a little payoff, and make sure we keep the conventions very straightforward and the payoff predictable, to encourage and strengthen the use of these conventions. (The attached example uses this technique to mark up class and method names with hyperlinks, and to make attribute names stand out.) Finally, about the attached example: this is the example i showed at the end of the Doc-SIG meeting on Developer Day at IPC8. It was generated from the stock SocketServer.py by a program that imports the module and introspects into its classes and functions. We use this script (except for the hyperlinking -- that was a recent addition) at ILM and it works for us fairly well. Further improvements: - Many modules contain documentation in # comments at the beginning of the module, or immediately before functions or classes. The script could look for documentation in these places as well, if docstrings are not found. (This is now done in my local copy, though it wasn't in the script when i demonstrated it at IPC8.) (Side note: i've updated all the modules in the standard library that did this, by moving the # comments into proper docstrings, but this is still likely a good feature to have, as i bet lots of other modules out there use # comments instead of docstrings.) - The script oughta scan the module for constants as well. Constants could be documented with a # comment on the same line as the constant assignment. - Given knowledge of other modules in the system, the script could produce hyperlinks where documentation in one module references functions or classes in another. In short -- let's make it so easy to write rich docstrings that people do it correctly without even knowing that they are doing it. -- ?!ng "If I have not seen as far as others, it is because giants were standing on my shoulders." -- Hal Abelson --8323328-2057684099-949874924=:2302 Content-Type: TEXT/PLAIN; charset=US-ASCII; name="SocketServer.html" Content-Transfer-Encoding: BASE64 Content-ID: Content-Description: Content-Disposition: attachment; filename="SocketServer.html" PCFkb2N0eXBlIGh0bWwgcHVibGljICItLy9XM0MvL0RURCBIVE1MIDMuMi8v RU4iPg0KPGh0bWw+PGhlYWQ+PHRpdGxlPm1hbnB5OiBTb2NrZXRTZXJ2ZXI8 L3RpdGxlPg0KPC9oZWFkPjxib2R5IGJnY29sb3I9IiNmZmZmZmYiPg0KPHA+ PHRhYmxlIHdpZHRoPSIxMDAlIiBjZWxsc3BhY2luZz0wIGNlbGxwYWRkaW5n PTAgYm9yZGVyPTA+DQo8dHI+PHRkIGJnY29sb3I9IiM3Nzk5ZWUiIGNvbHNw YW49Mz48c21hbGw+PHNtYWxsPjxicj48L3NtYWxsPjwvc21hbGwNCj48Zm9u dCBjb2xvcj0iI2ZmZmZmZiIgZmFjZT0iaGVsdmV0aWNhIj4mbmJzcDs8YnI+ Jm5ic3A7PGJpZz48YmlnPjxzdHJvbmc+U29ja2V0U2VydmVyPC9zdHJvbmc+ PC9iaWc+ICg8YSBocmVmPSIvcGluZy9tYW5weS5jZ2kiPi91c3IvbGliL3B5 dGhvbjEuNTwvYT4vPGEgaHJlZj0iZmlsZTovdXNyL2xpYi9weXRob24xLjUv U29ja2V0U2VydmVyLnB5Ij5Tb2NrZXRTZXJ2ZXIucHk8L2E+KTwvYmlnPjwv dGQ+PC9mb250PjwvdGQ+PC90cj4NCjwvdGFibGU+DQo8bW9kdWxlICdTb2Nr ZXRTZXJ2ZXInIGZyb20gJy91c3IvbGliL3B5dGhvbjEuNS9Tb2NrZXRTZXJ2 ZXIucHknPg0KPHA+IDxzbWFsbD48dHQ+R2VuZXJpYyZuYnNwO3NvY2tldCZu YnNwO3NlcnZlciZuYnNwO2NsYXNzZXMuPGJyPg0KPGJyPg0KVGhpcyZuYnNw O21vZHVsZSZuYnNwO3RyaWVzJm5ic3A7dG8mbmJzcDtjYXB0dXJlJm5ic3A7 dGhlJm5ic3A7dmFyaW91cyZuYnNwO2FzcGVjdHMmbmJzcDtvZiZuYnNwO2Rl ZmluaW5nJm5ic3A7YSZuYnNwO3NlcnZlcjo8YnI+DQo8YnI+DQotJm5ic3A7 YWRkcmVzcyZuYnNwO2ZhbWlseTo8YnI+DQombmJzcDsmbmJzcDsmbmJzcDsm bmJzcDsmbmJzcDsmbmJzcDsmbmJzcDsmbmJzcDstJm5ic3A7QUZfSU5FVDom bmJzcDtJUCZuYnNwOyhJbnRlcm5ldCZuYnNwO1Byb3RvY29sKSZuYnNwO3Nv Y2tldHMmbmJzcDsoZGVmYXVsdCk8YnI+DQombmJzcDsmbmJzcDsmbmJzcDsm bmJzcDsmbmJzcDsmbmJzcDsmbmJzcDsmbmJzcDstJm5ic3A7QUZfVU5JWDom bmJzcDtVbml4Jm5ic3A7ZG9tYWluJm5ic3A7c29ja2V0czxicj4NCiZuYnNw OyZuYnNwOyZuYnNwOyZuYnNwOyZuYnNwOyZuYnNwOyZuYnNwOyZuYnNwOy0m bmJzcDtvdGhlcnMsJm5ic3A7ZS5nLiZuYnNwO0FGX0RFQ05FVCZuYnNwO2Fy ZSZuYnNwO2NvbmNlaXZhYmxlJm5ic3A7KHNlZSZuYnNwOyZsdDtzb2NrZXQu aD48YnI+DQotJm5ic3A7c29ja2V0Jm5ic3A7dHlwZTo8YnI+DQombmJzcDsm bmJzcDsmbmJzcDsmbmJzcDsmbmJzcDsmbmJzcDsmbmJzcDsmbmJzcDstJm5i c3A7U09DS19TVFJFQU0mbmJzcDsocmVsaWFibGUmbmJzcDtzdHJlYW0sJm5i c3A7ZS5nLiZuYnNwO1RDUCk8YnI+DQombmJzcDsmbmJzcDsmbmJzcDsmbmJz cDsmbmJzcDsmbmJzcDsmbmJzcDsmbmJzcDstJm5ic3A7U09DS19ER1JBTSZu YnNwOyhkYXRhZ3JhbXMsJm5ic3A7ZS5nLiZuYnNwO1VEUCk8YnI+DQotJm5i c3A7Y2xpZW50Jm5ic3A7YWRkcmVzcyZuYnNwO3ZlcmlmaWNhdGlvbiZuYnNw O2JlZm9yZSZuYnNwO2Z1cnRoZXImbmJzcDtsb29raW5nJm5ic3A7YXQmbmJz cDt0aGUmbmJzcDtyZXF1ZXN0PGJyPg0KJm5ic3A7Jm5ic3A7Jm5ic3A7Jm5i c3A7Jm5ic3A7Jm5ic3A7Jm5ic3A7Jm5ic3A7KFRoaXMmbmJzcDtpcyZuYnNw O2FjdHVhbGx5Jm5ic3A7YSZuYnNwO2hvb2smbmJzcDtmb3ImbmJzcDthbnkm bmJzcDtwcm9jZXNzaW5nJm5ic3A7dGhhdCZuYnNwO25lZWRzJm5ic3A7dG8m bmJzcDtsb29rPGJyPg0KJm5ic3A7Jm5ic3A7Jm5ic3A7Jm5ic3A7Jm5ic3A7 Jm5ic3A7Jm5ic3A7Jm5ic3A7Jm5ic3A7YXQmbmJzcDt0aGUmbmJzcDtyZXF1 ZXN0Jm5ic3A7YmVmb3JlJm5ic3A7YW55dGhpbmcmbmJzcDtlbHNlLCZuYnNw O2UuZy4mbmJzcDtsb2dnaW5nKTxicj4NCi0mbmJzcDtob3cmbmJzcDt0byZu YnNwO2hhbmRsZSZuYnNwO211bHRpcGxlJm5ic3A7cmVxdWVzdHM6PGJyPg0K Jm5ic3A7Jm5ic3A7Jm5ic3A7Jm5ic3A7Jm5ic3A7Jm5ic3A7Jm5ic3A7Jm5i c3A7LSZuYnNwO3N5bmNocm9ub3VzJm5ic3A7KG9uZSZuYnNwO3JlcXVlc3Qm bmJzcDtpcyZuYnNwO2hhbmRsZWQmbmJzcDthdCZuYnNwO2EmbmJzcDt0aW1l KTxicj4NCiZuYnNwOyZuYnNwOyZuYnNwOyZuYnNwOyZuYnNwOyZuYnNwOyZu YnNwOyZuYnNwOy0mbmJzcDtmb3JraW5nJm5ic3A7KGVhY2gmbmJzcDtyZXF1 ZXN0Jm5ic3A7aXMmbmJzcDtoYW5kbGVkJm5ic3A7YnkmbmJzcDthJm5ic3A7 bmV3Jm5ic3A7cHJvY2Vzcyk8YnI+DQombmJzcDsmbmJzcDsmbmJzcDsmbmJz cDsmbmJzcDsmbmJzcDsmbmJzcDsmbmJzcDstJm5ic3A7dGhyZWFkaW5nJm5i c3A7KGVhY2gmbmJzcDtyZXF1ZXN0Jm5ic3A7aXMmbmJzcDtoYW5kbGVkJm5i c3A7YnkmbmJzcDthJm5ic3A7bmV3Jm5ic3A7dGhyZWFkKTxicj4NCjxicj4N ClRoZSZuYnNwO2NsYXNzZXMmbmJzcDtpbiZuYnNwO3RoaXMmbmJzcDttb2R1 bGUmbmJzcDtmYXZvciZuYnNwO3RoZSZuYnNwO3NlcnZlciZuYnNwO3R5cGUm bmJzcDt0aGF0Jm5ic3A7aXMmbmJzcDtzaW1wbGVzdCZuYnNwO3RvPGJyPg0K d3JpdGU6Jm5ic3A7YSZuYnNwO3N5bmNocm9ub3VzJm5ic3A7VENQL0lQJm5i c3A7c2VydmVyLiZuYnNwOyZuYnNwO1RoaXMmbmJzcDtpcyZuYnNwO2JhZCZu YnNwO2NsYXNzJm5ic3A7ZGVzaWduLCZuYnNwO2J1dDxicj4NCnNhdmUmbmJz cDtzb21lJm5ic3A7dHlwaW5nLiZuYnNwOyZuYnNwOyhUaGVyZSdzJm5ic3A7 YWxzbyZuYnNwO3RoZSZuYnNwO2lzc3VlJm5ic3A7dGhhdCZuYnNwO2EmbmJz cDtkZWVwJm5ic3A7Y2xhc3MmbmJzcDtoaWVyYXJjaHk8YnI+DQpzbG93cyZu YnNwO2Rvd24mbmJzcDttZXRob2QmbmJzcDtsb29rdXBzLik8YnI+DQo8YnI+ DQpUaGVyZSZuYnNwO2FyZSZuYnNwO2ZvdXImbmJzcDtjbGFzc2VzJm5ic3A7 aW4mbmJzcDthbiZuYnNwO2luaGVyaXRhbmNlJm5ic3A7ZGlhZ3JhbSZuYnNw O3RoYXQmbmJzcDtyZXByZXNlbnQ8YnI+DQpzeW5jaHJvbm91cyZuYnNwO3Nl cnZlcnMmbmJzcDtvZiZuYnNwO2ZvdXImbmJzcDt0eXBlczo8YnI+DQo8YnI+ DQombmJzcDsmbmJzcDsmbmJzcDsmbmJzcDsmbmJzcDsmbmJzcDsmbmJzcDsm bmJzcDsrLS0tLS0tLS0tLS0rJm5ic3A7Jm5ic3A7Jm5ic3A7Jm5ic3A7Jm5i c3A7Jm5ic3A7Jm5ic3A7Jm5ic3A7Ky0tLS0tLS0tLS0tLS0tLS0tLSs8YnI+ DQombmJzcDsmbmJzcDsmbmJzcDsmbmJzcDsmbmJzcDsmbmJzcDsmbmJzcDsm bmJzcDt8Jm5ic3A7PGEgaHJlZj0iI1RDUFNlcnZlciI+VENQU2VydmVyPC9h PiZuYnNwO3wtLS0tLS0tPnwmbmJzcDs8YSBocmVmPSIjVW5peFN0cmVhbVNl cnZlciI+VW5peFN0cmVhbVNlcnZlcjwvYT4mbmJzcDt8PGJyPg0KJm5ic3A7 Jm5ic3A7Jm5ic3A7Jm5ic3A7Jm5ic3A7Jm5ic3A7Jm5ic3A7Jm5ic3A7Ky0t LS0tLS0tLS0tKyZuYnNwOyZuYnNwOyZuYnNwOyZuYnNwOyZuYnNwOyZuYnNw OyZuYnNwOyZuYnNwOystLS0tLS0tLS0tLS0tLS0tLS0rPGJyPg0KJm5ic3A7 Jm5ic3A7Jm5ic3A7Jm5ic3A7Jm5ic3A7Jm5ic3A7Jm5ic3A7Jm5ic3A7Jm5i c3A7Jm5ic3A7Jm5ic3A7Jm5ic3A7Jm5ic3A7Jm5ic3A7fDxicj4NCiZuYnNw OyZuYnNwOyZuYnNwOyZuYnNwOyZuYnNwOyZuYnNwOyZuYnNwOyZuYnNwOyZu YnNwOyZuYnNwOyZuYnNwOyZuYnNwOyZuYnNwOyZuYnNwO3Y8YnI+DQombmJz cDsmbmJzcDsmbmJzcDsmbmJzcDsmbmJzcDsmbmJzcDsmbmJzcDsmbmJzcDsr LS0tLS0tLS0tLS0rJm5ic3A7Jm5ic3A7Jm5ic3A7Jm5ic3A7Jm5ic3A7Jm5i c3A7Jm5ic3A7Jm5ic3A7Ky0tLS0tLS0tLS0tLS0tLS0tLS0tKzxicj4NCiZu YnNwOyZuYnNwOyZuYnNwOyZuYnNwOyZuYnNwOyZuYnNwOyZuYnNwOyZuYnNw O3wmbmJzcDs8YSBocmVmPSIjVURQU2VydmVyIj5VRFBTZXJ2ZXI8L2E+Jm5i c3A7fC0tLS0tLS0+fCZuYnNwOzxhIGhyZWY9IiNVbml4RGF0YWdyYW1TZXJ2 ZXIiPlVuaXhEYXRhZ3JhbVNlcnZlcjwvYT4mbmJzcDt8PGJyPg0KJm5ic3A7 Jm5ic3A7Jm5ic3A7Jm5ic3A7Jm5ic3A7Jm5ic3A7Jm5ic3A7Jm5ic3A7Ky0t LS0tLS0tLS0tKyZuYnNwOyZuYnNwOyZuYnNwOyZuYnNwOyZuYnNwOyZuYnNw OyZuYnNwOyZuYnNwOystLS0tLS0tLS0tLS0tLS0tLS0tLSs8YnI+DQo8YnI+ DQpOb3RlJm5ic3A7dGhhdCZuYnNwOzxhIGhyZWY9IiNVbml4RGF0YWdyYW1T ZXJ2ZXIiPlVuaXhEYXRhZ3JhbVNlcnZlcjwvYT4mbmJzcDtkZXJpdmVzJm5i c3A7ZnJvbSZuYnNwOzxhIGhyZWY9IiNVRFBTZXJ2ZXIiPlVEUFNlcnZlcjwv YT4sJm5ic3A7bm90Jm5ic3A7ZnJvbTxicj4NCjxhIGhyZWY9IiNVbml4U3Ry ZWFtU2VydmVyIj5Vbml4U3RyZWFtU2VydmVyPC9hPiZuYnNwOy0tJm5ic3A7 dGhlJm5ic3A7b25seSZuYnNwO2RpZmZlcmVuY2UmbmJzcDtiZXR3ZWVuJm5i c3A7YW4mbmJzcDtJUCZuYnNwO2FuZCZuYnNwO2EmbmJzcDtVbml4PGJyPg0K c3RyZWFtJm5ic3A7c2VydmVyJm5ic3A7aXMmbmJzcDt0aGUmbmJzcDthZGRy ZXNzJm5ic3A7ZmFtaWx5LCZuYnNwO3doaWNoJm5ic3A7aXMmbmJzcDtzaW1w bHkmbmJzcDtyZXBlYXRlZCZuYnNwO2luJm5ic3A7Ym90aDxicj4NCnVuaXgm bmJzcDtzZXJ2ZXImbmJzcDtjbGFzc2VzLjxicj4NCjxicj4NCkZvcmtpbmcm bmJzcDthbmQmbmJzcDt0aHJlYWRpbmcmbmJzcDt2ZXJzaW9ucyZuYnNwO29m Jm5ic3A7ZWFjaCZuYnNwO3R5cGUmbmJzcDtvZiZuYnNwO3NlcnZlciZuYnNw O2NhbiZuYnNwO2JlJm5ic3A7Y3JlYXRlZDxicj4NCnVzaW5nJm5ic3A7dGhl Jm5ic3A7Rm9ya2luZ1NlcnZlciZuYnNwO2FuZCZuYnNwO1RocmVhZGluZ1Nl cnZlciZuYnNwO21peC1pbiZuYnNwO2NsYXNzZXMuJm5ic3A7Jm5ic3A7Rm9y PGJyPg0KaW5zdGFuY2UsJm5ic3A7YSZuYnNwO3RocmVhZGluZyZuYnNwO1VE UCZuYnNwO3NlcnZlciZuYnNwO2NsYXNzJm5ic3A7aXMmbmJzcDtjcmVhdGVk Jm5ic3A7YXMmbmJzcDtmb2xsb3dzOjxicj4NCjxicj4NCiZuYnNwOyZuYnNw OyZuYnNwOyZuYnNwOyZuYnNwOyZuYnNwOyZuYnNwOyZuYnNwO2NsYXNzJm5i c3A7PGEgaHJlZj0iI1RocmVhZGluZ1VEUFNlcnZlciI+VGhyZWFkaW5nVURQ U2VydmVyPC9hPig8YSBocmVmPSIjVGhyZWFkaW5nTWl4SW4iPlRocmVhZGlu Z01peEluPC9hPiwmbmJzcDs8YSBocmVmPSIjVURQU2VydmVyIj5VRFBTZXJ2 ZXI8L2E+KTombmJzcDtwYXNzPGJyPg0KPGJyPg0KVGhlJm5ic3A7TWl4LWlu Jm5ic3A7Y2xhc3MmbmJzcDttdXN0Jm5ic3A7Y29tZSZuYnNwO2ZpcnN0LCZu YnNwO3NpbmNlJm5ic3A7aXQmbmJzcDtvdmVycmlkZXMmbmJzcDthJm5ic3A7 bWV0aG9kJm5ic3A7ZGVmaW5lZDxicj4NCmluJm5ic3A7PGEgaHJlZj0iI1VE UFNlcnZlciI+VURQU2VydmVyPC9hPiE8YnI+DQo8YnI+DQpUbyZuYnNwO2lt cGxlbWVudCZuYnNwO2EmbmJzcDtzZXJ2aWNlLCZuYnNwO3lvdSZuYnNwO211 c3QmbmJzcDtkZXJpdmUmbmJzcDthJm5ic3A7Y2xhc3MmbmJzcDtmcm9tPGJy Pg0KPGEgaHJlZj0iI0Jhc2VSZXF1ZXN0SGFuZGxlciI+QmFzZVJlcXVlc3RI YW5kbGVyPC9hPiZuYnNwO2FuZCZuYnNwO3JlZGVmaW5lJm5ic3A7aXRzJm5i c3A7aGFuZGxlKCkmbmJzcDttZXRob2QuJm5ic3A7Jm5ic3A7WW91Jm5ic3A7 Y2FuJm5ic3A7dGhlbiZuYnNwO3J1bjxicj4NCnZhcmlvdXMmbmJzcDt2ZXJz aW9ucyZuYnNwO29mJm5ic3A7dGhlJm5ic3A7c2VydmljZSZuYnNwO2J5Jm5i c3A7Y29tYmluaW5nJm5ic3A7b25lJm5ic3A7b2YmbmJzcDt0aGUmbmJzcDtz ZXJ2ZXImbmJzcDtjbGFzc2VzPGJyPg0Kd2l0aCZuYnNwO3lvdXImbmJzcDty ZXF1ZXN0Jm5ic3A7aGFuZGxlciZuYnNwO2NsYXNzLjxicj4NCjxicj4NClRo ZSZuYnNwO3JlcXVlc3QmbmJzcDtoYW5kbGVyJm5ic3A7Y2xhc3MmbmJzcDtt dXN0Jm5ic3A7YmUmbmJzcDtkaWZmZXJlbnQmbmJzcDtmb3ImbmJzcDtkYXRh Z3JhbSZuYnNwO29yJm5ic3A7c3RyZWFtPGJyPg0Kc2VydmljZXMuJm5ic3A7 Jm5ic3A7VGhpcyZuYnNwO2NhbiZuYnNwO2JlJm5ic3A7aGlkZGVuJm5ic3A7 YnkmbmJzcDt1c2luZyZuYnNwO3RoZSZuYnNwO21peC1pbiZuYnNwO3JlcXVl c3QmbmJzcDtoYW5kbGVyPGJyPg0KY2xhc3NlcyZuYnNwOzxhIGhyZWY9IiNT dHJlYW1SZXF1ZXN0SGFuZGxlciI+U3RyZWFtUmVxdWVzdEhhbmRsZXI8L2E+ Jm5ic3A7b3ImbmJzcDs8YSBocmVmPSIjRGF0YWdyYW1SZXF1ZXN0SGFuZGxl ciI+RGF0YWdyYW1SZXF1ZXN0SGFuZGxlcjwvYT4uPGJyPg0KPGJyPg0KT2Ym bmJzcDtjb3Vyc2UsJm5ic3A7eW91Jm5ic3A7c3RpbGwmbmJzcDtoYXZlJm5i c3A7dG8mbmJzcDt1c2UmbmJzcDt5b3VyJm5ic3A7aGVhZCE8YnI+DQo8YnI+ DQpGb3ImbmJzcDtpbnN0YW5jZSwmbmJzcDtpdCZuYnNwO21ha2VzJm5ic3A7 bm8mbmJzcDtzZW5zZSZuYnNwO3RvJm5ic3A7dXNlJm5ic3A7YSZuYnNwO2Zv cmtpbmcmbmJzcDtzZXJ2ZXImbmJzcDtpZiZuYnNwO3RoZSZuYnNwO3NlcnZp Y2U8YnI+DQpjb250YWlucyZuYnNwO3N0YXRlJm5ic3A7aW4mbmJzcDttZW1v cnkmbmJzcDt0aGF0Jm5ic3A7Y2FuJm5ic3A7YmUmbmJzcDttb2RpZmllZCZu YnNwO2J5Jm5ic3A7cmVxdWVzdHMmbmJzcDsoc2luY2UmbmJzcDt0aGU8YnI+ DQptb2RpZmljYXRpb25zJm5ic3A7aW4mbmJzcDt0aGUmbmJzcDtjaGlsZCZu YnNwO3Byb2Nlc3MmbmJzcDt3b3VsZCZuYnNwO25ldmVyJm5ic3A7cmVhY2gm bmJzcDt0aGUmbmJzcDtpbml0aWFsJm5ic3A7c3RhdGU8YnI+DQprZXB0Jm5i c3A7aW4mbmJzcDt0aGUmbmJzcDtwYXJlbnQmbmJzcDtwcm9jZXNzJm5ic3A7 YW5kJm5ic3A7cGFzc2VkJm5ic3A7dG8mbmJzcDtlYWNoJm5ic3A7Y2hpbGQp LiZuYnNwOyZuYnNwO0luJm5ic3A7dGhpcyZuYnNwO2Nhc2UsPGJyPg0KeW91 Jm5ic3A7Y2FuJm5ic3A7dXNlJm5ic3A7YSZuYnNwO3RocmVhZGluZyZuYnNw O3NlcnZlciwmbmJzcDtidXQmbmJzcDt5b3UmbmJzcDt3aWxsJm5ic3A7cHJv YmFibHkmbmJzcDtoYXZlJm5ic3A7dG8mbmJzcDt1c2U8YnI+DQpsb2NrcyZu YnNwO3RvJm5ic3A7YXZvaWQmbmJzcDt0d28mbmJzcDtyZXF1ZXN0cyZuYnNw O3RoYXQmbmJzcDtjb21lJm5ic3A7aW4mbmJzcDtuZWFybHkmbmJzcDtzaW11 bHRhbmVvdXMmbmJzcDt0byZuYnNwO2FwcGx5PGJyPg0KY29uZmxpY3Rpbmcm bmJzcDtjaGFuZ2VzJm5ic3A7dG8mbmJzcDt0aGUmbmJzcDtzZXJ2ZXImbmJz cDtzdGF0ZS48YnI+DQo8YnI+DQpPbiZuYnNwO3RoZSZuYnNwO290aGVyJm5i c3A7aGFuZCwmbmJzcDtpZiZuYnNwO3lvdSZuYnNwO2FyZSZuYnNwO2J1aWxk aW5nJm5ic3A7ZS5nLiZuYnNwO2FuJm5ic3A7SFRUUCZuYnNwO3NlcnZlciwm bmJzcDt3aGVyZSZuYnNwO2FsbDxicj4NCmRhdGEmbmJzcDtpcyZuYnNwO3N0 b3JlZCZuYnNwO2V4dGVybmFsbHkmbmJzcDsoZS5nLiZuYnNwO2luJm5ic3A7 dGhlJm5ic3A7ZmlsZSZuYnNwO3N5c3RlbSksJm5ic3A7YSZuYnNwO3N5bmNo cm9ub3VzPGJyPg0KY2xhc3MmbmJzcDt3aWxsJm5ic3A7ZXNzZW50aWFsbHkm bmJzcDtyZW5kZXImbmJzcDt0aGUmbmJzcDtzZXJ2aWNlJm5ic3A7ImRlYWYi Jm5ic3A7d2hpbGUmbmJzcDtvbmUmbmJzcDtyZXF1ZXN0Jm5ic3A7aXM8YnI+ DQpiZWluZyZuYnNwO2hhbmRsZWQmbmJzcDstLSZuYnNwO3doaWNoJm5ic3A7 bWF5Jm5ic3A7YmUmbmJzcDtmb3ImbmJzcDthJm5ic3A7dmVyeSZuYnNwO2xv bmcmbmJzcDt0aW1lJm5ic3A7aWYmbmJzcDthJm5ic3A7Y2xpZW50Jm5ic3A7 aXMmbmJzcDtzbG93PGJyPg0KdG8mbmJzcDtyZXFkJm5ic3A7YWxsJm5ic3A7 dGhlJm5ic3A7ZGF0YSZuYnNwO2l0Jm5ic3A7aGFzJm5ic3A7cmVxdWVzdGVk LiZuYnNwOyZuYnNwO0hlcmUmbmJzcDthJm5ic3A7dGhyZWFkaW5nJm5ic3A7 b3ImbmJzcDtmb3JraW5nPGJyPg0Kc2VydmVyJm5ic3A7aXMmbmJzcDthcHBy b3ByaWF0ZS48YnI+DQo8YnI+DQpJbiZuYnNwO3NvbWUmbmJzcDtjYXNlcywm bmJzcDtpdCZuYnNwO21heSZuYnNwO2JlJm5ic3A7YXBwcm9wcmlhdGUmbmJz cDt0byZuYnNwO3Byb2Nlc3MmbmJzcDtwYXJ0Jm5ic3A7b2YmbmJzcDthJm5i c3A7cmVxdWVzdDxicj4NCnN5bmNocm9ub3VzbHksJm5ic3A7YnV0Jm5ic3A7 dG8mbmJzcDtmaW5pc2gmbmJzcDtwcm9jZXNzaW5nJm5ic3A7aW4mbmJzcDth Jm5ic3A7Zm9ya2VkJm5ic3A7Y2hpbGQmbmJzcDtkZXBlbmRpbmcmbmJzcDtv bjxicj4NCnRoZSZuYnNwO3JlcXVlc3QmbmJzcDtkYXRhLiZuYnNwOyZuYnNw O1RoaXMmbmJzcDtjYW4mbmJzcDtiZSZuYnNwO2ltcGxlbWVudGVkJm5ic3A7 YnkmbmJzcDt1c2luZyZuYnNwO2EmbmJzcDtzeW5jaHJvbm91czxicj4NCnNl cnZlciZuYnNwO2FuZCZuYnNwO2RvaW5nJm5ic3A7YW4mbmJzcDtleHBsaWNp dCZuYnNwO2ZvcmsmbmJzcDtpbiZuYnNwO3RoZSZuYnNwO3JlcXVlc3QmbmJz cDtoYW5kbGVyJm5ic3A7Y2xhc3Mnczxicj4NCmhhbmRsZSgpJm5ic3A7bWV0 aG9kLjxicj4NCjxicj4NCkFub3RoZXImbmJzcDthcHByb2FjaCZuYnNwO3Rv Jm5ic3A7aGFuZGxpbmcmbmJzcDttdWx0aXBsZSZuYnNwO3NpbXVsdGFuZW91 cyZuYnNwO3JlcXVlc3RzJm5ic3A7aW4mbmJzcDthbjxicj4NCmVudmlyb25t ZW50Jm5ic3A7dGhhdCZuYnNwO3N1cHBvcnRzJm5ic3A7bmVpdGhlciZuYnNw O3RocmVhZHMmbmJzcDtub3ImbmJzcDtmb3JrJm5ic3A7KG9yJm5ic3A7d2hl cmUmbmJzcDt0aGVzZSZuYnNwO2FyZTxicj4NCnRvbyZuYnNwO2V4cGVuc2l2 ZSZuYnNwO29yJm5ic3A7aW5hcHByb3ByaWF0ZSZuYnNwO2ZvciZuYnNwO3Ro ZSZuYnNwO3NlcnZpY2UpJm5ic3A7aXMmbmJzcDt0byZuYnNwO21haW50YWlu Jm5ic3A7YW48YnI+DQpleHBsaWNpdCZuYnNwO3RhYmxlJm5ic3A7b2YmbmJz cDtwYXJ0aWFsbHkmbmJzcDtmaW5pc2hlZCZuYnNwO3JlcXVlc3RzJm5ic3A7 YW5kJm5ic3A7dG8mbmJzcDt1c2UmbmJzcDtzZWxlY3QoKSZuYnNwO3RvPGJy Pg0KZGVjaWRlJm5ic3A7d2hpY2gmbmJzcDtyZXF1ZXN0Jm5ic3A7dG8mbmJz cDt3b3JrJm5ic3A7b24mbmJzcDtuZXh0Jm5ic3A7KG9yJm5ic3A7d2hldGhl ciZuYnNwO3RvJm5ic3A7aGFuZGxlJm5ic3A7YSZuYnNwO25ldzxicj4NCmlu Y29taW5nJm5ic3A7cmVxdWVzdCkuJm5ic3A7Jm5ic3A7VGhpcyZuYnNwO2lz Jm5ic3A7cGFydGljdWxhcmx5Jm5ic3A7aW1wb3J0YW50Jm5ic3A7Zm9yJm5i c3A7c3RyZWFtJm5ic3A7c2VydmljZXM8YnI+DQp3aGVyZSZuYnNwO2VhY2gm bmJzcDtjbGllbnQmbmJzcDtjYW4mbmJzcDtwb3RlbnRpYWxseSZuYnNwO2Jl Jm5ic3A7Y29ubmVjdGVkJm5ic3A7Zm9yJm5ic3A7YSZuYnNwO2xvbmcmbmJz cDt0aW1lJm5ic3A7KGlmPGJyPg0KdGhyZWFkcyZuYnNwO29yJm5ic3A7c3Vi cHJvY2Vzc2VzJm5ic3A7Y2FuJ3QmbmJzcDtiZSZuYnNwO3VzZWQpLjxicj4N Cjxicj4NCkZ1dHVyZSZuYnNwO3dvcms6PGJyPg0KLSZuYnNwO1N0YW5kYXJk Jm5ic3A7Y2xhc3NlcyZuYnNwO2ZvciZuYnNwO1N1biZuYnNwO1JQQyZuYnNw Oyh3aGljaCZuYnNwO3VzZXMmbmJzcDtlaXRoZXImbmJzcDtVRFAmbmJzcDtv ciZuYnNwO1RDUCk8YnI+DQotJm5ic3A7U3RhbmRhcmQmbmJzcDttaXgtaW4m bmJzcDtjbGFzc2VzJm5ic3A7dG8mbmJzcDtpbXBsZW1lbnQmbmJzcDt2YXJp b3VzJm5ic3A7YXV0aGVudGljYXRpb248YnI+DQombmJzcDsmbmJzcDthbmQm bmJzcDtlbmNyeXB0aW9uJm5ic3A7c2NoZW1lczxicj4NCi0mbmJzcDtTdGFu ZGFyZCZuYnNwO2ZyYW1ld29yayZuYnNwO2ZvciZuYnNwO3NlbGVjdC1iYXNl ZCZuYnNwO211bHRpcGxleGluZzxicj4NCjxicj4NClhYWCZuYnNwO09wZW4m bmJzcDtwcm9ibGVtczo8YnI+DQotJm5ic3A7V2hhdCZuYnNwO3RvJm5ic3A7 ZG8mbmJzcDt3aXRoJm5ic3A7b3V0LW9mLWJhbmQmbmJzcDtkYXRhPzwvdHQ+ PC9zbWFsbD48L3A+DQo8cD48dGFibGUgd2lkdGg9IjEwMCUiIGNlbGxzcGFj aW5nPTAgY2VsbHBhZGRpbmc9MCBib3JkZXI9MD4NCjx0cj48dGQgYmdjb2xv cj0iI2FhNTVjYyIgY29sc3Bhbj0zPjxzbWFsbD48c21hbGw+PGJyPjwvc21h bGw+PC9zbWFsbA0KPjxmb250IGNvbG9yPSIjZmZmZmZmIiBmYWNlPSJoZWx2 ZXRpY2EiPiZuYnNwOzxiaWc+PHN0cm9uZz5Nb2R1bGVzPC9zdHJvbmc+PC9i aWc+PC9mb250PjwvdGQ+PC90cj4NCjx0cj48dGQgYmdjb2xvcj0iI2FhNTVj YyIgd2lkdGg9NzA+PGltZyBzcmM9Ii9zcGFjZXIuZ2lmIiB3aWR0aD03MCBo ZWlnaHQ9MT48L3RkPjx0ZD48aW1nIHNyYz0iL3NwYWNlci5naWYiIHdpZHRo PTEwIGhlaWdodD0xPjwvdGQ+PHRkPg0KPGZvbnQgc2l6ZT0iLTMiIGNvbG9y PSIjZmZmZmZmIj5fIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8g XyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBf IF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8g XyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBf IF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8g XyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyA8YnI+PC9mb250Pg0KPHRhYmxl IHdpZHRoPSIxMDAlIj48dHI+DQo8dGQgd2lkdGg9IjI1JSIgdmFsaWduPXRv cD4NCjxhIGhyZWY9Ii9waW5nL21hbnB5LmNnaT9vcyI+b3M8L2E+PGJyPg0K PC90ZD4NCjx0ZCB3aWR0aD0iMjUlIiB2YWxpZ249dG9wPg0KPGEgaHJlZj0i L3BpbmcvbWFucHkuY2dpP3NvY2tldCI+c29ja2V0PC9hPjxicj4NCjwvdGQ+ DQo8dGQgd2lkdGg9IjI1JSIgdmFsaWduPXRvcD4NCjxhIGhyZWY9Ii9waW5n L21hbnB5LmNnaT9zeXMiPnN5czwvYT48YnI+DQo8L3RkPg0KPHRkIHdpZHRo PSIyNSUiIHZhbGlnbj10b3A+DQo8L3RkPg0KPC90cj48L3RhYmxlPg0KPC90 ZD48L3RyPjwvdGFibGU+DQo8cD48dGFibGUgd2lkdGg9IjEwMCUiIGNlbGxz cGFjaW5nPTAgY2VsbHBhZGRpbmc9MCBib3JkZXI9MD4NCjx0cj48dGQgYmdj b2xvcj0iI2VlNzdhYSIgY29sc3Bhbj0zPjxzbWFsbD48c21hbGw+PGJyPjwv c21hbGw+PC9zbWFsbA0KPjxmb250IGNvbG9yPSIjZmZmZmZmIiBmYWNlPSJo ZWx2ZXRpY2EiPiZuYnNwOzxiaWc+PHN0cm9uZz5DbGFzc2VzPC9zdHJvbmc+ PC9iaWc+PC9mb250PjwvdGQ+PC90cj4NCjx0cj48dGQgYmdjb2xvcj0iI2Vl NzdhYSIgd2lkdGg9NzA+PGltZyBzcmM9Ii9zcGFjZXIuZ2lmIiB3aWR0aD03 MCBoZWlnaHQ9MT48L3RkPjx0ZD48aW1nIHNyYz0iL3NwYWNlci5naWYiIHdp ZHRoPTEwIGhlaWdodD0xPjwvdGQ+PHRkPg0KPGZvbnQgc2l6ZT0iLTMiIGNv bG9yPSIjZmZmZmZmIj48YnI+PC9mb250Pg0KPHNtYWxsPjxmb250IGZhY2U9 ImhlbHZldGljYSI+DQo8ZGw+DQo8ZHQ+PGEgaHJlZj0iI0Jhc2VSZXF1ZXN0 SGFuZGxlciI+QmFzZVJlcXVlc3RIYW5kbGVyPC9hPg0KPGRkPg0KPGRsPg0K PGR0PjxhIGhyZWY9IiNEYXRhZ3JhbVJlcXVlc3RIYW5kbGVyIj5EYXRhZ3Jh bVJlcXVlc3RIYW5kbGVyPC9hPg0KPGR0PjxhIGhyZWY9IiNTdHJlYW1SZXF1 ZXN0SGFuZGxlciI+U3RyZWFtUmVxdWVzdEhhbmRsZXI8L2E+DQo8L2RsPg0K PGR0PjxhIGhyZWY9IiNGb3JraW5nTWl4SW4iPkZvcmtpbmdNaXhJbjwvYT4N CjxkZD4NCjxkbD4NCjxkdD48YSBocmVmPSIjRm9ya2luZ1RDUFNlcnZlciI+ Rm9ya2luZ1RDUFNlcnZlcjwvYT4oPGEgaHJlZj0iI0ZvcmtpbmdNaXhJbiI+ Rm9ya2luZ01peEluPC9hPiwgPGEgaHJlZj0iI1RDUFNlcnZlciI+VENQU2Vy dmVyPC9hPikNCjxkdD48YSBocmVmPSIjRm9ya2luZ1VEUFNlcnZlciI+Rm9y a2luZ1VEUFNlcnZlcjwvYT4oPGEgaHJlZj0iI0ZvcmtpbmdNaXhJbiI+Rm9y a2luZ01peEluPC9hPiwgPGEgaHJlZj0iI1VEUFNlcnZlciI+VURQU2VydmVy PC9hPikNCjwvZGw+DQo8ZHQ+PGEgaHJlZj0iI1RDUFNlcnZlciI+VENQU2Vy dmVyPC9hPg0KPGRkPg0KPGRsPg0KPGR0PjxhIGhyZWY9IiNVRFBTZXJ2ZXIi PlVEUFNlcnZlcjwvYT4NCjxkZD4NCjxkbD4NCjxkdD48YSBocmVmPSIjVW5p eERhdGFncmFtU2VydmVyIj5Vbml4RGF0YWdyYW1TZXJ2ZXI8L2E+DQo8L2Rs Pg0KPGR0PjxhIGhyZWY9IiNVbml4U3RyZWFtU2VydmVyIj5Vbml4U3RyZWFt U2VydmVyPC9hPg0KPC9kbD4NCjxkdD48YSBocmVmPSIjVGhyZWFkaW5nTWl4 SW4iPlRocmVhZGluZ01peEluPC9hPg0KPGRkPg0KPGRsPg0KPGR0PjxhIGhy ZWY9IiNUaHJlYWRpbmdUQ1BTZXJ2ZXIiPlRocmVhZGluZ1RDUFNlcnZlcjwv YT4oPGEgaHJlZj0iI1RDUFNlcnZlciI+VENQU2VydmVyPC9hPiwgPGEgaHJl Zj0iI1RocmVhZGluZ01peEluIj5UaHJlYWRpbmdNaXhJbjwvYT4pDQo8ZHQ+ PGEgaHJlZj0iI1RocmVhZGluZ1VEUFNlcnZlciI+VGhyZWFkaW5nVURQU2Vy dmVyPC9hPig8YSBocmVmPSIjVGhyZWFkaW5nTWl4SW4iPlRocmVhZGluZ01p eEluPC9hPiwgPGEgaHJlZj0iI1VEUFNlcnZlciI+VURQU2VydmVyPC9hPikN CjxkdD48YSBocmVmPSIjVGhyZWFkaW5nVW5peERhdGFncmFtU2VydmVyIj5U aHJlYWRpbmdVbml4RGF0YWdyYW1TZXJ2ZXI8L2E+KDxhIGhyZWY9IiNUaHJl YWRpbmdNaXhJbiI+VGhyZWFkaW5nTWl4SW48L2E+LCA8YSBocmVmPSIjVW5p eERhdGFncmFtU2VydmVyIj5Vbml4RGF0YWdyYW1TZXJ2ZXI8L2E+KQ0KPGR0 PjxhIGhyZWY9IiNUaHJlYWRpbmdVbml4U3RyZWFtU2VydmVyIj5UaHJlYWRp bmdVbml4U3RyZWFtU2VydmVyPC9hPig8YSBocmVmPSIjVGhyZWFkaW5nTWl4 SW4iPlRocmVhZGluZ01peEluPC9hPiwgPGEgaHJlZj0iI1VuaXhTdHJlYW1T ZXJ2ZXIiPlVuaXhTdHJlYW1TZXJ2ZXI8L2E+KQ0KPC9kbD4NCjwvZGw+DQo8 L2ZvbnQ+PC9zbWFsbD4NCjxwPjx0YWJsZSB3aWR0aD0iMTAwJSIgY2VsbHNw YWNpbmc9MCBjZWxscGFkZGluZz0wIGJvcmRlcj0wPg0KPHRyPjx0ZCBiZ2Nv bG9yPSIjZmZjOGQ4IiBjb2xzcGFuPTM+PHNtYWxsPjxzbWFsbD48YnI+PC9z bWFsbD48L3NtYWxsDQo+PGZvbnQgY29sb3I9IiMwMDAwMDAiIGZhY2U9Imhl bHZldGljYSI+Jm5ic3A7PGEgbmFtZT0iQmFzZVJlcXVlc3RIYW5kbGVyIj5j bGFzcyA8c3Ryb25nPkJhc2VSZXF1ZXN0SGFuZGxlcjwvc3Ryb25nPjwvYT48 L2ZvbnQ+PGRkPjxzbWFsbD48dHQ+QmFzZSZuYnNwO2NsYXNzJm5ic3A7Zm9y Jm5ic3A7cmVxdWVzdCZuYnNwO2hhbmRsZXImbmJzcDtjbGFzc2VzLjxicj4N CjxkZD48YnI+DQo8ZGQ+VGhpcyZuYnNwO2NsYXNzJm5ic3A7aXMmbmJzcDtp bnN0YW50aWF0ZWQmbmJzcDtmb3ImbmJzcDtlYWNoJm5ic3A7cmVxdWVzdCZu YnNwO3RvJm5ic3A7YmUmbmJzcDtoYW5kbGVkLiZuYnNwOyZuYnNwO1RoZTxi cj4NCjxkZD5jb25zdHJ1Y3RvciZuYnNwO3NldHMmbmJzcDt0aGUmbmJzcDtp bnN0YW5jZSZuYnNwO3ZhcmlhYmxlcyZuYnNwO3JlcXVlc3QsJm5ic3A7Y2xp ZW50X2FkZHJlc3M8YnI+DQo8ZGQ+YW5kJm5ic3A7c2VydmVyLCZuYnNwO2Fu ZCZuYnNwO3RoZW4mbmJzcDtjYWxscyZuYnNwO3RoZSZuYnNwOzxhIGhyZWY9 IiNCYXNlUmVxdWVzdEhhbmRsZXItaGFuZGxlIj5oYW5kbGU8L2E+KCkmbmJz cDttZXRob2QuJm5ic3A7Jm5ic3A7VG8mbmJzcDtpbXBsZW1lbnQmbmJzcDth PGJyPg0KPGRkPnNwZWNpZmljJm5ic3A7c2VydmljZSwmbmJzcDthbGwmbmJz cDt5b3UmbmJzcDtuZWVkJm5ic3A7dG8mbmJzcDtkbyZuYnNwO2lzJm5ic3A7 dG8mbmJzcDtkZXJpdmUmbmJzcDthJm5ic3A7Y2xhc3MmbmJzcDt3aGljaDxi cj4NCjxkZD5kZWZpbmVzJm5ic3A7YSZuYnNwOzxhIGhyZWY9IiNCYXNlUmVx dWVzdEhhbmRsZXItaGFuZGxlIj5oYW5kbGU8L2E+KCkmbmJzcDttZXRob2Qu PGJyPg0KPGRkPjxicj4NCjxkZD5UaGUmbmJzcDs8YSBocmVmPSIjQmFzZVJl cXVlc3RIYW5kbGVyLWhhbmRsZSI+aGFuZGxlPC9hPigpJm5ic3A7bWV0aG9k Jm5ic3A7Y2FuJm5ic3A7ZmluZCZuYnNwO3RoZSZuYnNwO3JlcXVlc3QmbmJz cDthcyZuYnNwO3NlbGYuPHN0cm9uZz5yZXF1ZXN0PC9zdHJvbmc+LCZuYnNw O3RoZTxicj4NCjxkZD5jbGllbnQmbmJzcDthZGRyZXNzJm5ic3A7YXMmbmJz cDtzZWxmLjxzdHJvbmc+Y2xpZW50X2FkZHJlc3M8L3N0cm9uZz4sJm5ic3A7 YW5kJm5ic3A7dGhlJm5ic3A7c2VydmVyJm5ic3A7KGluJm5ic3A7Y2FzZSZu YnNwO2l0PGJyPg0KPGRkPm5lZWRzJm5ic3A7YWNjZXNzJm5ic3A7dG8mbmJz cDtwZXItc2VydmVyJm5ic3A7aW5mb3JtYXRpb24pJm5ic3A7YXMmbmJzcDtz ZWxmLjxzdHJvbmc+c2VydmVyPC9zdHJvbmc+LiZuYnNwOyZuYnNwO1NpbmNl Jm5ic3A7YTxicj4NCjxkZD5zZXBhcmF0ZSZuYnNwO2luc3RhbmNlJm5ic3A7 aXMmbmJzcDtjcmVhdGVkJm5ic3A7Zm9yJm5ic3A7ZWFjaCZuYnNwO3JlcXVl c3QsJm5ic3A7dGhlJm5ic3A7PGEgaHJlZj0iI0Jhc2VSZXF1ZXN0SGFuZGxl ci1oYW5kbGUiPmhhbmRsZTwvYT4oKSZuYnNwO21ldGhvZDxicj4NCjxkZD5j YW4mbmJzcDtkZWZpbmUmbmJzcDthcmJpdHJhcnkmbmJzcDtvdGhlciZuYnNw O2luc3RhbmNlJm5ic3A7dmFyaWFyaWFibGVzLjwvdHQ+PC9zbWFsbD48L3A+ PC9mb250PjwvdGQ+PC90cj4NCjx0cj48dGQgYmdjb2xvcj0iI2ZmYzhkOCIg d2lkdGg9NDA+PGltZyBzcmM9Ii9zcGFjZXIuZ2lmIiB3aWR0aD00MCBoZWln aHQ9MT48L3RkPjx0ZD48aW1nIHNyYz0iL3NwYWNlci5naWYiIHdpZHRoPTEw IGhlaWdodD0xPjwvdGQ+PHRkPg0KPGZvbnQgc2l6ZT0iLTMiIGNvbG9yPSIj ZmZmZmZmIj5fIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBf IF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8g XyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBf IF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8g XyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBf IF8gXyBfIF8gXyBfIF8gXyBfIF8gXyA8YnI+PC9mb250Pg0KPGR0PjxhIG5h bWU9IkJhc2VSZXF1ZXN0SGFuZGxlci1fX2RlbF9fIj4gPHN0cm9uZz5fX2Rl bF9fPC9zdHJvbmc+KHNlbGYpOjwvYT4NCjxkZD48c21hbGw+PGVtPm5vIGRv YyBzdHJpbmcgYXZhaWxhYmxlPC9lbT48L3NtYWxsPjxwPg0KPGR0PjxhIG5h bWU9IkJhc2VSZXF1ZXN0SGFuZGxlci1fX2luaXRfXyI+IDxzdHJvbmc+X19p bml0X188L3N0cm9uZz4oc2VsZiwgcmVxdWVzdCwgY2xpZW50X2FkZHJlc3Ms IHNlcnZlcik6PC9hPg0KPGRkPjxzbWFsbD48ZW0+bm8gZG9jIHN0cmluZyBh dmFpbGFibGU8L2VtPjwvc21hbGw+PHA+DQo8ZHQ+PGEgbmFtZT0iQmFzZVJl cXVlc3RIYW5kbGVyLWZpbmlzaCI+IDxzdHJvbmc+ZmluaXNoPC9zdHJvbmc+ KHNlbGYpOjwvYT4NCjxkZD48c21hbGw+PGVtPm5vIGRvYyBzdHJpbmcgYXZh aWxhYmxlPC9lbT48L3NtYWxsPjxwPg0KPGR0PjxhIG5hbWU9IkJhc2VSZXF1 ZXN0SGFuZGxlci1oYW5kbGUiPiA8c3Ryb25nPmhhbmRsZTwvc3Ryb25nPihz ZWxmKTo8L2E+DQo8ZGQ+PHNtYWxsPjxlbT5ubyBkb2Mgc3RyaW5nIGF2YWls YWJsZTwvZW0+PC9zbWFsbD48cD4NCjxkdD48YSBuYW1lPSJCYXNlUmVxdWVz dEhhbmRsZXItc2V0dXAiPiA8c3Ryb25nPnNldHVwPC9zdHJvbmc+KHNlbGYp OjwvYT4NCjxkZD48c21hbGw+PGVtPm5vIGRvYyBzdHJpbmcgYXZhaWxhYmxl PC9lbT48L3NtYWxsPjxwPg0KPC90ZD48L3RyPjwvdGFibGU+DQo8cD48dGFi bGUgd2lkdGg9IjEwMCUiIGNlbGxzcGFjaW5nPTAgY2VsbHBhZGRpbmc9MCBi b3JkZXI9MD4NCjx0cj48dGQgYmdjb2xvcj0iI2ZmYzhkOCIgY29sc3Bhbj0z PjxzbWFsbD48c21hbGw+PGJyPjwvc21hbGw+PC9zbWFsbA0KPjxmb250IGNv bG9yPSIjMDAwMDAwIiBmYWNlPSJoZWx2ZXRpY2EiPiZuYnNwOzxhIG5hbWU9 IkRhdGFncmFtUmVxdWVzdEhhbmRsZXIiPmNsYXNzIDxzdHJvbmc+RGF0YWdy YW1SZXF1ZXN0SGFuZGxlcjwvc3Ryb25nPig8YSBocmVmPSIjQmFzZVJlcXVl c3RIYW5kbGVyIj5CYXNlUmVxdWVzdEhhbmRsZXI8L2E+KTwvYT48L2ZvbnQ+ PGRkPjxzbWFsbD48dHQ+RGVmaW5lJm5ic3A7c2VsZi48c3Ryb25nPnJmaWxl PC9zdHJvbmc+Jm5ic3A7YW5kJm5ic3A7c2VsZi48c3Ryb25nPndmaWxlPC9z dHJvbmc+Jm5ic3A7Zm9yJm5ic3A7ZGF0YWdyYW0mbmJzcDtzb2NrZXRzLjwv dHQ+PC9zbWFsbD48L3A+PC9mb250PjwvdGQ+PC90cj4NCjx0cj48dGQgYmdj b2xvcj0iI2ZmYzhkOCIgd2lkdGg9NDA+PGltZyBzcmM9Ii9zcGFjZXIuZ2lm IiB3aWR0aD00MCBoZWlnaHQ9MT48L3RkPjx0ZD48aW1nIHNyYz0iL3NwYWNl ci5naWYiIHdpZHRoPTEwIGhlaWdodD0xPjwvdGQ+PHRkPg0KPGZvbnQgc2l6 ZT0iLTMiIGNvbG9yPSIjZmZmZmZmIj5fIF8gXyBfIF8gXyBfIF8gXyBfIF8g XyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBf IF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8g XyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBf IF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8g XyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyA8YnI+PC9m b250Pg0KPGR0PjxhIG5hbWU9IkRhdGFncmFtUmVxdWVzdEhhbmRsZXItZmlu aXNoIj4gPHN0cm9uZz5maW5pc2g8L3N0cm9uZz4oc2VsZik6PC9hPg0KPGRk PjxzbWFsbD48ZW0+bm8gZG9jIHN0cmluZyBhdmFpbGFibGU8L2VtPjwvc21h bGw+PHA+DQo8ZHQ+PGEgbmFtZT0iRGF0YWdyYW1SZXF1ZXN0SGFuZGxlci1z ZXR1cCI+IDxzdHJvbmc+c2V0dXA8L3N0cm9uZz4oc2VsZik6PC9hPg0KPGRk PjxzbWFsbD48ZW0+bm8gZG9jIHN0cmluZyBhdmFpbGFibGU8L2VtPjwvc21h bGw+PHA+DQo8L3RkPjwvdHI+PC90YWJsZT4NCjxwPjx0YWJsZSB3aWR0aD0i MTAwJSIgY2VsbHNwYWNpbmc9MCBjZWxscGFkZGluZz0wIGJvcmRlcj0wPg0K PHRyPjx0ZCBiZ2NvbG9yPSIjZmZjOGQ4IiBjb2xzcGFuPTM+PHNtYWxsPjxz bWFsbD48YnI+PC9zbWFsbD48L3NtYWxsDQo+PGZvbnQgY29sb3I9IiMwMDAw MDAiIGZhY2U9ImhlbHZldGljYSI+Jm5ic3A7PGEgbmFtZT0iRm9ya2luZ01p eEluIj5jbGFzcyA8c3Ryb25nPkZvcmtpbmdNaXhJbjwvc3Ryb25nPjwvYT48 L2ZvbnQ+PGRkPjxzbWFsbD48dHQ+TWl4LWluJm5ic3A7Y2xhc3MmbmJzcDt0 byZuYnNwO2hhbmRsZSZuYnNwO2VhY2gmbmJzcDtyZXF1ZXN0Jm5ic3A7aW4m bmJzcDthJm5ic3A7bmV3Jm5ic3A7cHJvY2Vzcy48L3R0Pjwvc21hbGw+PC9w PjwvZm9udD48L3RkPjwvdHI+DQo8dHI+PHRkIGJnY29sb3I9IiNmZmM4ZDgi IHdpZHRoPTQwPjxpbWcgc3JjPSIvc3BhY2VyLmdpZiIgd2lkdGg9NDAgaGVp Z2h0PTE+PC90ZD48dGQ+PGltZyBzcmM9Ii9zcGFjZXIuZ2lmIiB3aWR0aD0x MCBoZWlnaHQ9MT48L3RkPjx0ZD4NCjxmb250IHNpemU9Ii0zIiBjb2xvcj0i I2ZmZmZmZiI+XyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8g XyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBf IF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8g XyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBf IF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8g XyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gPGJyPjwvZm9udD4NCjxkdD48YSBu YW1lPSJGb3JraW5nTWl4SW4tY29sbGVjdF9jaGlsZHJlbiI+IDxzdHJvbmc+ Y29sbGVjdF9jaGlsZHJlbjwvc3Ryb25nPihzZWxmKTo8L2E+DQo8ZGQ+PHNt YWxsPjx0dD5JbnRlcm5hbCZuYnNwO3JvdXRpbmUmbmJzcDt0byZuYnNwO3dh aXQmbmJzcDtmb3ImbmJzcDtkaWVkJm5ic3A7Y2hpbGRyZW4uPC90dD48L3Nt YWxsPjwvcD48cD4NCjxkdD48YSBuYW1lPSJGb3JraW5nTWl4SW4tcHJvY2Vz c19yZXF1ZXN0Ij4gPHN0cm9uZz5wcm9jZXNzX3JlcXVlc3Q8L3N0cm9uZz4o c2VsZiwgcmVxdWVzdCwgY2xpZW50X2FkZHJlc3MpOjwvYT4NCjxkZD48c21h bGw+PHR0PkZvcmsmbmJzcDthJm5ic3A7bmV3Jm5ic3A7c3VicHJvY2VzcyZu YnNwO3RvJm5ic3A7cHJvY2VzcyZuYnNwO3RoZSZuYnNwO3JlcXVlc3QuPC90 dD48L3NtYWxsPjwvcD48cD4NCjwvdGQ+PC90cj48L3RhYmxlPg0KPHA+PHRh YmxlIHdpZHRoPSIxMDAlIiBjZWxsc3BhY2luZz0wIGNlbGxwYWRkaW5nPTAg Ym9yZGVyPTA+DQo8dHI+PHRkIGJnY29sb3I9IiNmZmM4ZDgiIGNvbHNwYW49 Mz48c21hbGw+PHNtYWxsPjxicj48L3NtYWxsPjwvc21hbGwNCj48Zm9udCBj b2xvcj0iIzAwMDAwMCIgZmFjZT0iaGVsdmV0aWNhIj4mbmJzcDs8YSBuYW1l PSJGb3JraW5nVENQU2VydmVyIj5jbGFzcyA8c3Ryb25nPkZvcmtpbmdUQ1BT ZXJ2ZXI8L3N0cm9uZz4oPGEgaHJlZj0iI0ZvcmtpbmdNaXhJbiI+Rm9ya2lu Z01peEluPC9hPiwgPGEgaHJlZj0iI1RDUFNlcnZlciI+VENQU2VydmVyPC9h Pik8L2E+PC9mb250PjxkZD48c21hbGw+PGVtPm5vIGRvYyBzdHJpbmcgYXZh aWxhYmxlPC9lbT48L3NtYWxsPjwvZm9udD48L3RkPjwvdHI+DQo8dHI+PHRk IGJnY29sb3I9IiNmZmM4ZDgiIHdpZHRoPTQwPjxpbWcgc3JjPSIvc3BhY2Vy LmdpZiIgd2lkdGg9NDAgaGVpZ2h0PTE+PC90ZD48dGQ+PGltZyBzcmM9Ii9z cGFjZXIuZ2lmIiB3aWR0aD0xMCBoZWlnaHQ9MT48L3RkPjx0ZD4NCjxmb250 IHNpemU9Ii0zIiBjb2xvcj0iI2ZmZmZmZiI+XyBfIF8gXyBfIF8gXyBfIF8g XyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBf IF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8g XyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBf IF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8g XyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gPGJy PjwvZm9udD4NCjwvdGQ+PC90cj48L3RhYmxlPg0KPHA+PHRhYmxlIHdpZHRo PSIxMDAlIiBjZWxsc3BhY2luZz0wIGNlbGxwYWRkaW5nPTAgYm9yZGVyPTA+ DQo8dHI+PHRkIGJnY29sb3I9IiNmZmM4ZDgiIGNvbHNwYW49Mz48c21hbGw+ PHNtYWxsPjxicj48L3NtYWxsPjwvc21hbGwNCj48Zm9udCBjb2xvcj0iIzAw MDAwMCIgZmFjZT0iaGVsdmV0aWNhIj4mbmJzcDs8YSBuYW1lPSJGb3JraW5n VURQU2VydmVyIj5jbGFzcyA8c3Ryb25nPkZvcmtpbmdVRFBTZXJ2ZXI8L3N0 cm9uZz4oPGEgaHJlZj0iI0ZvcmtpbmdNaXhJbiI+Rm9ya2luZ01peEluPC9h PiwgPGEgaHJlZj0iI1VEUFNlcnZlciI+VURQU2VydmVyPC9hPik8L2E+PC9m b250PjxkZD48c21hbGw+PGVtPm5vIGRvYyBzdHJpbmcgYXZhaWxhYmxlPC9l bT48L3NtYWxsPjwvZm9udD48L3RkPjwvdHI+DQo8dHI+PHRkIGJnY29sb3I9 IiNmZmM4ZDgiIHdpZHRoPTQwPjxpbWcgc3JjPSIvc3BhY2VyLmdpZiIgd2lk dGg9NDAgaGVpZ2h0PTE+PC90ZD48dGQ+PGltZyBzcmM9Ii9zcGFjZXIuZ2lm IiB3aWR0aD0xMCBoZWlnaHQ9MT48L3RkPjx0ZD4NCjxmb250IHNpemU9Ii0z IiBjb2xvcj0iI2ZmZmZmZiI+XyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBf IF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8g XyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBf IF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8g XyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBf IF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gPGJyPjwvZm9udD4N CjwvdGQ+PC90cj48L3RhYmxlPg0KPHA+PHRhYmxlIHdpZHRoPSIxMDAlIiBj ZWxsc3BhY2luZz0wIGNlbGxwYWRkaW5nPTAgYm9yZGVyPTA+DQo8dHI+PHRk IGJnY29sb3I9IiNmZmM4ZDgiIGNvbHNwYW49Mz48c21hbGw+PHNtYWxsPjxi cj48L3NtYWxsPjwvc21hbGwNCj48Zm9udCBjb2xvcj0iIzAwMDAwMCIgZmFj ZT0iaGVsdmV0aWNhIj4mbmJzcDs8YSBuYW1lPSJTdHJlYW1SZXF1ZXN0SGFu ZGxlciI+Y2xhc3MgPHN0cm9uZz5TdHJlYW1SZXF1ZXN0SGFuZGxlcjwvc3Ry b25nPig8YSBocmVmPSIjQmFzZVJlcXVlc3RIYW5kbGVyIj5CYXNlUmVxdWVz dEhhbmRsZXI8L2E+KTwvYT48L2ZvbnQ+PGRkPjxzbWFsbD48dHQ+RGVmaW5l Jm5ic3A7c2VsZi48c3Ryb25nPnJmaWxlPC9zdHJvbmc+Jm5ic3A7YW5kJm5i c3A7c2VsZi48c3Ryb25nPndmaWxlPC9zdHJvbmc+Jm5ic3A7Zm9yJm5ic3A7 c3RyZWFtJm5ic3A7c29ja2V0cy48L3R0Pjwvc21hbGw+PC9wPjwvZm9udD48 L3RkPjwvdHI+DQo8dHI+PHRkIGJnY29sb3I9IiNmZmM4ZDgiIHdpZHRoPTQw PjxpbWcgc3JjPSIvc3BhY2VyLmdpZiIgd2lkdGg9NDAgaGVpZ2h0PTE+PC90 ZD48dGQ+PGltZyBzcmM9Ii9zcGFjZXIuZ2lmIiB3aWR0aD0xMCBoZWlnaHQ9 MT48L3RkPjx0ZD4NCjxmb250IHNpemU9Ii0zIiBjb2xvcj0iI2ZmZmZmZiI+ XyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBf IF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8g XyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBf IF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8g XyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBf IF8gXyBfIF8gXyBfIF8gPGJyPjwvZm9udD4NCjxkdD48YSBuYW1lPSJTdHJl YW1SZXF1ZXN0SGFuZGxlci1maW5pc2giPiA8c3Ryb25nPmZpbmlzaDwvc3Ry b25nPihzZWxmKTo8L2E+DQo8ZGQ+PHNtYWxsPjxlbT5ubyBkb2Mgc3RyaW5n IGF2YWlsYWJsZTwvZW0+PC9zbWFsbD48cD4NCjxkdD48YSBuYW1lPSJTdHJl YW1SZXF1ZXN0SGFuZGxlci1zZXR1cCI+IDxzdHJvbmc+c2V0dXA8L3N0cm9u Zz4oc2VsZik6PC9hPg0KPGRkPjxzbWFsbD48ZW0+bm8gZG9jIHN0cmluZyBh dmFpbGFibGU8L2VtPjwvc21hbGw+PHA+DQo8L3RkPjwvdHI+PC90YWJsZT4N CjxwPjx0YWJsZSB3aWR0aD0iMTAwJSIgY2VsbHNwYWNpbmc9MCBjZWxscGFk ZGluZz0wIGJvcmRlcj0wPg0KPHRyPjx0ZCBiZ2NvbG9yPSIjZmZjOGQ4IiBj b2xzcGFuPTM+PHNtYWxsPjxzbWFsbD48YnI+PC9zbWFsbD48L3NtYWxsDQo+ PGZvbnQgY29sb3I9IiMwMDAwMDAiIGZhY2U9ImhlbHZldGljYSI+Jm5ic3A7 PGEgbmFtZT0iVENQU2VydmVyIj5jbGFzcyA8c3Ryb25nPlRDUFNlcnZlcjwv c3Ryb25nPjwvYT48L2ZvbnQ+PGRkPjxzbWFsbD48dHQ+QmFzZSZuYnNwO2Ns YXNzJm5ic3A7Zm9yJm5ic3A7dmFyaW91cyZuYnNwO3NvY2tldC1iYXNlZCZu YnNwO3NlcnZlciZuYnNwO2NsYXNzZXMuPGJyPg0KPGRkPjxicj4NCjxkZD5E ZWZhdWx0cyZuYnNwO3RvJm5ic3A7c3luY2hyb25vdXMmbmJzcDtJUCZuYnNw O3N0cmVhbSZuYnNwOyhpLmUuLCZuYnNwO1RDUCkuPGJyPg0KPGRkPjxicj4N CjxkZD5NZXRob2RzJm5ic3A7Zm9yJm5ic3A7dGhlJm5ic3A7Y2FsbGVyOjxi cj4NCjxkZD48YnI+DQo8ZGQ+LSZuYnNwOzxhIGhyZWY9IiNUQ1BTZXJ2ZXIt X19pbml0X18iPl9faW5pdF9fPC9hPihzZXJ2ZXJfYWRkcmVzcywmbmJzcDtS ZXF1ZXN0SGFuZGxlckNsYXNzKTxicj4NCjxkZD4tJm5ic3A7PGEgaHJlZj0i I1RDUFNlcnZlci1zZXJ2ZV9mb3JldmVyIj5zZXJ2ZV9mb3JldmVyPC9hPigp PGJyPg0KPGRkPi0mbmJzcDs8YSBocmVmPSIjVENQU2VydmVyLWhhbmRsZV9y ZXF1ZXN0Ij5oYW5kbGVfcmVxdWVzdDwvYT4oKSZuYnNwOyZuYnNwOyMmbmJz cDtpZiZuYnNwO3lvdSZuYnNwO2Rvbid0Jm5ic3A7dXNlJm5ic3A7PGEgaHJl Zj0iI1RDUFNlcnZlci1zZXJ2ZV9mb3JldmVyIj5zZXJ2ZV9mb3JldmVyPC9h PigpPGJyPg0KPGRkPi0mbmJzcDs8YSBocmVmPSIjVENQU2VydmVyLWZpbGVu byI+ZmlsZW5vPC9hPigpJm5ic3A7LT4mbmJzcDtpbnQmbmJzcDsmbmJzcDsm bmJzcDsjJm5ic3A7Zm9yJm5ic3A7c2VsZWN0KCk8YnI+DQo8ZGQ+PGJyPg0K PGRkPk1ldGhvZHMmbmJzcDt0aGF0Jm5ic3A7bWF5Jm5ic3A7YmUmbmJzcDtv dmVycmlkZGVuOjxicj4NCjxkZD48YnI+DQo8ZGQ+LSZuYnNwOzxhIGhyZWY9 IiNUQ1BTZXJ2ZXItc2VydmVyX2JpbmQiPnNlcnZlcl9iaW5kPC9hPigpPGJy Pg0KPGRkPi0mbmJzcDs8YSBocmVmPSIjVENQU2VydmVyLXNlcnZlcl9hY3Rp dmF0ZSI+c2VydmVyX2FjdGl2YXRlPC9hPigpPGJyPg0KPGRkPi0mbmJzcDs8 YSBocmVmPSIjVENQU2VydmVyLWdldF9yZXF1ZXN0Ij5nZXRfcmVxdWVzdDwv YT4oKSZuYnNwOy0+Jm5ic3A7cmVxdWVzdCwmbmJzcDtjbGllbnRfYWRkcmVz czxicj4NCjxkZD4tJm5ic3A7PGEgaHJlZj0iI1RDUFNlcnZlci12ZXJpZnlf cmVxdWVzdCI+dmVyaWZ5X3JlcXVlc3Q8L2E+KHJlcXVlc3QsJm5ic3A7Y2xp ZW50X2FkZHJlc3MpPGJyPg0KPGRkPi0mbmJzcDs8YSBocmVmPSIjVENQU2Vy dmVyLXByb2Nlc3NfcmVxdWVzdCI+cHJvY2Vzc19yZXF1ZXN0PC9hPihyZXF1 ZXN0LCZuYnNwO2NsaWVudF9hZGRyZXNzKTxicj4NCjxkZD4tJm5ic3A7PGEg aHJlZj0iI1RDUFNlcnZlci1oYW5kbGVfZXJyb3IiPmhhbmRsZV9lcnJvcjwv YT4oKTxicj4NCjxkZD48YnI+DQo8ZGQ+TWV0aG9kcyZuYnNwO2ZvciZuYnNw O2Rlcml2ZWQmbmJzcDtjbGFzc2VzOjxicj4NCjxkZD48YnI+DQo8ZGQ+LSZu YnNwOzxhIGhyZWY9IiNUQ1BTZXJ2ZXItZmluaXNoX3JlcXVlc3QiPmZpbmlz aF9yZXF1ZXN0PC9hPihyZXF1ZXN0LCZuYnNwO2NsaWVudF9hZGRyZXNzKTxi cj4NCjxkZD48YnI+DQo8ZGQ+Q2xhc3MmbmJzcDt2YXJpYWJsZXMmbmJzcDt0 aGF0Jm5ic3A7bWF5Jm5ic3A7YmUmbmJzcDtvdmVycmlkZGVuJm5ic3A7Ynkm bmJzcDtkZXJpdmVkJm5ic3A7Y2xhc3NlcyZuYnNwO29yPGJyPg0KPGRkPmlu c3RhbmNlczo8YnI+DQo8ZGQ+PGJyPg0KPGRkPi0mbmJzcDthZGRyZXNzX2Zh bWlseTxicj4NCjxkZD4tJm5ic3A7c29ja2V0X3R5cGU8YnI+DQo8ZGQ+LSZu YnNwO3JlcXVlc3RfcXVldWVfc2l6ZSZuYnNwOyhvbmx5Jm5ic3A7Zm9yJm5i c3A7c3RyZWFtJm5ic3A7c29ja2V0cyk8YnI+DQo8ZGQ+PGJyPg0KPGRkPklu c3RhbmNlJm5ic3A7dmFyaWFibGVzOjxicj4NCjxkZD48YnI+DQo8ZGQ+LSZu YnNwO3NlcnZlcl9hZGRyZXNzPGJyPg0KPGRkPi0mbmJzcDtSZXF1ZXN0SGFu ZGxlckNsYXNzPGJyPg0KPGRkPi0mbmJzcDtzb2NrZXQ8L3R0Pjwvc21hbGw+ PC9wPjwvZm9udD48L3RkPjwvdHI+DQo8dHI+PHRkIGJnY29sb3I9IiNmZmM4 ZDgiIHdpZHRoPTQwPjxpbWcgc3JjPSIvc3BhY2VyLmdpZiIgd2lkdGg9NDAg aGVpZ2h0PTE+PC90ZD48dGQ+PGltZyBzcmM9Ii9zcGFjZXIuZ2lmIiB3aWR0 aD0xMCBoZWlnaHQ9MT48L3RkPjx0ZD4NCjxmb250IHNpemU9Ii0zIiBjb2xv cj0iI2ZmZmZmZiI+XyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBf IF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8g XyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBf IF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8g XyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBf IF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gPGJyPjwvZm9udD4NCjxkdD48 YSBuYW1lPSJUQ1BTZXJ2ZXItX19pbml0X18iPiA8c3Ryb25nPl9faW5pdF9f PC9zdHJvbmc+KHNlbGYsIHNlcnZlcl9hZGRyZXNzLCBSZXF1ZXN0SGFuZGxl ckNsYXNzKTo8L2E+DQo8ZGQ+PHNtYWxsPjx0dD5Db25zdHJ1Y3Rvci4mbmJz cDsmbmJzcDtNYXkmbmJzcDtiZSZuYnNwO2V4dGVuZGVkLCZuYnNwO2RvJm5i c3A7bm90Jm5ic3A7b3ZlcnJpZGUuPC90dD48L3NtYWxsPjwvcD48cD4NCjxk dD48YSBuYW1lPSJUQ1BTZXJ2ZXItZmlsZW5vIj4gPHN0cm9uZz5maWxlbm88 L3N0cm9uZz4oc2VsZik6PC9hPg0KPGRkPjxzbWFsbD48dHQ+UmV0dXJuJm5i c3A7c29ja2V0Jm5ic3A7ZmlsZSZuYnNwO251bWJlci48YnI+DQo8ZGQ+PGJy Pg0KPGRkPkludGVyZmFjZSZuYnNwO3JlcXVpcmVkJm5ic3A7YnkmbmJzcDtz ZWxlY3QoKS48L3R0Pjwvc21hbGw+PC9wPjxwPg0KPGR0PjxhIG5hbWU9IlRD UFNlcnZlci1maW5pc2hfcmVxdWVzdCI+IDxzdHJvbmc+ZmluaXNoX3JlcXVl c3Q8L3N0cm9uZz4oc2VsZiwgcmVxdWVzdCwgY2xpZW50X2FkZHJlc3MpOjwv YT4NCjxkZD48c21hbGw+PHR0PkZpbmlzaCZuYnNwO29uZSZuYnNwO3JlcXVl c3QmbmJzcDtieSZuYnNwO2luc3RhbnRpYXRpbmcmbmJzcDtSZXF1ZXN0SGFu ZGxlckNsYXNzLjwvdHQ+PC9zbWFsbD48L3A+PHA+DQo8ZHQ+PGEgbmFtZT0i VENQU2VydmVyLWdldF9yZXF1ZXN0Ij4gPHN0cm9uZz5nZXRfcmVxdWVzdDwv c3Ryb25nPihzZWxmKTo8L2E+DQo8ZGQ+PHNtYWxsPjx0dD5HZXQmbmJzcDt0 aGUmbmJzcDtyZXF1ZXN0Jm5ic3A7YW5kJm5ic3A7Y2xpZW50Jm5ic3A7YWRk cmVzcyZuYnNwO2Zyb20mbmJzcDt0aGUmbmJzcDtzb2NrZXQuPGJyPg0KPGRk Pjxicj4NCjxkZD5NYXkmbmJzcDtiZSZuYnNwO292ZXJyaWRkZW4uPC90dD48 L3NtYWxsPjwvcD48cD4NCjxkdD48YSBuYW1lPSJUQ1BTZXJ2ZXItaGFuZGxl X2Vycm9yIj4gPHN0cm9uZz5oYW5kbGVfZXJyb3I8L3N0cm9uZz4oc2VsZiwg cmVxdWVzdCwgY2xpZW50X2FkZHJlc3MpOjwvYT4NCjxkZD48c21hbGw+PHR0 PkhhbmRsZSZuYnNwO2FuJm5ic3A7ZXJyb3ImbmJzcDtncmFjZWZ1bGx5LiZu YnNwOyZuYnNwO01heSZuYnNwO2JlJm5ic3A7b3ZlcnJpZGRlbi48YnI+DQo8 ZGQ+PGJyPg0KPGRkPlRoZSZuYnNwO2RlZmF1bHQmbmJzcDtpcyZuYnNwO3Rv Jm5ic3A7cHJpbnQmbmJzcDthJm5ic3A7dHJhY2ViYWNrJm5ic3A7YW5kJm5i c3A7Y29udGludWUuPC90dD48L3NtYWxsPjwvcD48cD4NCjxkdD48YSBuYW1l PSJUQ1BTZXJ2ZXItaGFuZGxlX3JlcXVlc3QiPiA8c3Ryb25nPmhhbmRsZV9y ZXF1ZXN0PC9zdHJvbmc+KHNlbGYpOjwvYT4NCjxkZD48c21hbGw+PHR0Pkhh bmRsZSZuYnNwO29uZSZuYnNwO3JlcXVlc3QsJm5ic3A7cG9zc2libHkmbmJz cDtibG9ja2luZy48L3R0Pjwvc21hbGw+PC9wPjxwPg0KPGR0PjxhIG5hbWU9 IlRDUFNlcnZlci1wcm9jZXNzX3JlcXVlc3QiPiA8c3Ryb25nPnByb2Nlc3Nf cmVxdWVzdDwvc3Ryb25nPihzZWxmLCByZXF1ZXN0LCBjbGllbnRfYWRkcmVz cyk6PC9hPg0KPGRkPjxzbWFsbD48dHQ+Q2FsbCZuYnNwO2ZpbmlzaF9yZXF1 ZXN0Ljxicj4NCjxkZD48YnI+DQo8ZGQ+T3ZlcnJpZGRlbiZuYnNwO2J5Jm5i c3A7PGEgaHJlZj0iI0ZvcmtpbmdNaXhJbiI+Rm9ya2luZ01peEluPC9hPiZu YnNwO2FuZCZuYnNwOzxhIGhyZWY9IiNUaHJlYWRpbmdNaXhJbiI+VGhyZWFk aW5nTWl4SW48L2E+LjwvdHQ+PC9zbWFsbD48L3A+PHA+DQo8ZHQ+PGEgbmFt ZT0iVENQU2VydmVyLXNlcnZlX2ZvcmV2ZXIiPiA8c3Ryb25nPnNlcnZlX2Zv cmV2ZXI8L3N0cm9uZz4oc2VsZik6PC9hPg0KPGRkPjxzbWFsbD48dHQ+SGFu ZGxlJm5ic3A7b25lJm5ic3A7cmVxdWVzdCZuYnNwO2F0Jm5ic3A7YSZuYnNw O3RpbWUmbmJzcDt1bnRpbCZuYnNwO2Rvb21zZGF5LjwvdHQ+PC9zbWFsbD48 L3A+PHA+DQo8ZHQ+PGEgbmFtZT0iVENQU2VydmVyLXNlcnZlcl9hY3RpdmF0 ZSI+IDxzdHJvbmc+c2VydmVyX2FjdGl2YXRlPC9zdHJvbmc+KHNlbGYpOjwv YT4NCjxkZD48c21hbGw+PHR0PkNhbGxlZCZuYnNwO2J5Jm5ic3A7Y29uc3Ry dWN0b3ImbmJzcDt0byZuYnNwO2FjdGl2YXRlJm5ic3A7dGhlJm5ic3A7c2Vy dmVyLjxicj4NCjxkZD48YnI+DQo8ZGQ+TWF5Jm5ic3A7YmUmbmJzcDtvdmVy cmlkZGVuLjwvdHQ+PC9zbWFsbD48L3A+PHA+DQo8ZHQ+PGEgbmFtZT0iVENQ U2VydmVyLXNlcnZlcl9iaW5kIj4gPHN0cm9uZz5zZXJ2ZXJfYmluZDwvc3Ry b25nPihzZWxmKTo8L2E+DQo8ZGQ+PHNtYWxsPjx0dD5DYWxsZWQmbmJzcDti eSZuYnNwO2NvbnN0cnVjdG9yJm5ic3A7dG8mbmJzcDtiaW5kJm5ic3A7dGhl Jm5ic3A7c29ja2V0Ljxicj4NCjxkZD48YnI+DQo8ZGQ+TWF5Jm5ic3A7YmUm bmJzcDtvdmVycmlkZGVuLjwvdHQ+PC9zbWFsbD48L3A+PHA+DQo8ZHQ+PGEg bmFtZT0iVENQU2VydmVyLXZlcmlmeV9yZXF1ZXN0Ij4gPHN0cm9uZz52ZXJp ZnlfcmVxdWVzdDwvc3Ryb25nPihzZWxmLCByZXF1ZXN0LCBjbGllbnRfYWRk cmVzcyk6PC9hPg0KPGRkPjxzbWFsbD48dHQ+VmVyaWZ5Jm5ic3A7dGhlJm5i c3A7cmVxdWVzdC4mbmJzcDsmbmJzcDtNYXkmbmJzcDtiZSZuYnNwO292ZXJy aWRkZW4uPGJyPg0KPGRkPjxicj4NCjxkZD5SZXR1cm4mbmJzcDt0cnVlJm5i c3A7aWYmbmJzcDt3ZSZuYnNwO3Nob3VsZCZuYnNwO3Byb2NlZWQmbmJzcDt3 aXRoJm5ic3A7dGhpcyZuYnNwO3JlcXVlc3QuPC90dD48L3NtYWxsPjwvcD48 cD4NCjwvdGQ+PC90cj48L3RhYmxlPg0KPHA+PHRhYmxlIHdpZHRoPSIxMDAl IiBjZWxsc3BhY2luZz0wIGNlbGxwYWRkaW5nPTAgYm9yZGVyPTA+DQo8dHI+ PHRkIGJnY29sb3I9IiNmZmM4ZDgiIGNvbHNwYW49Mz48c21hbGw+PHNtYWxs Pjxicj48L3NtYWxsPjwvc21hbGwNCj48Zm9udCBjb2xvcj0iIzAwMDAwMCIg ZmFjZT0iaGVsdmV0aWNhIj4mbmJzcDs8YSBuYW1lPSJUaHJlYWRpbmdNaXhJ biI+Y2xhc3MgPHN0cm9uZz5UaHJlYWRpbmdNaXhJbjwvc3Ryb25nPjwvYT48 L2ZvbnQ+PGRkPjxzbWFsbD48dHQ+TWl4LWluJm5ic3A7Y2xhc3MmbmJzcDt0 byZuYnNwO2hhbmRsZSZuYnNwO2VhY2gmbmJzcDtyZXF1ZXN0Jm5ic3A7aW4m bmJzcDthJm5ic3A7bmV3Jm5ic3A7dGhyZWFkLjwvdHQ+PC9zbWFsbD48L3A+ PC9mb250PjwvdGQ+PC90cj4NCjx0cj48dGQgYmdjb2xvcj0iI2ZmYzhkOCIg d2lkdGg9NDA+PGltZyBzcmM9Ii9zcGFjZXIuZ2lmIiB3aWR0aD00MCBoZWln aHQ9MT48L3RkPjx0ZD48aW1nIHNyYz0iL3NwYWNlci5naWYiIHdpZHRoPTEw IGhlaWdodD0xPjwvdGQ+PHRkPg0KPGZvbnQgc2l6ZT0iLTMiIGNvbG9yPSIj ZmZmZmZmIj5fIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBf IF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8g XyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBf IF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8g XyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBf IF8gXyBfIF8gXyBfIF8gXyBfIF8gXyA8YnI+PC9mb250Pg0KPGR0PjxhIG5h bWU9IlRocmVhZGluZ01peEluLXByb2Nlc3NfcmVxdWVzdCI+IDxzdHJvbmc+ cHJvY2Vzc19yZXF1ZXN0PC9zdHJvbmc+KHNlbGYsIHJlcXVlc3QsIGNsaWVu dF9hZGRyZXNzKTo8L2E+DQo8ZGQ+PHNtYWxsPjx0dD5TdGFydCZuYnNwO2Em bmJzcDtuZXcmbmJzcDt0aHJlYWQmbmJzcDt0byZuYnNwO3Byb2Nlc3MmbmJz cDt0aGUmbmJzcDtyZXF1ZXN0LjwvdHQ+PC9zbWFsbD48L3A+PHA+DQo8L3Rk PjwvdHI+PC90YWJsZT4NCjxwPjx0YWJsZSB3aWR0aD0iMTAwJSIgY2VsbHNw YWNpbmc9MCBjZWxscGFkZGluZz0wIGJvcmRlcj0wPg0KPHRyPjx0ZCBiZ2Nv bG9yPSIjZmZjOGQ4IiBjb2xzcGFuPTM+PHNtYWxsPjxzbWFsbD48YnI+PC9z bWFsbD48L3NtYWxsDQo+PGZvbnQgY29sb3I9IiMwMDAwMDAiIGZhY2U9Imhl bHZldGljYSI+Jm5ic3A7PGEgbmFtZT0iVGhyZWFkaW5nVENQU2VydmVyIj5j bGFzcyA8c3Ryb25nPlRocmVhZGluZ1RDUFNlcnZlcjwvc3Ryb25nPig8YSBo cmVmPSIjVGhyZWFkaW5nTWl4SW4iPlRocmVhZGluZ01peEluPC9hPiwgPGEg aHJlZj0iI1RDUFNlcnZlciI+VENQU2VydmVyPC9hPik8L2E+PC9mb250Pjxk ZD48c21hbGw+PGVtPm5vIGRvYyBzdHJpbmcgYXZhaWxhYmxlPC9lbT48L3Nt YWxsPjwvZm9udD48L3RkPjwvdHI+DQo8dHI+PHRkIGJnY29sb3I9IiNmZmM4 ZDgiIHdpZHRoPTQwPjxpbWcgc3JjPSIvc3BhY2VyLmdpZiIgd2lkdGg9NDAg aGVpZ2h0PTE+PC90ZD48dGQ+PGltZyBzcmM9Ii9zcGFjZXIuZ2lmIiB3aWR0 aD0xMCBoZWlnaHQ9MT48L3RkPjx0ZD4NCjxmb250IHNpemU9Ii0zIiBjb2xv cj0iI2ZmZmZmZiI+XyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBf IF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8g XyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBf IF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8g XyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBf IF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gPGJyPjwvZm9udD4NCjwvdGQ+ PC90cj48L3RhYmxlPg0KPHA+PHRhYmxlIHdpZHRoPSIxMDAlIiBjZWxsc3Bh Y2luZz0wIGNlbGxwYWRkaW5nPTAgYm9yZGVyPTA+DQo8dHI+PHRkIGJnY29s b3I9IiNmZmM4ZDgiIGNvbHNwYW49Mz48c21hbGw+PHNtYWxsPjxicj48L3Nt YWxsPjwvc21hbGwNCj48Zm9udCBjb2xvcj0iIzAwMDAwMCIgZmFjZT0iaGVs dmV0aWNhIj4mbmJzcDs8YSBuYW1lPSJUaHJlYWRpbmdVRFBTZXJ2ZXIiPmNs YXNzIDxzdHJvbmc+VGhyZWFkaW5nVURQU2VydmVyPC9zdHJvbmc+KDxhIGhy ZWY9IiNUaHJlYWRpbmdNaXhJbiI+VGhyZWFkaW5nTWl4SW48L2E+LCA8YSBo cmVmPSIjVURQU2VydmVyIj5VRFBTZXJ2ZXI8L2E+KTwvYT48L2ZvbnQ+PGRk PjxzbWFsbD48ZW0+bm8gZG9jIHN0cmluZyBhdmFpbGFibGU8L2VtPjwvc21h bGw+PC9mb250PjwvdGQ+PC90cj4NCjx0cj48dGQgYmdjb2xvcj0iI2ZmYzhk OCIgd2lkdGg9NDA+PGltZyBzcmM9Ii9zcGFjZXIuZ2lmIiB3aWR0aD00MCBo ZWlnaHQ9MT48L3RkPjx0ZD48aW1nIHNyYz0iL3NwYWNlci5naWYiIHdpZHRo PTEwIGhlaWdodD0xPjwvdGQ+PHRkPg0KPGZvbnQgc2l6ZT0iLTMiIGNvbG9y PSIjZmZmZmZmIj5fIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8g XyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBf IF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8g XyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBf IF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8g XyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyA8YnI+PC9mb250Pg0KPC90ZD48 L3RyPjwvdGFibGU+DQo8cD48dGFibGUgd2lkdGg9IjEwMCUiIGNlbGxzcGFj aW5nPTAgY2VsbHBhZGRpbmc9MCBib3JkZXI9MD4NCjx0cj48dGQgYmdjb2xv cj0iI2ZmYzhkOCIgY29sc3Bhbj0zPjxzbWFsbD48c21hbGw+PGJyPjwvc21h bGw+PC9zbWFsbA0KPjxmb250IGNvbG9yPSIjMDAwMDAwIiBmYWNlPSJoZWx2 ZXRpY2EiPiZuYnNwOzxhIG5hbWU9IlRocmVhZGluZ1VuaXhEYXRhZ3JhbVNl cnZlciI+Y2xhc3MgPHN0cm9uZz5UaHJlYWRpbmdVbml4RGF0YWdyYW1TZXJ2 ZXI8L3N0cm9uZz4oPGEgaHJlZj0iI1RocmVhZGluZ01peEluIj5UaHJlYWRp bmdNaXhJbjwvYT4sIDxhIGhyZWY9IiNVbml4RGF0YWdyYW1TZXJ2ZXIiPlVu aXhEYXRhZ3JhbVNlcnZlcjwvYT4pPC9hPjwvZm9udD48ZGQ+PHNtYWxsPjxl bT5ubyBkb2Mgc3RyaW5nIGF2YWlsYWJsZTwvZW0+PC9zbWFsbD48L2ZvbnQ+ PC90ZD48L3RyPg0KPHRyPjx0ZCBiZ2NvbG9yPSIjZmZjOGQ4IiB3aWR0aD00 MD48aW1nIHNyYz0iL3NwYWNlci5naWYiIHdpZHRoPTQwIGhlaWdodD0xPjwv dGQ+PHRkPjxpbWcgc3JjPSIvc3BhY2VyLmdpZiIgd2lkdGg9MTAgaGVpZ2h0 PTE+PC90ZD48dGQ+DQo8Zm9udCBzaXplPSItMyIgY29sb3I9IiNmZmZmZmYi Pl8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8g XyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBf IF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8g XyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBf IF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8g XyBfIF8gXyBfIF8gXyBfIDxicj48L2ZvbnQ+DQo8L3RkPjwvdHI+PC90YWJs ZT4NCjxwPjx0YWJsZSB3aWR0aD0iMTAwJSIgY2VsbHNwYWNpbmc9MCBjZWxs cGFkZGluZz0wIGJvcmRlcj0wPg0KPHRyPjx0ZCBiZ2NvbG9yPSIjZmZjOGQ4 IiBjb2xzcGFuPTM+PHNtYWxsPjxzbWFsbD48YnI+PC9zbWFsbD48L3NtYWxs DQo+PGZvbnQgY29sb3I9IiMwMDAwMDAiIGZhY2U9ImhlbHZldGljYSI+Jm5i c3A7PGEgbmFtZT0iVGhyZWFkaW5nVW5peFN0cmVhbVNlcnZlciI+Y2xhc3Mg PHN0cm9uZz5UaHJlYWRpbmdVbml4U3RyZWFtU2VydmVyPC9zdHJvbmc+KDxh IGhyZWY9IiNUaHJlYWRpbmdNaXhJbiI+VGhyZWFkaW5nTWl4SW48L2E+LCA8 YSBocmVmPSIjVW5peFN0cmVhbVNlcnZlciI+VW5peFN0cmVhbVNlcnZlcjwv YT4pPC9hPjwvZm9udD48ZGQ+PHNtYWxsPjxlbT5ubyBkb2Mgc3RyaW5nIGF2 YWlsYWJsZTwvZW0+PC9zbWFsbD48L2ZvbnQ+PC90ZD48L3RyPg0KPHRyPjx0 ZCBiZ2NvbG9yPSIjZmZjOGQ4IiB3aWR0aD00MD48aW1nIHNyYz0iL3NwYWNl ci5naWYiIHdpZHRoPTQwIGhlaWdodD0xPjwvdGQ+PHRkPjxpbWcgc3JjPSIv c3BhY2VyLmdpZiIgd2lkdGg9MTAgaGVpZ2h0PTE+PC90ZD48dGQ+DQo8Zm9u dCBzaXplPSItMyIgY29sb3I9IiNmZmZmZmYiPl8gXyBfIF8gXyBfIF8gXyBf IF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8g XyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBf IF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8g XyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBf IF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIDxi cj48L2ZvbnQ+DQo8L3RkPjwvdHI+PC90YWJsZT4NCjxwPjx0YWJsZSB3aWR0 aD0iMTAwJSIgY2VsbHNwYWNpbmc9MCBjZWxscGFkZGluZz0wIGJvcmRlcj0w Pg0KPHRyPjx0ZCBiZ2NvbG9yPSIjZmZjOGQ4IiBjb2xzcGFuPTM+PHNtYWxs PjxzbWFsbD48YnI+PC9zbWFsbD48L3NtYWxsDQo+PGZvbnQgY29sb3I9IiMw MDAwMDAiIGZhY2U9ImhlbHZldGljYSI+Jm5ic3A7PGEgbmFtZT0iVURQU2Vy dmVyIj5jbGFzcyA8c3Ryb25nPlVEUFNlcnZlcjwvc3Ryb25nPig8YSBocmVm PSIjVENQU2VydmVyIj5UQ1BTZXJ2ZXI8L2E+KTwvYT48L2ZvbnQ+PGRkPjxz bWFsbD48dHQ+VURQJm5ic3A7c2VydmVyJm5ic3A7Y2xhc3MuPC90dD48L3Nt YWxsPjwvcD48L2ZvbnQ+PC90ZD48L3RyPg0KPHRyPjx0ZCBiZ2NvbG9yPSIj ZmZjOGQ4IiB3aWR0aD00MD48aW1nIHNyYz0iL3NwYWNlci5naWYiIHdpZHRo PTQwIGhlaWdodD0xPjwvdGQ+PHRkPjxpbWcgc3JjPSIvc3BhY2VyLmdpZiIg d2lkdGg9MTAgaGVpZ2h0PTE+PC90ZD48dGQ+DQo8Zm9udCBzaXplPSItMyIg Y29sb3I9IiNmZmZmZmYiPl8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBf IF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8g XyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBf IF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8g XyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBf IF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIDxicj48L2ZvbnQ+DQo8 ZHQ+PGEgbmFtZT0iVURQU2VydmVyLWdldF9yZXF1ZXN0Ij4gPHN0cm9uZz5n ZXRfcmVxdWVzdDwvc3Ryb25nPihzZWxmKTo8L2E+DQo8ZGQ+PHNtYWxsPjxl bT5ubyBkb2Mgc3RyaW5nIGF2YWlsYWJsZTwvZW0+PC9zbWFsbD48cD4NCjxk dD48YSBuYW1lPSJVRFBTZXJ2ZXItc2VydmVyX2FjdGl2YXRlIj4gPHN0cm9u Zz5zZXJ2ZXJfYWN0aXZhdGU8L3N0cm9uZz4oc2VsZik6PC9hPg0KPGRkPjxz bWFsbD48ZW0+bm8gZG9jIHN0cmluZyBhdmFpbGFibGU8L2VtPjwvc21hbGw+ PHA+DQo8L3RkPjwvdHI+PC90YWJsZT4NCjxwPjx0YWJsZSB3aWR0aD0iMTAw JSIgY2VsbHNwYWNpbmc9MCBjZWxscGFkZGluZz0wIGJvcmRlcj0wPg0KPHRy Pjx0ZCBiZ2NvbG9yPSIjZmZjOGQ4IiBjb2xzcGFuPTM+PHNtYWxsPjxzbWFs bD48YnI+PC9zbWFsbD48L3NtYWxsDQo+PGZvbnQgY29sb3I9IiMwMDAwMDAi IGZhY2U9ImhlbHZldGljYSI+Jm5ic3A7PGEgbmFtZT0iVW5peERhdGFncmFt U2VydmVyIj5jbGFzcyA8c3Ryb25nPlVuaXhEYXRhZ3JhbVNlcnZlcjwvc3Ry b25nPig8YSBocmVmPSIjVURQU2VydmVyIj5VRFBTZXJ2ZXI8L2E+KTwvYT48 L2ZvbnQ+PGRkPjxzbWFsbD48ZW0+bm8gZG9jIHN0cmluZyBhdmFpbGFibGU8 L2VtPjwvc21hbGw+PC9mb250PjwvdGQ+PC90cj4NCjx0cj48dGQgYmdjb2xv cj0iI2ZmYzhkOCIgd2lkdGg9NDA+PGltZyBzcmM9Ii9zcGFjZXIuZ2lmIiB3 aWR0aD00MCBoZWlnaHQ9MT48L3RkPjx0ZD48aW1nIHNyYz0iL3NwYWNlci5n aWYiIHdpZHRoPTEwIGhlaWdodD0xPjwvdGQ+PHRkPg0KPGZvbnQgc2l6ZT0i LTMiIGNvbG9yPSIjZmZmZmZmIj5fIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBf IF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8g XyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBf IF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8g XyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBf IF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyA8YnI+PC9mb250 Pg0KPC90ZD48L3RyPjwvdGFibGU+DQo8cD48dGFibGUgd2lkdGg9IjEwMCUi IGNlbGxzcGFjaW5nPTAgY2VsbHBhZGRpbmc9MCBib3JkZXI9MD4NCjx0cj48 dGQgYmdjb2xvcj0iI2ZmYzhkOCIgY29sc3Bhbj0zPjxzbWFsbD48c21hbGw+ PGJyPjwvc21hbGw+PC9zbWFsbA0KPjxmb250IGNvbG9yPSIjMDAwMDAwIiBm YWNlPSJoZWx2ZXRpY2EiPiZuYnNwOzxhIG5hbWU9IlVuaXhTdHJlYW1TZXJ2 ZXIiPmNsYXNzIDxzdHJvbmc+VW5peFN0cmVhbVNlcnZlcjwvc3Ryb25nPig8 YSBocmVmPSIjVENQU2VydmVyIj5UQ1BTZXJ2ZXI8L2E+KTwvYT48L2ZvbnQ+ PGRkPjxzbWFsbD48ZW0+bm8gZG9jIHN0cmluZyBhdmFpbGFibGU8L2VtPjwv c21hbGw+PC9mb250PjwvdGQ+PC90cj4NCjx0cj48dGQgYmdjb2xvcj0iI2Zm YzhkOCIgd2lkdGg9NDA+PGltZyBzcmM9Ii9zcGFjZXIuZ2lmIiB3aWR0aD00 MCBoZWlnaHQ9MT48L3RkPjx0ZD48aW1nIHNyYz0iL3NwYWNlci5naWYiIHdp ZHRoPTEwIGhlaWdodD0xPjwvdGQ+PHRkPg0KPGZvbnQgc2l6ZT0iLTMiIGNv bG9yPSIjZmZmZmZmIj5fIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBf IF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8g XyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBf IF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8g XyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBf IF8gXyBfIF8gXyBfIF8gXyBfIF8gXyBfIF8gXyA8YnI+PC9mb250Pg0KPC90 ZD48L3RyPjwvdGFibGU+DQo8L3RkPjwvdHI+PC90YWJsZT4NCjxwPjxhIGhy ZWY9ImFkZHJlZj9tb2R1bGU9U29ja2V0U2VydmVyIj5IYXZlIHlvdSBzZWVu IGFueSBvdGhlcg0KZG9jdW1lbnRhdGlvbiBhYm91dCB0aGlzIG1vZHVsZT88 L2E+DQo8dGFibGUgd2lkdGg9IjEwMCUiPjx0cj48dGQgYWxpZ249cmlnaHQ+ DQo8Zm9udCBmYWNlPSJoZWx2ZXRpY2EiPjxzbWFsbD48c21hbGw+PHN0cm9u Zz5tYW5weTwvc3Ryb25nPiBieQ0KPHN0cm9uZz48YSBocmVmPSJtYWlsdG86 dG9tbXkiPlRvbW15IEJ1cm5ldHRlPC9hPjwvc3Ryb25nPiwNCldlYiBpbnRl cmZhY2UgYnkgPGEgaHJlZj0ibWFpbHRvOnBpbmdzdGVyIj5QaW5nPC9hPg0K KDI2IEp1bmUgOTgpPC9zbWFsbD48L3NtYWxsPjwvZm9udD48L3RyPjwvdGQ+ PC90YWJsZT4NCjwvYm9keT48L2h0bWw+DQo= --8323328-2057684099-949874924=:2302-- From Moshe Zadka Mon Feb 7 15:48:10 2000 From: Moshe Zadka (Moshe Zadka) Date: Mon, 7 Feb 2000 17:48:10 +0200 (IST) Subject: [Doc-SIG] Re: Ease of use is #1 In-Reply-To: Message-ID: On Mon, 7 Feb 2000, Edward Welbourne wrote: Hi Edward, nice to know you're safely back in the UK > > Assumption 1: > > This addresses `what are doc strings for ?' and I disagree with you > (at least partially). While the rest of your post is interesting, it is irrelevant. If we can't agree on the goals, we certainly won't be able to agree on the syntax. (BTW: you're not disagreeing with me, but rather my assumptions. I'm not sure *I* agree with those: I just tried to formulate a consensus which I can live with ;-) ) Since no discussion will settle the purpose issue, which I will formulate as "Are doc-strings the whole documentation, or a quick reminder while the documentation is elsewhere?", unless some of the people here will manage to brainwash the rest , the whole issue is moot. I think the only way to resolve the argument is by decision from above. The authority to consult remains TBD. -- Moshe Zadka . INTERNET: Learn what you know. Share what you don't. From pf@artcom-gmbh.de Mon Feb 7 16:10:31 2000 From: pf@artcom-gmbh.de (Peter Funk) Date: Mon, 7 Feb 2000 17:10:31 +0100 (MET) Subject: Taking a poll? (was Re: [Doc-SIG] Re: Ease of use is #1) In-Reply-To: from Moshe Zadka at "Feb 7, 2000 5:48:10 pm" Message-ID: Hi! [Moshe Zadka]: > > > Assumption 1: > > > > This addresses `what are doc strings for ?' and I disagree with you > > (at least partially). [...] > Since no discussion will settle the purpose issue, which I will formulate > as "Are doc-strings the whole documentation, or a quick reminder while > the documentation is elsewhere?", unless some of the people here will > manage to brainwash the rest , the whole issue is moot. I think the > only way to resolve the argument is by decision from above. > > The authority to consult remains TBD. What about taking a poll at a larger audience? Regards, Peter -- Peter Funk, Oldenburger Str.86, D-27777 Ganderkesee, Germany, Fax:+49 4222950260 office: +49 421 20419-0 (ArtCom GmbH, Grazer Str.8, D-28359 Bremen) From fdrake@acm.org Mon Feb 7 17:57:05 2000 From: fdrake@acm.org (Fred L. Drake, Jr.) Date: Mon, 7 Feb 2000 12:57:05 -0500 (EST) Subject: M.Z. assumptions (was Re: [Doc-SIG] Re: Ease of use is #1) In-Reply-To: References: Message-ID: <14495.1905.906349.867382@weyr.cnri.reston.va.us> Moshe Zadka wrote: > Assumption 1: > doc-strings should be flexible enough to document most Python > modules without any OOL documentation (that is, as I understand, > our majority vote). The "most" comes because it shouldn't Peter Funk writes: > I see: IMHO this first assumption is wrong. Good reference > documentation often requires complex material like tables, figures, > formulas and more text, which will clutter up the source and distract Ok, guys, I think this points out where the communications failure is (what other kind is there?). Docstrings, combined with language information obtained from the parse tree or reflection, should be sufficient to generate "usable" documentation "most" of the time. Note that "usable" and "most" are fairly vague; don't assume they're tightly related to "optimal" or "all". "Usable" means that names of classes, functions, and parameters are available and can be presented reasonably, and the docstrings can be used to augment the information content with descriptions and examples. As for "most", I'd be quite happy to hit 75% to 80% of modules at the "usable" level. > It should be possible to autogenerate *some* kind of reference > documentation from doc-strings during early stages of the lifetime > of software. Later, when the software becomes more mature and > complex, it should be possible to use this autogenerated material > as a starting point for more elaborate documentation. So not all > features, which would be available at the higher XML level and > which you see used in the current python library reference need to > have a counterpart in an upcoming doc-string grammar. Agreed. I think David Ascher and the structured-text proponents are likely to come up with a very reasonable proposal. For modules which require more structure or author-control of semantic labelling than we can extract from the module source (docstrings + (parse tree or reflection)), it's perfectly reasonable to say "You need to use the heavy stuff." (Moshe: Please don't think I meant that *you* really had to do *everything* with the documentation! I was just joking about that at the IPC8 Doc-SIG session! We welcome your participation, but it's up to me to act as channel for the BDFL here; keeps the hate mail in my box rather than yours. ;) -Fred -- Fred L. Drake, Jr. Corporation for National Research Initiatives From klm@digicool.com Mon Feb 7 19:07:21 2000 From: klm@digicool.com (Ken Manheimer) Date: Mon, 7 Feb 2000 14:07:21 -0500 Subject: [Doc-SIG] RE: Doc-SIG digest, Vol 1 #145 - 4 msgs Message-ID: <613145F79272D211914B0020AFF640191D1D73@gandalf.digicool.com> Ping wrote: > Remember the old adage that says that every math equation in a book > will cut its readership in half? Well, imagine something similar -- > every additional syntactic construct or tag will cut the *writership* > in half (or some fraction). Even though more tags may mean more I think this is a brilliant way to frame it. > expressive power, it also means a more difficult choice to make every > time one uses a tag -- beyond a certain point it becomes debatable > which tag is the correct one to use, and then all is lost. Also, the > more complex the system becomes, the less predictable the failure modes > will be -- till we get to the point you have to debug docstrings (eek!). I believe that jim did an extremely good job balancing these concerns with structured text - i had the impression that david ascher came to see this, too, when he was looking at alternatives and came back to structured text. Moshe makes the point that it's hard to reason about structured text. I happen to be sympathetic with this point of view - i would be reluctant to implement a system myself, because i'd be afraid of tangling myself in ambiguities that i couldn't resolve for people writing text or extending the text processing code. However that doesn't mean that what jim implemented suffers from this, or that it can't be rectified where it does! I guess the upshot is that i think it would be worthwhile investigating whether moshe's concerns - which i take to be having rigorous, predictable rules - could be satisfied with structured text, rather than taking a different path that suffers from the things to which eddy, ping, and others (me, include) object. (I don't know whether it was deliberate or not, but i note that both eddy and ping's messages had the right (or trivially-near right) bullets/emphasis/etc formatting for correct interpretation by StructuredText.) > (The attached example is generated from SocketServer.py as distributed > with Python 1.5 -- nothing has been edited.) I'm unable to read the example because i get this list in digest form. (My fault, sorta, for not fixing this in mailman's MIME handling in digests when i was working on it...) Ken klm@digicool.com From fdrake@acm.org Mon Feb 7 18:59:16 2000 From: fdrake@acm.org (Fred L. Drake, Jr.) Date: Mon, 7 Feb 2000 13:59:16 -0500 (EST) Subject: [Doc-SIG] RE: Doc-SIG digest, Vol 1 #145 - 4 msgs In-Reply-To: <613145F79272D211914B0020AFF640191D1D73@gandalf.digicool.com> References: <613145F79272D211914B0020AFF640191D1D73@gandalf.digicool.com> Message-ID: <14495.5636.176338.263680@weyr.cnri.reston.va.us> Ken Manheimer writes: > I'm unable to read the example because i get this list in digest form. > (My fault, sorta, for not fixing this in mailman's MIME handling in > digests when i was working on it...) Ken, This means you're fixing this in Mailman as we speak? ;-) -Fred -- Fred L. Drake, Jr. Corporation for National Research Initiatives From Manuel Gutierrez Algaba Mon Feb 7 20:53:34 2000 From: Manuel Gutierrez Algaba (Manuel Gutierrez Algaba) Date: Mon, 7 Feb 2000 20:53:34 +0000 (GMT) Subject: [Doc-SIG] More documentation In-Reply-To: <20000206213258.3CDA6D3761@oratrix.oratrix.nl> Message-ID: On Sun, 6 Feb 2000, Jack Jansen wrote: > > At least, in my mind the examples are all far too verbose: lots of > formatting info, typing info on the variables/functions/exceptions > used, etc. Common sense. > > I know that for me this will not work. Not only do I abhor weave-like > systems (I think writing real documentation should be done with a > completely different mindset, Common sense, but sometimes weave-like may work, it depends on the programm. > and not sort-of in-between while writing > the code) but I'm also sure to forget the syntax, so after staring at > the opening """ for a few seconds I'll think "ah, forget it. Who needs > docs anyway". Common sense > The scheme we seemed to be converging to before the conference was > much more to my liking: basically free-format with a few readable > flag-words like "arguments:" or so. Common sense Regards/Saludos Manolo www.ctv.es/USERS/irmina /TeEncontreX.html /texpython.htm /pyttex.htm I just got out of the hospital after a speed reading accident. I hit a bookmark. -- Steven Wright From Manuel Gutierrez Algaba Mon Feb 7 20:52:41 2000 From: Manuel Gutierrez Algaba (Manuel Gutierrez Algaba) Date: Mon, 7 Feb 2000 20:52:41 +0000 (GMT) Subject: M.Z. assumptions (was Re: [Doc-SIG] Re: Ease of use is #1) In-Reply-To: Message-ID: On Mon, 7 Feb 2000, Peter Funk wrote: > Hi! > > Moshe Zadka wrote: > > Assumption 1: > > doc-strings should be flexible enough to document most Python > > modules without any OOL documentation (that is, as I understand, > > our majority vote). The "most" comes because it shouldn't > > necessarily be flexible enough to write the reference manual for > > the debugger. > > I see: IMHO this first assumption is wrong. Good reference > documentation often requires complex material like tables, figures, > formulas and more text, which will clutter up the source and distract > during code maintainance. Common sense! > What you describe is the literate programming approach, which IMHO > has always failed in the past. (Look at TeXs tangle and weave). Literate programming is not dead. We should think too if we can develop better tools for handling python code than editors. Class browsers and such. Rich docstrings are interesting but not for functions or classes, perhaps at the beginning of modules. > > It should be possible to autogenerate *some* kind of reference > documentation from doc-strings during early stages of the lifetime > of software. Later, when the software becomes more mature and > complex, it should be possible to use this autogenerated material > as a starting point for more elaborate documentation. So not all > features, which would be available at the higher XML level and > which you see used in the current python library reference need to > have a counterpart in an upcoming doc-string grammar. Another great deal of common sense. Regards/Saludos Manolo www.ctv.es/USERS/irmina /TeEncontreX.html /texpython.htm /pyttex.htm I just got out of the hospital after a speed reading accident. I hit a bookmark. -- Steven Wright From Manuel Gutierrez Algaba Mon Feb 7 20:53:52 2000 From: Manuel Gutierrez Algaba (Manuel Gutierrez Algaba) Date: Mon, 7 Feb 2000 20:53:52 +0000 (GMT) Subject: [Doc-SIG] Ease of use is #1 In-Reply-To: Message-ID: On Sun, 6 Feb 2000, Ka-Ping Yee wrote: > Before i begin, let me make an attempt to propose the two most important > goals of any documentation project. > > I. To encourage people to write lots of documentation. > > II. To make that documentation as accessible as possible. Great deal of common sense > > The attached file is an example; it is discussed in more detail below. > > I like the result. From Manuel Gutierrez Algaba Mon Feb 7 20:54:57 2000 From: Manuel Gutierrez Algaba (Manuel Gutierrez Algaba) Date: Mon, 7 Feb 2000 20:54:57 +0000 (GMT) Subject: [Doc-SIG] Re: Ease of use is #1 In-Reply-To: Message-ID: On Mon, 7 Feb 2000, Moshe Zadka wrote: > Assumption 4: > the "easy" part shouldn't hamper an interested documenter from > doing sophisticated things That's why we should settle two standards: - the dumb one - the guru one Two standards for the two existing realities. To impose a XML-ish docstring to "dumb-docstring" programmers would be imposible and to impose a dumb-docstring system to software companies like Zope, Ultraseek would be doubly impossible. All over the time, XML-ish and dumb-ish are fighting each other, both are right and both are wrong. Regards/Saludos Manolo www.ctv.es/USERS/irmina /TeEncontreX.html /texpython.htm /pyttex.htm I just got out of the hospital after a speed reading accident. I hit a bookmark. -- Steven Wright From Manuel Gutierrez Algaba Mon Feb 7 20:56:10 2000 From: Manuel Gutierrez Algaba (Manuel Gutierrez Algaba) Date: Mon, 7 Feb 2000 20:56:10 +0000 (GMT) Subject: Taking a poll? (was Re: [Doc-SIG] Re: Ease of use is #1) In-Reply-To: Message-ID: On Mon, 7 Feb 2000, Peter Funk wrote: > > What about taking a poll at a larger audience? Much better, what about a "genetic algorithm" poll at comp.lang.python , a large syntax trimmed by sucessive votations or augmented by sucessive votations, till we got two syntaxes: the dumb one and the XML-ish one, both of them valid. The first genetic-algorithmic-poll-made-at-internet of history. .....No, I haven't drunk Regards/Saludos Manolo www.ctv.es/USERS/irmina /TeEncontreX.html /texpython.htm /pyttex.htm I just got out of the hospital after a speed reading accident. I hit a bookmark. -- Steven Wright From fdrake@acm.org Mon Feb 7 20:31:08 2000 From: fdrake@acm.org (Fred L. Drake, Jr.) Date: Mon, 7 Feb 2000 15:31:08 -0500 (EST) Subject: [Doc-SIG] Docstring grammar: a very revised proposal In-Reply-To: References: Message-ID: <14495.11148.57519.639050@weyr.cnri.reston.va.us> Mark Hammond writes: > Im happy to ignore StructuredText for out-of-line doc for now. The critical Structured text (as evolved by David Ascher & others in this forum) is for embedded documentation. I only intend to support one out-of-line format, which will be in SGML or XML (I'm leaning toward SGML today). > issue we have to deal with is docstrings. Did we ever determine what > OReilly's position on XML and particular DTDs is? Frank Willison told me that they like to see books written in some subset of DocBook, where the specific subset depends on the topic; they want the author to use semantic markup appropriate to the subject. My impression was that the *specific* subset wasn't a real concern. I don't know that this is of real concern to us. If someone wants to feed Python's standard documentation to a publisher, DocBook can be used as an output format. > This SIG has been going for ages, and has been amazingly short on results (a > critisism that obviously includes myself!). It really is time to get > something happening, and this is an excellent start! Results? What's that? ;) -Fred -- Fred L. Drake, Jr. Corporation for National Research Initiatives From fdrake@acm.org Mon Feb 7 20:33:57 2000 From: fdrake@acm.org (Fred L. Drake, Jr.) Date: Mon, 7 Feb 2000 15:33:57 -0500 (EST) Subject: [Doc-SIG] DocStrings 0.3: Suggestion for documentation syntax (very long) In-Reply-To: <00e201bf6f5d$735cda90$0100000a@ski.org> References: <002c01bf6f04$ab116720$f0c809c0@lslp7o.lsl.co.uk> <00e201bf6f5d$735cda90$0100000a@ski.org> Message-ID: <14495.11317.119065.7005@weyr.cnri.reston.va.us> David Ascher writes: > not, etc. etc., but I don't think that Fred learned anything that he didn't > know before. Yes, I learned that there are still very few people interested in out-of-line documentation, and I can do whatever I darn well please. ;) -Fred -- Fred L. Drake, Jr. Corporation for National Research Initiatives From jack@oratrix.nl Mon Feb 7 22:21:18 2000 From: jack@oratrix.nl (Jack Jansen) Date: Mon, 07 Feb 2000 23:21:18 +0100 Subject: [Doc-SIG] Re: Ease of use is #1 In-Reply-To: Message by Moshe Zadka , Mon, 7 Feb 2000 07:13:00 +0200 (IST) , Message-ID: <20000207222124.0C745D8D4A@oratrix.oratrix.nl> Recently, Moshe Zadka said: > While I admire the way you markup by "guessing", I must admit I have my > qualms about this approach: too little control for the documenter. > Possibly, a mix of the two approaches is in order. I think I agree with this. Now that I've seen the wonderful stuff Ping can do it may indeed be worthwhile to try and get more than simple help-notes out of docstrings (as was my previous position:-). It would be nice to be able to somehow override the guessing when you (the author) know that it's wrong. Examples of this are mapping of foo() in the text to a certain foo() in the code, but there are probably many others (one that comes to mind is generated methods, as in xmllib.py). From the html-source and the comments at the bottom it appears that there is an intermediate form, so that would be a nice place to hook on to.... -- Jack Jansen | ++++ stop the execution of Mumia Abu-Jamal ++++ Jack.Jansen@oratrix.com | ++++ if you agree copy these lines to your sig ++++ www.oratrix.nl/~jack | see http://www.xs4all.nl/~tank/spg-l/sigaction.htm From da@ski.org Mon Feb 7 22:34:46 2000 From: da@ski.org (David Ascher) Date: Mon, 7 Feb 2000 14:34:46 -0800 Subject: [Doc-SIG] Re: Ease of use is #1 References: <20000207222124.0C745D8D4A@oratrix.oratrix.nl> Message-ID: <01a801bf71bb$8c1b36c0$0100000a@ski.org> From: Jack Jansen > Recently, Moshe Zadka said: > > While I admire the way you markup by "guessing", I must admit I have my > > qualms about this approach: too little control for the documenter. > > Possibly, a mix of the two approaches is in order. > > I think I agree with this. Now that I've seen the wonderful stuff Ping > can do it may indeed be worthwhile to try and get more than simple > help-notes out of docstrings (as was my previous position:-). > > It would be nice to be able to somehow override the guessing when you > (the author) know that it's wrong. Examples of this are mapping of > foo() in the text to a certain foo() in the code, but there are > probably many others (one that comes to mind is generated methods, as > in xmllib.py). FWIW, that concern is the source of my three objections to StructuredText. Quoted strings get 'verbatim'ified, __init__ get italicized, and StructuredText never complains of a parse error, so if you screw up the output is screwed up but you'll never know it. --david From Moshe Zadka Mon Feb 7 22:35:29 2000 From: Moshe Zadka (Moshe Zadka) Date: Tue, 8 Feb 2000 00:35:29 +0200 (IST) Subject: Taking a poll? (was Re: [Doc-SIG] Re: Ease of use is #1) In-Reply-To: Message-ID: On Mon, 7 Feb 2000, Peter Funk wrote: > > The authority to consult remains TBD. > > What about taking a poll at a larger audience? How would you weigh the results? (By people who contributed so far to the module docs? By people who would? By people who will?). Authority. Because arbitrary decisions (and it *is* arbitrary) should be made by someone, and then followed. Same reason standards aren't done by poles. -- Moshe Zadka . INTERNET: Learn what you know. Share what you don't. From ping@lfw.org Tue Feb 8 11:51:01 2000 From: ping@lfw.org (Ka-Ping Yee) Date: Tue, 8 Feb 2000 03:51:01 -0800 (PST) Subject: [Doc-SIG] Cross-reference proposal Message-ID: One useful thing we can accomplish, as others have pointed out, is to come up with clear and simple rules for referring to other objects in documentation. To start things off, let me try proposing a set of lookup rules for people to evaluate and shoot down. I list the rules to be applied in order of decreasing priority. When a rule applies but the referent object does not exist, we proceed to test any lower-priority rules that apply. Note that simple bare words are never interpreted as references. To refer to something, an identifier must be capitalized and match a class name, or be followed with an open-parenthesis and match a function or method name, or be preceded by "self.". 1. Text: "self." "(" In: class or method docstring Example: "self.foo(" mentioned in class "Zot" a. Refers to: method Zot.foo() b. Refers to: method foo() inherited by Zot 2. Text: "self." In: class or method docstring Example: "self.foo" mentioned in class "Zot" a. Refers to: attribute "foo" of Zot instances 3. Text: [ "." ]+ In: any docstring Example: "pkg.bar.Zot" a. Refers to: class pkg.bar.Zot 4. Text: [ "." ]+ "(" In: any docstring Example: "pkg.bar.foo(" a. Refers to: function pkg.bar.foo() 5. Text: In: any docstring Example: "Zot" mentioned in module "bar" a. Refers to: class bar.Zot 6. Text: "(" In: module or function docstring Example: "foo(" mentioned in module "bar" a. Refers to: function bar.foo() 7. Text: "(" In: class or method docstring Example: "foo(" mentioned in class "Zot" in module "bar" a. Refers to: method Zot.foo() b. Refers to: method foo() inherited by Zot c. Refers to: function bar.foo() I have attempted to make this set of rules complete while having the "obvious" behaviour. Is the suggested behaviour sufficiently obvious? I am aiming to eliminate the possibility that these rules ever fail in an unexpected way. #7 may be a bit much, but i would like to hear your opinions. I think i am comfortable with #7a,b,c. Have a look at each rule and see if you can imagine a case where it will do the wrong thing. I hope to be able to claim that each rule "just has to be right". Thanks for your time and input! -- ?!ng From gward@cnri.reston.va.us Tue Feb 8 13:26:40 2000 From: gward@cnri.reston.va.us (Greg Ward) Date: Tue, 8 Feb 2000 08:26:40 -0500 Subject: [Doc-SIG] Cross-reference proposal In-Reply-To: ; from ping@lfw.org on Tue, Feb 08, 2000 at 03:51:01AM -0800 References: Message-ID: <20000208082640.C1196@cnri.reston.va.us> On 08 February 2000, Ka-Ping Yee said: > Note that simple bare words are never interpreted as references. > To refer to something, an identifier must be capitalized and match > a class name, or be followed with an open-parenthesis and match a > function or method name, or be preceded by "self.". Two things I'm uncomfortable with here: * implicit enforcement of case conventions (modules, attributes, and methods lower-case, classes in StudlyCaps). While I think case conventions are a good thing and I like to see them followed, I'm not sure that people who *don't* follow them should be effectively barred from writing "standard" docstrings. (But my bondage 'n discipline side is cheering, "Yeah! Go! Stick it to those non-conformist punks!") * I think I'd prefer to distinguish identifiers before the docstring processor should look at them. And I'm really not sure if raising the word "self" so high in the pantheon is a good idea; it *is* an excellent convention that everyone should follow (much more so than the case convention), but the *user* of a class doesn't refer to it as 'self' -- that's something you do only when you're inside the class. Eg. in a docstring I prefer to type and to read: Don't frob the 'foo' attribute; use 'set_foo()' instead. rather than Don't frob self.foo; use self.set_foo() instead. I think I agree with at least that much from StructuredText. Greg From pf@artcom-gmbh.de Tue Feb 8 13:12:02 2000 From: pf@artcom-gmbh.de (Peter Funk) Date: Tue, 8 Feb 2000 14:12:02 +0100 (MET) Subject: [Doc-SIG] Cross-reference proposal In-Reply-To: from Ka-Ping Yee at "Feb 8, 2000 3:51: 1 am" Message-ID: Hi! Ka-Ping Yee schrieb: > One useful thing we can accomplish, as others have pointed out, > is to come up with clear and simple rules for referring to other > objects in documentation. Agreed. [...] > Note that simple bare words are never interpreted as references. Why not? Of course this may go wrong, if you use very common words like 'a', 'is', 'so' ... as identifiers. But I don't believe, that this will happen too much. [...seven rules deleted...] your rules sound a little bit complicated. I think we should model the reference rules after the python namespace visibility rules, which apply to all identifiers in the python object to document, with the exceptional handling of 'self.' within the doc-strings of class-objects: When processing the doc-string of class 'Zot' simply imagine a virtual object instance of class 'Zot' named 'self'. This behaviour seems "obvious" to me. The outcome may not be so very different from what you described in your ruleset. Regards, Peter -- Peter Funk, Oldenburger Str.86, 27777 Ganderkesee, Tel: 04222 9502 70, Fax: -60 From tony@lsl.co.uk Tue Feb 8 13:40:55 2000 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Tue, 8 Feb 2000 13:40:55 -0000 Subject: [Doc-SIG] Cross-reference proposal In-Reply-To: Message-ID: <000001bf723a$1fda19c0$f0c809c0@lslp7o.lsl.co.uk> Ka-Ping Yee wrote, on 08 February 2000 11:51: > Note that simple bare words are never interpreted as references. Urm - but... > To refer to something, an identifier must be capitalized and match > a class name, that sure sounds to me like it could be a "simple bare word" - if I have a class called London that handles data relating to the city of London, then I'll certainly use the noun and the class name in the same text. > or be followed with an open-parenthesis and match a > function or method name, The company I work for have a customer who are the Ordnance Survey for Great Britain (as opposed to the Ordnance Survey for Northern Ireland, who are *not* the same people). This is commonly abbreviated OS(GB) (strangely enough, OSNI is not OS(NI)). It is not inconceivable that code written to handle OS(GB) data might have a function somewhere called OS()... (and I would not be prepared NOT to write such code just to make the documentation processing easier!). > or be preceded by "self." OK - I find it harder to come up with an awkward example for this one, *but I bet I could given enough time to think* (heh, I've been *paid* to be a pedant on occasion!). The point? I think that we MUST require some delimitation for words/phrases that are to become links into the code, because *in practice* it is not possible to guess often enough (and I don't regard my awkward examples of the guessing failing as "odd" cases at all, thank you very much). The alternative suggestion (flag the awkward cases to say "don't guess wrong here") seem to me truly horrid. (I've used a documentation preprocessing system which, whilst dumber - it doesn't discriminate *nearly* as well as your algorithm - still illustrates the sheer frustration of typing perfectly normal english text and having odd words highlighted when one doesn't want them to be.) despite-this-the-output-of-your-algorithm-is-very-pretty,guv Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.demon.co.uk/ .. "equal" really means "in some sense the same, but maybe not .. the sense you were hoping for", or, more succinctly, "is .. confused with". (Gordon McMillan, Python list, Apr 1998) My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From Moshe Zadka Tue Feb 8 14:01:58 2000 From: Moshe Zadka (Moshe Zadka) Date: Tue, 8 Feb 2000 16:01:58 +0200 (IST) Subject: M.Z. assumptions (was Re: [Doc-SIG] Re: Ease of use is #1) In-Reply-To: <14495.1905.906349.867382@weyr.cnri.reston.va.us> Message-ID: On Mon, 7 Feb 2000, Fred L. Drake, Jr. wrote: > Ok, guys, I think this points out where the communications failure > is (what other kind is there?). Which was the purpose of my "assumptions" mail > Docstrings, combined with language information obtained from the > parse tree or reflection, should be sufficient to generate "usable" > documentation "most" of the time. OK, that sounds like a good goal for the doc-string grammar proposal. As a way to make it a bit less vague let me suggest one criterion for any doc-string syntax: pick any 2-3 doc-string'ed modules from the standard library, and mark them up so the resulting documentation will be just as good as what is currently in the library reference. Any suggestion which doesn't meet this criterion will surely fail whatever vague notion Fred has (unless it is vague enough ) > (Moshe: Please don't think I meant that *you* really had to do > *everything* with the documentation! I was just joking about that at > the IPC8 Doc-SIG session! We welcome your participation, but it's up > to me to act as channel for the BDFL here; keeps the hate mail in my > box rather than yours. ;) if-I-wouldn't-want-to-take-you-seriously-I-wouldn't-ly y'rs, Z. -- Moshe Zadka . INTERNET: Learn what you know. Share what you don't. From fdrake@acm.org Tue Feb 8 15:27:17 2000 From: fdrake@acm.org (Fred L. Drake, Jr.) Date: Tue, 8 Feb 2000 10:27:17 -0500 (EST) Subject: [Doc-SIG] Poll-schmoll, READ THIS! Message-ID: <14496.13781.278928.303319@weyr.cnri.reston.va.us> Doc-SIG readers, This is a long message, but please read it. Moshe Zadka writes: > Authority. Because arbitrary decisions (and it *is* arbitrary) should be > made by someone, and then followed. Same reason standards aren't done > by poles. At some point, I will make a recommendation to Guido substantially based on what comes out of this SIG. He will say "yes" or "fix ....", and that will be that. [What follows refers specifically to embedded documentation.] What *I'm* looking for is something to hand to Guido, with an implementation on hand. I want tools that don't require the import of a module's source code. I want it to produce a data structure that can be stored persistently, and I want to be able to produce really nice HTML. I want it written in 100% Python and work with both the CPython and JPython interpreters. Once this is available, I can start dealing with support for multiple formats and that sort of thing. [Back to your regularly scheduled SIG!] I think this SIG has made progress in fits and starts for a variety of reasons, including insufficient availability of my time to implement suggestions or keep up with the discussions. On the other hand, we have seen a number of things start to coalesce recently (never mind that they seem about to fall apart some days). While David seems to think we got very little out of the Doc-SIG session at the conference, I don't agree. David's current stance on StructuredText is good; it leverages existing work more than previous proposals and keeps the markup for embedded documentation quite minimal. It appears that sufficient support for rich hyperlinking can be built without costing too much. Let's support David and the StructuredText people so this can be a fruitful effort. What I got out of the conference was that the most important thing was to quite bickering about syntax and decide on one format for embedded documents and one for out-of-line documents. The attendees at the session seemed to be largely unconcerned about the specific syntax used. For inline, we've agreed here that the syntax should be minimal and that "just-text" docstrings should work. I stated that they would work *well*, so that's a specific requirement for tool builders on this one. I also got the message that nobody really cares about the SGML vs XML debate (it *is* a minor detail), and nobody really cares about the specific DTD. I will write one based on the existing conversion project; we can hash out details here a bit, but it will be frozen relatively quickly. I'll need someone to write stylesheets for typesetting; DSSSL or XSLT/XSL would be fine. We may be able to do the HTML conversion using DSSSL or XSLT as well; if so, I'd like to use the same stylesheet language for that if possible in order to keep the required tool set small, but whether we use multiple stylesheets or one parameterized stylesheet (a la Norm Walsh's modular stylesheets for DocBook) isn't terribly important. We will support at least HTML and one typeset format before we can "cut over" documentation maintenance to the new system. -Fred -- Fred L. Drake, Jr. Corporation for National Research Initiatives From Edward Welbourne Tue Feb 8 16:00:19 2000 From: Edward Welbourne (Edward Welbourne) Date: Tue, 8 Feb 2000 16:00:19 +0000 Subject: [Doc-SIG] Cross-reference proposal In-Reply-To: References: Message-ID: >> Note that simple bare words are never interpreted as references. > > Why not? Of course this may go wrong, if you use very common words > like 'a', 'is', 'so' ... as identifiers. But I don't believe, that > this will happen too much. umm ... I believe the reverse. * A string-processing function with an argument which decides whether to capitalise the string is almost certain to use the verb capitalise (in its Natural Language sense) in the course of its account of the argument which it will, naturally, call `capitalise'. * Many I/O routines use buffers whose size the caller can control via a parameter, usually called buffer; an account of whose meaning will routinely involve refering (in the NL sense) to the buffer whose size is controlled by the argument. * ... It is *in general* Good Practice to name parameters (especially those which the caller is expected to give in name=value form) using plain words which fit close to the NL words relating to the purpose of the parameter. Any account of the purpose of the parameter is, consequently, liable to use the NL sense of the word as well as using the word to refer to the parameter. IMO, this forces us to have some equivalent of the *emphasis* markup. As to *what* should serve in this role: well, it's going to enclose things which are to be read as lumps of python code in the doc string, within which any identifiers are to be hyperlinked to the definition of the object referenced by that identifier; so we can't go using any character which can appear in an inline-in-the-doc code fragment (e.g. regarding 'quoted text' as code fragment is unacceptable, because my code fragment may wish to include a 'quoted string'). I don't think $, @ and ! are good candidates, but they could work; however, how do folk feel about # as a marker ? Since we're in a doc-string, it doesn't have any special meaning; nor do I think it sensible to include an end-of-line-comment in an inline-in-the-doc code fragment (as opposed to a code fragment displayed using a Code: block or >>>). Thus #any.valid(python + ' code') is guaranteed(to, work)#. Then we get: Arguments: file ! string -- the name of the file to be opened. mode ! string -- the file access mode string ... If #mode#'s first letter is #'r'#, #file# must exist. buffer ! int or None [None] -- size of the I/O buffer to use. A size #< 0# indicates that no buffering should be done (raw I/O). If #buffer# is given as #None#, a `sensible' buffer size will be chosen. and only treat words in the description (after --) as special if explicitly marked as such. Of course, since this is the Arguments: block, treating the key (before !) as special comes naturally without needing to mark it using #. Exceptions: IOError -- raised if #file# does not exist, #mode# is unrecognised or if #buffer#'s value is inappropriate for the given #file# and #mode#. This fits the `easy to type' requirement; how do folk feel about `easy to read' ? Note that I, at least, find it has one bonus under `easy to read'; I know when a word is used in its NL sense and when it is used to refer to something in the python code; that makes it easier to understand what I read. As to creating cross-references: identifiers appearing inside #...# or in the body of a Code: block can be sought using the namespace lookup machinery python would use from within the body of the thing whose doc-string we're parsing; where the lookup finds something with a doc-string, it is natural to generate an href to that doc-string (or, rather, what it will become when parsed). This should only need to happen for things marked as code. Does this fit the requirement for clear and simple rules ? Summary: * Within text (not within Code: &c. blocks), # is used as delimiter for (start and end of) in-text code fragments. * Code:, Example: and >>> blocks and in-text code fragments are parsed; identifiers within them are looked up as if by the interpreter when executing the suite which the doc-string begins; if these lookups yield something to which the generated docs can make an HREF, they do so. Note that, * in #open('peter', 'r')#, peter does not appear as an identifier (it appears as a string) so no attempt is made to look peter up in any namespaces. * use of #code(fragments)# is viable within comments, either in real python code (outside the doc-string) or in Code: &c. blocks. Given the latter, it would make sense for the parse-and-href idiom to ignore end-of-line comments in Code: &c. blocks, but to recognise code fragments in such comments and subject these to parse-and-href. > [Ka Ping's] rules sound a little bit complicated. they are amenable to some simplification, though. Eddy. -- Actually, starting /* and ending */ would do fine ... the funny thing is, in C, that */ would be the obvious way to *start* comments, since it cannot appear in valid code. As ever, K&R didn't do the obvious. From pf@artcom-gmbh.de Tue Feb 8 16:01:01 2000 From: pf@artcom-gmbh.de (Peter Funk) Date: Tue, 8 Feb 2000 17:01:01 +0100 (MET) Subject: M.Z. assumptions (was Re: [Doc-SIG] Re: Ease of use is #1) In-Reply-To: from Moshe Zadka at "Feb 8, 2000 4: 1:58 pm" Message-ID: Hi! [Fred]: > > Docstrings, combined with language information obtained from the > > parse tree or reflection, should be sufficient to generate "usable" > > documentation "most" of the time. [Moshe Zadka]: > OK, that sounds like a good goal for the doc-string grammar proposal. As > a way to make it a bit less vague let me suggest one criterion for any > doc-string syntax: pick any 2-3 doc-string'ed modules from the standard > library, and mark them up so the resulting documentation will be just as > good as what is currently in the library reference. Any suggestion which > doesn't meet this criterion will surely fail whatever vague notion Fred > has (unless it is vague enough ) Do you really mean, you actually want to change the markup of already doc string'ed Lib/... modules by encrypting^H^H^H^H^H^H^H^Hediting their current doc-strings? ;-) Or should we better look at existing doc-string'ed Lib/... modules (most of them got doc string'ed in the CVS last weekend) and look, whether a clever tool (something like 'pythondoc/gendoc/manpy') could possibly gather enough information without special markup, which is sufficient enough "most" of the time? Or should we first have a look at the rich set of LaTeX macros described in Freds .../Doc/doc/doc.tex and run a histogram analysis script over .../Doc/lib/...*tex and count, which of them are really regulary used? The current style files define some very esoteric markup tags. Others are used often, like section headings, nested lists, \code, verbatim-environment .... I guess, that an enhanced 'StructuredText' approach augmented with a identifier reference analysis similar to this suggested by ping today will be able to tag the most often used elements in doc-strings without the need to heavily modify any existing doc strings. Okay. ASCII graphics like this seen in ping's example 'SocketServer.py' will be very difficult. But those are rare in doc-strings anyway. Regards, Peter -- Peter Funk, Oldenburger Str.86, 27777 Ganderkesee, Tel: 04222 9502 70, Fax: -60 From fdrake@acm.org Tue Feb 8 18:09:25 2000 From: fdrake@acm.org (Fred L. Drake, Jr.) Date: Tue, 8 Feb 2000 13:09:25 -0500 (EST) Subject: M.Z. assumptions (was Re: [Doc-SIG] Re: Ease of use is #1) In-Reply-To: References: <14495.1905.906349.867382@weyr.cnri.reston.va.us> Message-ID: <14496.23509.143263.376869@weyr.cnri.reston.va.us> Moshe Zadka writes: > OK, that sounds like a good goal for the doc-string grammar proposal. As > a way to make it a bit less vague let me suggest one criterion for any > doc-string syntax: pick any 2-3 doc-string'ed modules from the standard > library, and mark them up so the resulting documentation will be just as > good as what is currently in the library reference. Any suggestion which > doesn't meet this criterion will surely fail whatever vague notion Fred > has (unless it is vague enough ) I'd like to see a processing tool that outputs structure. This should probably be based on pythondoc, since a lot of the work is done there; perhaps Ping would like to work on that? ;-) It has the nice property of supporting multiple backends. I've no idea of the quality of the code; last time I tried it, it just wouldn't work for me. Is Daniel Larson still working on pythondoc? > if-I-wouldn't-want-to-take-you-seriously-I-wouldn't-ly y'rs, Z. the-catch-of-course-is-that-sometimes-you-can't-even-if-you-want-to-ly y'rs, -Fred -- Fred L. Drake, Jr. Corporation for National Research Initiatives From ping@lfw.org Tue Feb 8 21:40:14 2000 From: ping@lfw.org (Ka-Ping Yee) Date: Tue, 8 Feb 2000 15:40:14 -0600 (EST) Subject: [Doc-SIG] Cross-reference proposal In-Reply-To: Message-ID: > your rules sound a little bit complicated. I think we should model the > reference rules after the python namespace visibility rules, Actually, i did try to model the rules after namespace rules (note the rules with respect to dotted references to things in other modules). > This behaviour seems "obvious" to me. The outcome may not be so > very different from what you described in your ruleset. It's kind of too bad that it came out appearing complicated. What i tried to do there was to give an exact specification of an algorithm that would yield the kind of "simple" or "obvious" behaviour you expect. A more succinct description of the intended behaviour would be: 1. dotted.references to classes or functions in other modules 2. dotted.references to class methods or attributes 3. references() to class methods or functions 4. references to class names in the local module Unfortunately the attempt to be very precise about how to achieve this behaviour yielded a long-winded and pedantic description. I just wanted to provide a very clearly stated framework for us to pick and poke at. -- ?!ng From ping@lfw.org Tue Feb 8 21:44:49 2000 From: ping@lfw.org (Ka-Ping Yee) Date: Tue, 8 Feb 2000 15:44:49 -0600 (EST) Subject: [Doc-SIG] Cross-reference proposal In-Reply-To: Message-ID: Tony J Ibbs wrote: > that sure sounds to me like it could be a "simple bare word" - if I have a > class called London that handles data relating to the city of London, then > I'll certainly use the noun and the class name in the same text. [...] > The company I work for have a customer who are the Ordnance Survey for Great > Britain (as opposed to the Ordnance Survey for Northern Ireland, who are > *not* the same people). This is commonly abbreviated OS(GB) (strangely Edward Welbourne wrote: > > umm ... I believe the reverse. > * A string-processing function with an argument which decides whether > to capitalise the string is almost certain to use the verb > capitalise (in its Natural Language sense) in the course of its > account of the argument which it will, naturally, call `capitalise'. So here are three examples of what Tony and Edward might consider "unintended" references. Let me ask a radical question: if you had a class named London in your module, and you happened to mention the city of London in your docstring somewhere -- what would be so wrong with linking that mention to the class named London? Or if you have an argument named "capitalise" and somewhere in the documentation you use the word "capitalise" -- is it really a problem that that word is interpreted as referring to the argument? Surely if you "just happen" to use exactly the name of a class in your module documentation somewhere, it's somehow related... ? -- ?!ng From dgoodger@bigfoot.com Tue Feb 8 22:10:48 2000 From: dgoodger@bigfoot.com (David Goodger) Date: Tue, 08 Feb 2000 17:10:48 -0500 Subject: [Doc-SIG] Docstring: a newbie's two bits In-Reply-To: <20000208170051.DA62A1CD66@dinsdale.python.org> Message-ID: Let me introduce myself. I am an experienced programmer with a plethora of languages under my belt (C/C++, Pascal, the dreaded BASIC, Lisp/Scheme, Perl, csh/ksh/bash scripting, AppleScript, and others in passing). I delved into Python about a year ago, and loved it. I have 3 years intense experience in an SGML analysis/design/processing environment. I have been reading the Doc SIG digests for about a week, plus some back issues from the archive. Please forgive me if I cover old ground. I am about to release a set of (relatively small) open-source libraries & tools. I have been using the docstring mechanism for internal documentation all along, and was delighted to find there were tools available to extract & mark up docstrings into something usable as documentation. Imagine my relief when I learned that I didn't *have* to use TeX if I wanted to use standard tools! As a newbie, without any affiliation to one approach or another, I thought I'd give you some opinions about the current docstring discussions. Please take it as a vote from a typical (atypical?) member of the intended audience. No offense to anyone is intended (nor, I hope, taken). They take a little getting used to, but the rules of Structured Text (as at http://www.python.org/sigs/doc-sig/stext.html) are easy to apply. I wouldn't want to see much more tagging than this, however. I use docstrings as working documentation, to be written in parallel with (ok, slightly *after*) writing the code. And I refer to this documentation also, so it **must** be readable (see? I'm already using the StructText conventions!). The docstring documentation (as output by the tools) would only be a start for final publication-quality documentation, however, so I'm not worried about lack of fine-tweaking control. HTML is great for quick & dirty user documentation or for on-screen display, but its formatting-oriented tagging makes it next to useless for anything more ambitious. I am pleased to hear that an effort is underway to create an SGML/XML DTD, a la DocBook (PyBook?) or whatever. Specifics: - I would not use any kind of [tag content] or tag[content] or Message-ID: <000401bf7293$f30ba990$c355cfc0@ski.org> > Actually, i did try to model the rules after namespace rules > (note the rules with respect to dotted references to things in > other modules). BTW, those rules look fine to me. From pf@artcom-gmbh.de Wed Feb 9 09:06:12 2000 From: pf@artcom-gmbh.de (Peter Funk) Date: Wed, 9 Feb 2000 10:06:12 +0100 (MET) Subject: [Doc-SIG] pythondoc/gendoc (was Re: Poll-schmoll, READ THIS!) In-Reply-To: <14496.13781.278928.303319@weyr.cnri.reston.va.us> from "Fred L. Drake, Jr." at "Feb 8, 2000 10:27:17 am" Message-ID: Hi! [Fred L. Drake, Jr.]: [...] > I want tools that don't require the import of a module's source code. The current implementation of pythondoc doesn't meet this requirement, since it does 'import'. I like to cite from the README in 'gendoc-0.73', which supports both modes: gd> Did some simple measurements on gendoc generating HTMLg gd> documentation for all python modules in the standard gd> ditribution (almost) (HP 712/80Mhz): gd> gd> gendoc -i (import mode) gendoc -p (parser mode) gd> ----------------------- ----------------------- gd> real 6m19.93s real 1h26m31.63s gd> user 1m56.36s user 22m29.63s gd> sys 0m10.41s sys 0m47.38s However with todays computer this speed issue shouldn't matter much. [Fred]: > I want it to produce a data structure that > can be stored persistently, and I want to be able to produce really > nice HTML. I want it written in 100% Python and work with both the > CPython and JPython interpreters. The notion of formatters is present both in pythondoc and gendoc. The data structures in pythondoc seem to be little bit clearer and better to understand. I'm however eager to have a look at ping's manpy. [Fred]: > I'd like to see a processing tool that outputs structure. This > should probably be based on pythondoc, since a lot of the work is done > there; perhaps Ping would like to work on that? ;-) It has the nice > property of supporting multiple backends. I've no idea of the quality > of the code; last time I tried it, it just wouldn't work for me. > Is Daniel Larson still working on pythondoc? Daniel Larsson (who is currently still subscribed to this list, Hi!), seems to be very busy or on vacation at the moment. Last week I downloaded his 'pythondoc_07.zip' (released on Jan 25th 2000) and send email to him pointing out, that this archive contains files, which are definitely older than those contained in the 'pythondoc-0.6.tgz' he has released before. He has not reacted yet. Regards, Peter. -- Peter Funk, Oldenburger Str.86, 27777 Ganderkesee, Tel: 04222 9502 70, Fax: -60 From tony@lsl.co.uk Wed Feb 9 10:14:38 2000 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Wed, 9 Feb 2000 10:14:38 -0000 Subject: [Doc-SIG] Cross-reference proposal In-Reply-To: Message-ID: <000201bf72e6$78a6b8e0$f0c809c0@lslp7o.lsl.co.uk> Ka-Ping Yee wrote, on 08 February 2000 21:45: > Let me ask a radical question: if you had a class named London in > your module, and you happened to mention the city of London in > your docstring somewhere -- what would be so wrong with linking > that mention to the class named London? > > Or if you have an argument named "capitalise" and somewhere in the > documentation you use the word "capitalise" -- is it really a > problem that that word is interpreted as referring to the argument? > > Surely if you "just happen" to use exactly the name of a class > in your module documentation somewhere, it's somehow related... ? My immediate (and thus emotional) response to that is "NO!". This seems to be for two reasons: 1. I don't want spurious extra references that I don't intend (this is important to me, but I can see from the above you might not care). 2. It's quite possible to use common words in ways which are *not* applicable for the cross-reference. Hmm - thinks a bit... OK, here we go with an example: def BLOCKS(text,delimiter): """Given text and a paragraph delimiter, return paragraph BLOCKS. burble burble burble on a flowline model burble. burble think of it as pieces of text flowing along a pipeline burble if something goes wrong such that the pipeline BLOCKS up burble burble. """ Not a *very* contrived example. I've "highlighted" the word "blocks" as best I can in email. Note that the second usage of the word in the doc string is *not* a candidate for cross referencing. Given the nature of the english language (I can't speak for others) such multiple binding of meaning for a single word is common. trying-to-give-constructive-criticism,honest-guv Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.demon.co.uk/ 'Tim happens. Get used to it'. (David Ascher, on the Doc-SIG) My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Wed Feb 9 10:20:18 2000 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Wed, 9 Feb 2000 10:20:18 -0000 Subject: [Doc-SIG] Cross-reference proposal In-Reply-To: Message-ID: <000301bf72e7$434bb4b0$f0c809c0@lslp7o.lsl.co.uk> Looking at how one would delimit references to code items, Edward Welbourne wrote, on 08 February 2000 16:00: > I don't think $, @ and ! are good candidates, but they could work; > however, how do folk feel about # as a marker ? Since we're in a > doc-string, it doesn't have any special meaning; nor do I think it > sensible to include an end-of-line-comment in an inline-in-the-doc code > fragment (as opposed to a code fragment displayed using a Code: block or > >>>). Thus #any.valid(python + ' code') is guaranteed(to, work)#. I dislike "#" for two reasons: 1. I dislike it (i.e., it looks nasty to me). I find it visually distracting to try to parse the Python comment character as something else, in a Python file, and anyway, it just looks wrong (damn - that last isn't a very convincing bit of the argument). Eddy and I have been known to disagree about such things, of course. 2. I *do* use comments in doc strings! I do! As a strong believer in comments, if I include code in a doc string, it's damn well likely to be commented! - not least because it's probably copied from some actual code, which probably has comments in it. (sorry - this gets me in a ticklish spot, as it feels to me akin to the tendency of people teaching programming languages to first say "comments are good" and then present skads of examples where they don't use any, normally with the excuse "but it's only short, and an example, so I haven't bothered. Been there, seen that.) Tibs # no, I wouldn't say I overcomment my code... -- Tony J Ibbs (Tibs) http://www.tibsnjoan.demon.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From Edward Welbourne Wed Feb 9 11:51:24 2000 From: Edward Welbourne (Edward Welbourne) Date: Wed, 9 Feb 2000 11:51:24 +0000 Subject: [Doc-SIG] Cross-reference proposal In-Reply-To: <000301bf72e7$434bb4b0$f0c809c0@lslp7o.lsl.co.uk> References: <000301bf72e7$434bb4b0$f0c809c0@lslp7o.lsl.co.uk> Message-ID: > 2. I *do* use comments in doc strings! Not an issue. As I specified it, the use of #...# is for samples of *code when they appear in text* within a doc string. Thus, for example: One can call #open('/tmp/junk', 'w')# to obtain a scratch file or one can use: Code: i = 0 while 1: try: fd = open('/tmp/junk%d' % i, 'r') # ith template file except IOError: return open('/tmp/junk%d' % i, 'w') # nonexistent file fd.close() i = 1 + i The parser knows when it's in an embedded Code: block so regards # as starting a comment in one of those; but where it meets # in the text of a paragraph, it knows that it's the start of an in-text code fragment. Furthermore, in a Code: block but after the first # on a line, we can use #...# to delimit fragments of code appearing in a comment (just as we can use *emphasis* in comments without the * being interpreted as `multiply') and have the doc-string parser understand it as such. If you're putting comments *against the text* in a doc string, # thus, as opposed to *within an example block*, you're being gratuitously perverse and you deserve everything you get ;^> As to # not being pretty ... tough. Being unambiguous is important, being easy to spot is important, being easy to type is important, being pretty is what the down-stream tools support. Fontification and colouring might be able to help, in the mean time ... Eddy. From paul@prescod.net Wed Feb 9 16:33:38 2000 From: paul@prescod.net (Paul Prescod) Date: Wed, 09 Feb 2000 08:33:38 -0800 Subject: [Doc-SIG] Cross-reference proposal References: <000201bf72e6$78a6b8e0$f0c809c0@lslp7o.lsl.co.uk> Message-ID: <38A196E2.A8BB9EBD@prescod.net> "Tony J Ibbs (Tibs)" wrote: > > ... > > Not a *very* contrived example. I've "highlighted" the word "blocks" as best > I can in email. Note that the second usage of the word in the doc string is > *not* a candidate for cross referencing. Given the nature of the english > language (I can't speak for others) such multiple binding of meaning for a > single word is common. Okay, but what is the real cost of the mis-identification? -- Paul Prescod - ISOGEN Consulting Engineer speaking for himself The great era of mathematical physics is now over; the 300-year effort to represent the material world in mathematical terms has exhausted itself. The understanding it was to provide is infinitely closer than it was when Isaac Newton wrote in the late seventeenth centruy, but it is still infinitely far away. - The Advent of the Algorithm (pending), by David Berlinski From tony@lsl.co.uk Thu Feb 10 09:08:11 2000 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Thu, 10 Feb 2000 09:08:11 -0000 Subject: [Doc-SIG] Cross-reference proposal In-Reply-To: <38A196E2.A8BB9EBD@prescod.net> Message-ID: <000e01bf73a6$5adea7d0$f0c809c0@lslp7o.lsl.co.uk> Paul Prescod wrote, on 09 February 2000 16:34: > "Tony J Ibbs (Tibs)" wrote: > > Note that the second usage of the word in the doc string is > > *not* a candidate for cross referencing. Given the nature of the > > english language (I can't speak for others) such multiple binding > > of meaning for a single word is common. > > Okay, but what is the real cost of the mis-identification? Erm - it's wrong?[1] But seriously, if I'm reading a document and come across a cross reference, is it *really* too much to ask that it be relevant? I know I'm a pedant (well, of some sort), but this is text that's meant to be *helpful* to people, and if it consistently contains (or may contain) misleading cross references, then that engenders distrust of the text - one never knows whether it will be worth *following* a reference (I can hear it now - "drat, that *!@X&! has cocked up their referencing again - I thought I'd find something *useful* there!"). Also, it's pride - if I'm writing documentation in a doc string, then it's MY text, and I don't want it to be mucked up by an (otherwise) useful tool. Putting in *misleading* references would be such mucking up. As for misleadingness - there *are* words in the english language that can have entirely opposite, and certainly antagonistic, meanings in different contexts. If the misreference in such a circumstance, life could get truly confusing. Tibs [1] The pedant in me wants to leave it at that, on the grounds that the rest is trivially derived from this, but since Paul asked I guess it *does* need explanation... -- Tony J Ibbs (Tibs) http://www.tibsnjoan.demon.co.uk/ .. Haskell is the most Pythonic of all the languages that are entirely .. unlike Python <0.9 wink> (Tim Peters) My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From Edward Welbourne Thu Feb 10 09:12:28 2000 From: Edward Welbourne (Edward Welbourne) Date: Thu, 10 Feb 2000 09:12:28 +0000 Subject: [Doc-SIG] Cross-reference proposal In-Reply-To: <38A196E2.A8BB9EBD@prescod.net> References: <000201bf72e6$78a6b8e0$f0c809c0@lslp7o.lsl.co.uk> <38A196E2.A8BB9EBD@prescod.net> Message-ID: > Okay, but what is the real cost of the mis-identification? Clutter. A document, which should have five words picked out neatly as hrefs to significant text elsewhere, has twenty hrefs, almost all the extras being spurious. Now look at the result and tell me which five were the pertinent hrefs ... ? Eddy. From tony@lsl.co.uk Thu Feb 10 09:15:35 2000 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Thu, 10 Feb 2000 09:15:35 -0000 Subject: [Doc-SIG] Cross-reference proposal In-Reply-To: Message-ID: <000f01bf73a7$63c08fc0$f0c809c0@lslp7o.lsl.co.uk> Talking with Eddy yesterday, he pointed out something that I hadn't thought about, which is the general usefulness of Ka-Ping Yee's "documentation from un-annotated doc strings" tool when one actually *wants* to get documentation from the vast number of doc strings which don't have annotation. I think that's a tool we *need*, and it looks like Ka-Ping Yee's approach is excellent for that purpose. So please don't take my grumbles about not wanting to go that route as saying I don't think the tool is very clever, and (I now realise) also very useful. I also rather like the appearance of the web page produced! (although I haven't read the HTML). Oh - and has anyone else said how nice it is to see Ka-Ping back on the Python lists again? Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.demon.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From ping@lfw.org Thu Feb 10 11:29:57 2000 From: ping@lfw.org (Ka-Ping Yee) Date: Thu, 10 Feb 2000 03:29:57 -0800 (PST) Subject: [Doc-SIG] Cross-reference proposal In-Reply-To: <000f01bf73a7$63c08fc0$f0c809c0@lslp7o.lsl.co.uk> Message-ID: On Thu, 10 Feb 2000, Tony J Ibbs (Tibs) wrote: > > I also rather like the appearance of the web page produced! (although I > haven't read the HTML). There is one particular thing that makes the HTML rather ugly: all the spaces in the docstrings are replaced with " "s (non-breaking spaces). This is to prevent word-wrapping so that any formatting in the docstrings (like that diagram at the top of SocketServer.py) is preserved. > Oh - and has anyone else said how nice it is to see Ka-Ping back on the > Python lists again? Wow, Tony, that's so nice of you! I have to say i'm really glad to be back too. -- ?!ng "Je n'aime pas les stupides garçons, même quand ils sont intelligents." -- Roople Unia From ping@lfw.org Thu Feb 10 11:45:18 2000 From: ping@lfw.org (Ka-Ping Yee) Date: Thu, 10 Feb 2000 03:45:18 -0800 (PST) Subject: [Doc-SIG] Cross-reference proposal In-Reply-To: <000e01bf73a6$5adea7d0$f0c809c0@lslp7o.lsl.co.uk> Message-ID: On Thu, 10 Feb 2000, Tony J Ibbs (Tibs) wrote: > Paul Prescod wrote, on 09 February 2000 16:34: > > > > Okay, but what is the real cost of the mis-identification? > > Erm - it's wrong?[1] > > But seriously, if I'm reading a document and come across a cross reference, > is it *really* too much to ask that it be relevant? Mmm. Okay. Well, first of all, let's carefully define and reduce the issue. Here is the list of kinds of auto-referencing again: 1. dotted.references to classes or functions in other modules 2. dotted.references to class methods or attributes 3. references() to class methods or functions 4. references to class names in the local module The question to ask, then, is: Of these cases, for which are there likely to exist situations where the cross-reference is misleading? So, first, i posit that #1, #2, and #3 are unambiguous enough not to bother anyone. That is, i hypothesize that no one would write . that happens to match the name of a module member or class method and *not* be referring to that thing. Does anyone have a problem with that much? #4 might be considered a little dangerous; more dangerous is 5. references to argument names in function and method docstrings since these are likely to be just ordinary unmarked words. It's #4 and #5 that concern you, right? Well, there is a spectrum of comfort zones for this kind of automatic interpretation. I think i have placed these categories in order, from #1 which i think is very solid, to #5 which i think is the most shaky. And #5 i would agree is approaching the limit of my comfort level. I didn't think that #4 would be too unreasonable to propose. Does it make you uncomfortable? (survey for all, not just Tony) > references, then that engenders distrust of the text - one never knows > whether it will be worth *following* a reference (I can hear it now - "drat, > that *!@X&! has cocked up their referencing again - I thought I'd find > something *useful* there!"). Right, well at least i don't think there ought to be a situation where the reader doesn't know whether it will be worth following a reference -- because i think it is a basic requirement that it always be transparently obvious what the reference will lead to. And i think that for #1 through #4 above this is true. (Even in cases where the introduced reference is spurious, it would still be quite obvious where the hyperlink will take you.) > Also, it's pride - if I'm writing documentation in a doc string, then it's > MY text, and I don't want it to be mucked up by an (otherwise) useful tool. > Putting in *misleading* references would be such mucking up. Yup. This is an entirely justified reason even if it may sound emotionally driven at first blush. I don't want anyone messing up *my* text either. :) > [1] The pedant in me wants to leave it at that, on the grounds that the rest > is trivially derived from this, but since Paul asked I guess it *does* need > explanation... I'm glad that you broke it down into specific reasons. Thanks. -- ?!ng "Je n'aime pas les stupides garçons, même quand ils sont intelligents." -- Roople Unia From tony@lsl.co.uk Thu Feb 10 12:30:39 2000 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Thu, 10 Feb 2000 12:30:39 -0000 Subject: [Doc-SIG] Cross-reference proposal In-Reply-To: Message-ID: <001901bf73c2$a38ed600$f0c809c0@lslp7o.lsl.co.uk> Ka-Ping Yee reiterated a list of possible things to autodetect: > 1. dotted.references to classes or functions in other modules > 2. dotted.references to class methods or attributes > 3. references() to class methods or functions > 4. references to class names in the local module > 5. references to argument names in function and method docstrings > The question to ask, then, is: Of these cases, for which are there > likely to exist situations where the cross-reference is misleading? He then guesses my answers, but I'm going to ignore that... Hmm. There are two answers: T1. In "marked up" docstrings, none of the above should be autodetected. I'll get into why below, but basically mark it down as "I'm paranoid" for the moment. T2. In docstrings with no markup, I think you should be able to do what you like, and although 3..5 may be risky, the benefit probably outweighs the problem (i.e., I'll put up with spurious references IN THIS CASE so I can get the correct ones as well). It might be polite to put a note at the top of the page saying that the markup is autogenerated, though, so that people don't blame the original author of the doc string for any mistakes (that's politeness to those of us with ego!). Expanding on T1 above. As you posit, 5 is generally dangerous. I hope I demonstrated (elsewhere, "London") that 4 is equally dangerous, and I reckon I can come up with other cases (than "OS(GB)") why 3 is dangerous too. But note that 1 and 2 are dangerous as well - english allows acronyms with "." as well as without (so NASA and BBC don't have dots, but N.B. does, and there are better examples which unfortunately I can't call to mind - try looking up a good style guide to publishing and I'm sure it will have examples). My *general* point is that, given the nature of the english language, it is *impossible* to *guarantee* that you will get it right, however complex the rules you produce. Now, for case T2 that's OK - we're trying to generate something from nothing, and I personally am willing to accept mistakes. But for T1 you're messing with someone's (hopefully) lovingly crafted text, and I refer you back to my previous points (and Eddy's too). [In fact, given that this is *programming* we're documenting, it is almost certain that someone will want to do *very* odd things in documentation that we haven't and probably *can't* think of, which render non-markup schemes untenable if one wants a decent result.] Hmm - and it's just occurred to me that if a programmer is marking up their text, they might also have a *reason* for suppressing a cross reference - one example is if they're talking about how one *might* have implemented fred.spam (definitely don't want a reference here) rather than how they actually *have* implemented #fred.spam# (to use Eddy's annotation, which I still hate). Summary: if it's autogenerated from no markup, the more guessing one can do the better, and your rules are well thought out, but if it's written by an author with intentional markup, then that markup is *all* one is *allowed* to infer. Tibs (And yes, I'm bringing in experience as a reader and writer of english, of being a pedant, of being a standards writer and user (very different experiences!), and also of producing a fanzine/magazine (using TeX) containing contributions from English and American speakers, where I needed to keep the original voice, spelling, etc., intact - how's that for spurious appeals to authority!) (oh - and I'm a programmer as well) -- Tony J Ibbs (Tibs) http://www.tibsnjoan.demon.co.uk/ Feet first with 5 wheels... (although not enough in the past few weeks) My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Thu Feb 10 12:57:14 2000 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Thu, 10 Feb 2000 12:57:14 -0000 Subject: [Doc-SIG] Cross-reference proposal In-Reply-To: <001901bf73c2$a38ed600$f0c809c0@lslp7o.lsl.co.uk> Message-ID: <001a01bf73c6$5b13db10$f0c809c0@lslp7o.lsl.co.uk> Ka-Ping Yee can be thought to have categorised, in part: > 1. dotted.references to classes or functions in other modules > 2. dotted.references to class methods or attributes Strangely enough, cases 1 and 2 would be the places I would consider using a "don't cross reference this" markup. But given the problems of producing a markup for the case where we *do* want to markup items (pace Eddy and me arguing about "#"), I doubt we'll ever be able to agree on the idea of having "anti-markup" (gosh, there's a concept - obviously it should be used extensively in designing the documentation scheme for INTERCAL). Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.demon.co.uk/ 2 wheels good + 2 wheels good = 4 wheels good? 3 wheels good + 2 wheels good = 5 wheels better? My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From pf@artcom-gmbh.de Thu Feb 10 12:55:16 2000 From: pf@artcom-gmbh.de (Peter Funk) Date: Thu, 10 Feb 2000 13:55:16 +0100 (MET) Subject: [Doc-SIG] Cross-reference proposal In-Reply-To: <001901bf73c2$a38ed600$f0c809c0@lslp7o.lsl.co.uk> from "Tony J Ibbs (Tibs)" at "Feb 10, 2000 12:30:39 pm" Message-ID: Hi! Tony J Ibbs (Tibs): > Ka-Ping Yee reiterated a list of possible things to autodetect: [...] > Hmm. There are two answers: > > T1. In "marked up" docstrings, none of the above should be autodetected. > I'll get into why below, but basically mark it down as "I'm paranoid" for > the moment. Question: What is difference between a "marked up" docstring and a doc string, which is not "marked up"? This must be easy to detect. Regards, Peter From Edward Welbourne Thu Feb 10 13:20:36 2000 From: Edward Welbourne (Edward Welbourne) Date: Thu, 10 Feb 2000 13:20:36 +0000 Subject: [Doc-SIG] Cross-reference proposal In-Reply-To: <001901bf73c2$a38ed600$f0c809c0@lslp7o.lsl.co.uk> References: <001901bf73c2$a38ed600$f0c809c0@lslp7o.lsl.co.uk> Message-ID: > I hope I demonstrated (elsewhere, "London") that 4 is equally > dangerous The first word of each sentence is capitalised. This can lead to further mis-fires of rule 4. > english allows acronyms with "." as well ... N.B. I.mech.eng., Ph.D., ... which all end in a dangling ., which might make them recognisable, except that legit name.attr may appear at end of sentence. Further (c.f. why I don't advocate @ for the in-text code delimiter), text may legitimately contain domain names ... which we *do* want to make subjects of hyperlinks, but the href is invented differently than if it were a dotted python identifier ... indeed, chaos.org.uk wants to be linked as http://www.chaos.org.uk/ while eddy@chaos.org.uk, naturally, should be either a mailto or (which I'd prefer, but others might not) http://www.chaos.org.uk/~eddy/. > ... #fred.spam# (to use Eddy's annotation, which I still hate) Can someone come up with a viable alternative that's less ugly ? Will North Americans have problems with using # in text as the number indicator ? [what is standard N.A. usage of # ?] Would ` . ' (a dot surrounded by space) be acceptable as a delimiter for code embedded in text ? (I don't like it, but I guess it could work ...) > Summary: ... no markup ... guess..., but ... with ... markup is *all* So, back to my earlier question: Ping, how much palaver would it take to have two ways of processing a doc-string, for the phase which decides what's code (and possibly hyperlink) and what's not: marked up -- if the doc-string appears to be using #...# for in-text code fragments, take those fragments as code (no guessing) unmarked -- if the doc-string doesn't use #...#, make Ping's educated guesses at what is code and what isn't then generate hrefs from identifiers in the code fragments thus identified ? Other hrefs may be generated other ways -- e.g. to URLs in the text -- but hrefs to python objects only get auto-generated if in a code fragment, however it has been recognised. Eddy. From pf@artcom-gmbh.de Thu Feb 10 13:14:23 2000 From: pf@artcom-gmbh.de (Peter Funk) Date: Thu, 10 Feb 2000 14:14:23 +0100 (MET) Subject: [Doc-SIG] Markup of identifiers (was: Cross-reference proposal) In-Reply-To: <001a01bf73c6$5b13db10$f0c809c0@lslp7o.lsl.co.uk> from "Tony J Ibbs (Tibs)" at "Feb 10, 2000 12:57:14 pm" Message-ID: Hi! [Tony J Ibbs (Tibs)]: > Strangely enough, cases 1 and 2 would be the places I would consider using a > "don't cross reference this" markup. But given the problems of producing a > markup for the case where we *do* want to markup items (pace Eddy and me > arguing about "#"), I doubt we'll ever be able to agree on the idea of > having "anti-markup" (gosh, there's a concept - obviously it should be used > extensively in designing the documentation scheme for INTERCAL). Several possibilities to markup (tag) identifiers in doc strings: 1. #identifier# (recent proposal here, looks ugly to me) 2. [ident identifier] (nobody here but M.Z. seems to like this kind of markup) 3. *identifier* (also used for emphsizing in StructuredText, used by the package Python Mega Widget) 4. 'identifier' (used in the gendoc sources) 5. "identifier" (I have seen this occasionally, misleading) 6. `identifier' (TeX look-alike quoting) 7. ^identifier (my personal idea, while thinking about alternatives since identifiers don't contain white space, a single markup character in front of the identifier should be enough) Are there other possibilities, which I may have missed? If not, we have simply to choose one. Regards, Peter -- Peter Funk, Oldenburger Str.86, 27777 Ganderkesee, Tel: 04222 9502 70, Fax: -60 From tony@lsl.co.uk Thu Feb 10 13:33:12 2000 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Thu, 10 Feb 2000 13:33:12 -0000 Subject: [Doc-SIG] Cross-reference proposal In-Reply-To: Message-ID: <001d01bf73cb$60648920$f0c809c0@lslp7o.lsl.co.uk> Peter Funk wrote, on 10 February 2000 12:55: > Question: What is difference between a "marked up" docstring and a doc > string, which is not "marked up"? This must be easy to detect. "must"? hmm... Answer 1: A marked up doc string is one which contains markup. This is the easy answer, but see: Answer 2: You can't tell, because you can't distinguish a doc string that *required* no markup (or so the writer decided) from one which (for instance) predates the markup scheme. In fact, I don't think it's a problem in practise. Some person decides to run the appropriate tool over a particular Python file, and I think it is reasonable to assume (for our purposes) that either all of a file (maybe even a module) shall be marked up, or none of it shall be (note the careful ISO-speak there). In that case, the person can make the decision. If Ka-Ping Yee wants to be *really* nice (and I don't regard this as a requirement!) then he could have his script warn the user that there actually *is* something that looks like markup in the text, and even (maybe) attempt to use it - but that's a whole other discussion about trade-offs (e.g., what if it *looked* like our markup but wasn't?, and should the user be able to aver "ignore any characters that look like markup"?). Etc. Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.demon.co.uk/ .. "equal" really means "in some sense the same, but maybe not .. the sense you were hoping for", or, more succinctly, "is .. confused with". (Gordon McMillan, Python list, Apr 1998) My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Thu Feb 10 13:45:24 2000 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Thu, 10 Feb 2000 13:45:24 -0000 Subject: [Doc-SIG] Markup of identifiers (was: Cross-reference proposal) In-Reply-To: Message-ID: <001e01bf73cd$15121620$f0c809c0@lslp7o.lsl.co.uk> Peter Funk wrote, on 10 February 2000 13:14 > Several possibilities to markup (tag) identifiers in doc strings: > > 1. #identifier# > 2. [ident identifier] > 3. *identifier* > 4. 'identifier' > 5. "identifier" > 6. `identifier' > 7. ^identifier I've omitted the comments. 1 is Eddy's idea - I've commented elsewhere - it works but I don't like the look either (but it might still be the best solution). 2 is too verbose (where one of the sister threads to this started!). The simpler [identifier] variant was proposed in the earlier round of talks, and is my favourite, but suffers from the "Eddy objection" - that "[" and "]" are too valuable/used too much in Python to be reserved for this purpose (I *think* that's the problem). 3 can't be used because it already is (emphasis) - firstly someone might want to emphasise a cross reference (for example, me), and secondly you can't actually *distinguish* a cross reference from plain text automatically anyway (see the other thread) 4 and 5 both use quotes, which must suffer the "Eddy objection" (see 2), but also I don't think you can force people to choose quote styles in doc strings. 6 won't fly because "`" (that first quote char) is not in ISO 646 (or ASCII if you prefer) and I don't think it's a good idea to *require* non-646 text in doc strings (also, it's paired with "'", which is a valid character for other purposes, so that doesn't work well - yu'd get confusion over what the "'" was doing, I think). 7 would need a terminator, and can suffer the "Eddy problem". Personally I like [reference], but I'm comfortably expecting this to be solved by someone else in the implementation we eventually see (which I'm not writing, you note) and I'll use their choice... Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.demon.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From tony@lsl.co.uk Thu Feb 10 13:56:31 2000 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Thu, 10 Feb 2000 13:56:31 -0000 Subject: [Doc-SIG] Cross-reference proposal In-Reply-To: Message-ID: <002001bf73ce$a264de80$f0c809c0@lslp7o.lsl.co.uk> Edward Welbourne wrote (I'm giving up including the date, since Outlook ain't helping me and I'm not sure anyone cares): > Would ` . ' (a dot surrounded by space) be acceptable as a delimiter for > code embedded in text ? (I don't like it, but I guess it could work ...) No. (do I need explanations? do I *have* explanations? well, *I* wouldn't be able to visually parse it - I prefer Eddy's "#"!) > So, back to my earlier question: Ping, how much palaver would it take to > have two ways of processing a doc-string, for the phase which decides > what's code (and possibly hyperlink) and what's not: > > marked up -- if the doc-string appears to be using #...# for in-text > code fragments, take those fragments as code (no guessing) > > unmarked -- if the doc-string doesn't use #...#, make Ping's educated > guesses at what is code and what isn't > > then generate hrefs from identifiers in the code fragments thus > identified ? Other hrefs may be generated other ways -- e.g. to URLs in > the text -- but hrefs to python objects only get auto-generated if in a > code fragment, however it has been recognised. As I've said in a reply to Peter Funk elsewhere, I think you *can't* guess if a doc string is not marked up because it (deliberately) wasn't, or because it (for instance) predates markup. So I think the choices have to be: i. doc string is clearly marked up (I'll concede detecting that for practical purposes, for some value of "clearly"), and there are #...# (or whatever). ii. doc string is clearly marked up, but there are no #...#? How do you tell if they just didn't *want* any cross references? iii. doc string clearly isn't marked up (for values of "clearly" as defined above, or perhaps their inverse!). In case i you can obviously use the cross references, and must not generate new ones. In case ii, I think there should be an option to the processor (e.g., -force_xref) which forces generation of cross references if the user believes they have "obviously" been omitted. But it needs a human to tell. In case iii, I'd prefer an option to tell the processor about the (probably infrequent) cases where the absence of markup was deliberate (e.g., -absent_xref). But in practice, I might have to live with the markup getting generated regardless - so could I have a pragma to say "this doc string contains no markup" please? (ouch) Tibs, getting tangled in conditional clauses -- Tony J Ibbs (Tibs) http://www.tibsnjoan.demon.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From irmina@ctv.es Sun Feb 13 11:53:36 2000 From: irmina@ctv.es (Manuel Gutierrez Algaba) Date: Sun, 13 Feb 2000 11:53:36 +0000 (GMT) Subject: [Doc-SIG] MiniBloquiHeader Message-ID: I've just released MiniBloquiHeader http://www.ctv.es/USERS/irmina/Mini/MiniBloquiHeader.html very interesting for anybody that writes doc y TeX/LaTeX Regards/Saludos Manolo www.ctv.es/USERS/irmina /TeEncontreX.html /texpython.htm /pyttex.htm I'm going to live forever, or die trying! -- Spider Robinson From fdrake@acm.org Mon Feb 14 20:03:09 2000 From: fdrake@acm.org (Fred L. Drake, Jr.) Date: Mon, 14 Feb 2000 15:03:09 -0500 (EST) Subject: [Doc-SIG] Documentation patches Message-ID: <14504.24445.524107.655533@weyr.cnri.reston.va.us> I've just updated the page at python.org/patches/ to ask that documentation patches be sent to python-docs@python.org, with specific bug reports to be submitted through the bugs database (which I monitor). Hopefully this will clarify what should happen for documentation issues. It also means that the published documentation on the Web site isn't out of date! -Fred -- Fred L. Drake, Jr. Corporation for National Research Initiatives From laurie@eh.org Tue Feb 22 22:41:10 2000 From: laurie@eh.org (Laurence Tratt) Date: Tue, 22 Feb 2000 22:41:10 +0000 Subject: [Doc-SIG] Crystal 0.1 Message-ID: <38B31086.F14FFB0A@eh.org> I'd like to make a sort of low key announcement about a very early version of a new tool in the gendoc/pythondoc/javadoc mould. It's called Crystal and 0.1 is the first public version. I have been creating this system as part of my final year undergraduate project, so at the moment it's subject to whatever license my university wants to put on it. This first version is *very* rough, not very ready and has much unimplemented, much buggy etc. There is no documentation. There's no guaranteed support (but I'll try). If you're still not put off, here are some things worth noting: * Has plugin support for different languages, different doc string styles and different output formats (Currently only Python, StructuredText & HTML3 implemented though) * Flexible output (using a built in page layout language) * Good quality output (needs some work though) * Parses rather than imports .py files Here are some less good things worth noting: * StructuredText is *not* implemented using Jim Fulton's module, was only implemented today, and may be very weird * No indices yet * No list of inherited methods / fields etc yet; HRefs between pages mostly lacking * Not widely tested (though it runs OKish over the standard 1.5.2 library); Crystal has only been run on a couple of Unix machines * Lots of other little things not implemented * Has a tendency to show up Netscape 4.x tables limitations * Uses CPython parser interface; may not work under other Python implementations The download URL is: http://eh.org/~laurie/comp/python/crystal/ I have put up a few demonstration pages (including a file or two from the standard Python library as a point of comparison) on the web site to give people a vague idea of what Crystal does. I'm making this release because although this is early days, this might still be useful to some people; at the least, it's got some ideas which I don't think are seen in any other such tools, and so it might be useful to people doing the same sort of thing. Installation is currently a simple decompress. Crystal makes use of SPARK, and my thanks to John Aycock for that brilliant little package. If anyone has any comments, please feel free to mail me (or discuss it on the doc-sig), and happy documentation creating! Laurie From dgoodger@bigfoot.com Wed Feb 23 21:45:54 2000 From: dgoodger@bigfoot.com (David Goodger) Date: Wed, 23 Feb 2000 16:45:54 -0500 Subject: [Doc-SIG] pythondoc on mac; multi-platform file names Message-ID: I am attempting to use Daniel Larsson's pythondoc (http://starship.python.net/crew/danilo/pythondoc/) on MacOS, and am running into trouble. Pythondoc wants to create files with names like 'module.class.html'. When the total is over 31 characters (Mac's filename length limit), pythondoc fails. I could hack the code to make it work, but I'd rather do something general which could be included in the next release. Also, there are inter-file cross references to consider. 1. Has anyone else successfully used pythondoc on MacOS, perhaps with modifications? If so, I'd like to see any modifications, or at least hear how you got around the OS problems. 2. Is there a general-purpose file naming utility module for Python which gets around the limitations of various operating systems? Perhaps something that checks the validity of a name, or creates a unique name (for a specified directory) based on the input. Mac files can have spaces & puntuation (except colon ':') in their names, but are limited to 31 characters. DOS (does anyone still use DOS? :-) is 8.3. Unix & Windows have their own (hard or soft) rules. I like Python for its multi-platform capabilities (among many other aspects). This type of utility would make multi-platform programming that much easier. Thanks. -- David Goodger dgoodger@bigfoot.com From gward@python.net Thu Feb 24 03:30:18 2000 From: gward@python.net (Greg Ward) Date: Wed, 23 Feb 2000 22:30:18 -0500 Subject: [Doc-SIG] Documentation: "Installing Python Modules" Message-ID: <20000223223018.A3646@beelzebub> Hi all -- well, I finally sat down and started spewing Distutils documentation. My plan is to write two howto-style manuals (maybe a bit bigger than "Documenting Python", but along those lines) to be included in the 1.6 manual set. (Clever of me to announce this intention in public before mentioning it to Fred or Guido, just to make it harder for them to tell me to get stuffed. ;-) The two manuals are tentatively entitled: Installing Python Modules Distributing Python Modules So far, I have written one section of the "Installing" manual, entitled "Custom Installation (Unix)". This one is kind of important: it explains how to use the Distutils to install modules to any non-standard place, with lots of commentary on good practices and multi-platform installations. I want feedback on this on several axes: * Distutils terminology: eg. does "install-lib" mean what you think it should mean, or do you have a better idea? * Distutils semantics: eg. is the behaviour of "install-lib" sensible? * documentation organization * documentation wording * spelling, typos, typesetting, etc. The docs are available at http://www.python.org/sigs/distutils-sig/documentation.html Currently only LaTeX source and PDF available -- HTML soon. -- Greg Ward - programmer-at-large gward@python.net http://starship.python.net/~gward/ If it can't be expressed in figures, it is not science--it is opinion. From laurie@eh.org Thu Feb 24 22:44:24 2000 From: laurie@eh.org (Laurence Tratt) Date: Thu, 24 Feb 2000 22:44:24 +0000 Subject: [Doc-SIG] Crystal 0.2 Message-ID: <38B5B448.68988E7D@eh.org> Sorry for all those of you who may have experienced problems downloading Crystal 0.1; I'd completely forgotten that the web server it's on has a tendency to distribute .gz files as plain text with all the problems that that causes. Therefore to make up I'm making available Crystal 0.2 (24 February 1999) which is distributed in .zip format (as a temporary fix) and contains a few new things including indices. Crystal can be downloaded from: http://eh.org/~laurie/comp/python/crystal/ I have also updated the sample output on the webpage to give people a better idea of what Crystal can do. If you thought that automatically created Python module/packge documentation had to be ugly, hopefully the sample output can go some way to persuading you it can be functional and fairly pretty! For those of you wondering *what* Crystal is, it is a tool in the javadoc/pythondoc vein (with quite a lot of extra features on top of those two tools). Although in its very early stages, it is already capable of useful work as evidenced by the sample output on the webpage. Laurie From fdrake@acm.org Mon Feb 28 20:37:27 2000 From: fdrake@acm.org (Fred L. Drake, Jr.) Date: Mon, 28 Feb 2000 15:37:27 -0500 (EST) Subject: [Doc-SIG] Forthcoming doc release; request for help Message-ID: <14522.56455.195782.528453@weyr.cnri.reston.va.us> Yes, the rumors are true: I'm planning to release the documentation for Python 1.5.2 one more time. The current target date is 17 March. Here's my planned schedule for short-term activity: Feb 29: Release documentation packages to Doc-SIG for review Mar 17: Release documentation version 1.5.2p2 (last 1.5.2 release) Apr 17: Finish merging 1.5.2p2 into documentation for 1.6 There are a couple of things I'd like help with. ;) First, I try to go throught the HTML version every so often using major browsers on major platforms. I *don't* have access to all platforms, though, and just don't have time to test for each major browser for each platform, and that's only gotten worse the last couple of releases. Second, I haven't been able to "close-read" the documentation for a long time; this is valuable to catch confusing passages, the random typo, and effects of whitespace-gobbling nanoviruses. Catching statements that are just plain wrong is also an important goal. Clearly, the second goal can be met while meeting the first goal; if you shoot for the second, the first falls out, at least for one browser/platform combination, but it requires a more substantial time commitment than browser-testing the HTML. I've often used a printed version for the close-reading instead of using the HTML. What I'm doing is asking for volunteers to help; with enough eyes, the work is highly partionable. If each of us picks one or more documents (the library reference can be partitioned by chapter) and a particular browser/platform combo, this shouldn't be too hard. I'd like to hit at least the following browser/platform combinations: MSIE 5.0 Windows, MacOS(?) Navigator 4.x Windows, MacOS, Unix Opera Windows, MacOS(?), Linux Mozilla M13 Windows, MacOS, Unix (I haven't been able to run the M13 binary for Solaris 2.6 on my 2.7 box; has anyone succeeded at this? The M12 runs OK... for a little while. I've not yet checked M13 for other platforms.) Could someone with a MacOS box please check that all the filenames, at least for the generated HTML, aren't too long or otherwise cause problems with HFS? Thanks! I can coordinate as well as do a portion of the work; who'll volunteer? -Fred -- Fred L. Drake, Jr. Corporation for National Research Initiatives From ping@lfw.org Mon Feb 28 20:46:10 2000 From: ping@lfw.org (Ka-Ping Yee) Date: Mon, 28 Feb 2000 14:46:10 -0600 (CST) Subject: [Doc-SIG] Forthcoming doc release; request for help In-Reply-To: <14522.56455.195782.528453@weyr.cnri.reston.va.us> Message-ID: On Mon, 28 Feb 2000, Fred L. Drake, Jr. wrote: > What I'm doing is asking for volunteers to help; with enough eyes, > the work is highly partionable. If each of us picks one or more > documents (the library reference can be partitioned by chapter) and a > particular browser/platform combo, this shouldn't be too hard. Okay, post some URLs... i have Navigator 3 and 4 on Irix and Linux. > I'd like to hit at least the following browser/platform > combinations: > > MSIE 5.0 Windows, MacOS(?) > Navigator 4.x Windows, MacOS, Unix > Opera Windows, MacOS(?), Linux > Mozilla M13 Windows, MacOS, Unix Is Mozilla even worth it? I've downloaded two or three releases and never had it stay up for more than a couple of minutes even on ordinary pages, or on its own included test pages. -- ?!ng From fdrake@acm.org Mon Feb 28 23:18:46 2000 From: fdrake@acm.org (Fred L. Drake, Jr.) Date: Mon, 28 Feb 2000 18:18:46 -0500 (EST) Subject: [Doc-SIG] Forthcoming doc release; request for help In-Reply-To: References: <14522.56455.195782.528453@weyr.cnri.reston.va.us> Message-ID: <14523.599.24651.207764@weyr.cnri.reston.va.us> Ka-Ping Yee writes: > Okay, post some URLs... i have Navigator 3 and 4 on Irix and Linux. I've dropped tarballs at: ftp://ftp.python.org/pub/python/doc/.test/ Online versions are available at: http://www.python.org/doc/1.5.2p2/ (not yet linked to from anywhere). > Is Mozilla even worth it? I've downloaded two or three releases > and never had it stay up for more than a couple of minutes even > on ordinary pages, or on its own included test pages. I tried M12 on Solaris, Linux, and Windows, and it mostly worked OK (HTML widget portion of the display), aside from some weirdness on Solaris, and generally leaking like a sieve. I still haven't played with M13 on Linux or Windows. It still seems slow, but that's probably an issue of the application code rather than the renderer (feels snappy); I suspect they're not caching network resources, or have a bug in that. I'm not so concerned about Mozilla now as six months from now; they *are* becoming much more stable & capable. I don't want to feel I need to do another release simply because they've fixed the usability issues related to their interface. But I've not intention of holding anything up for Mozilla either. -Fred -- Fred L. Drake, Jr. Corporation for National Research Initiatives From willguaraldi@mediaone.net Tue Feb 29 10:22:11 2000 From: willguaraldi@mediaone.net (will) Date: Tue, 29 Feb 2000 05:22:11 -0500 Subject: [Doc-SIG] Forthcoming doc release; request for help In-Reply-To: <14523.599.24651.207764@weyr.cnri.reston.va.us> Message-ID: how do you want us to relate "errors" back to you? directly, or on this list, or on another list, or bug-tracker? i've been programming python for a while, but i would just gloss over subtle python inconsistencies. so i'll stare through the html code, run it through the w3c validator (they do matching of tags and such which is useful), and tell my friends to sift through it with their browsers. (i know various folks at companies that do web-sites so they have a lot of the browser/os/platform test-beds, i think). i can get a more extensive listing of browser/os/platform combinations that i'm checking soonish. it'll likely be versions of Netscape and IE on Mac and Windows and Linux platforms (where applicable). beyond that, i'm running IE 5.0 on WinNT 4.0 and Win2000 and M13 on WinNT 4.0 (which i haven't had that many problems with other than the ui). i've found a few problems with the code posted at the url. lines 267 and 276 of .../lib/typesseq-strings.html have stray unmatched and tags. looking at the web-page (not the html), it's in section 2.1.5.2 Mutabe Sequence Types in the table. you can actually see two of the parens are in a var enclosure and shouldn't be. 9th and 12th row, first column in the table under 2.1.5.2. also links on the modules and index pages turn up 404's. i may untar the tarball and see if i have the same problems. /will > -----Original Message----- > > Ka-Ping Yee writes: > > Okay, post some URLs... i have Navigator 3 and 4 on Irix > and Linux. > > I've dropped tarballs at: > > ftp://ftp.python.org/pub/python/doc/.test/ > > Online versions are available at: > > http://www.python.org/doc/1.5.2p2/ > > (not yet linked to from anywhere). > > > Is Mozilla even worth it? I've downloaded two or three releases > > and never had it stay up for more than a couple of minutes even > > on ordinary pages, or on its own included test pages. > > I tried M12 on Solaris, Linux, and Windows, and it mostly > worked OK > (HTML widget portion of the display), aside from some weirdness on > Solaris, and generally leaking like a sieve. I still haven't played > with M13 on Linux or Windows. It still seems slow, but that's > probably an issue of the application code rather than the renderer > (feels snappy); I suspect they're not caching network resources, or > have a bug in that. > I'm not so concerned about Mozilla now as six months from > now; they > *are* becoming much more stable & capable. I don't want to feel I > need to do another release simply because they've fixed the > usability > issues related to their interface. > But I've not intention of holding anything up for Mozilla either. > > > -Fred > > -- > Fred L. Drake, Jr. > Corporation for National Research Initiatives > > _______________________________________________ > Doc-SIG maillist - Doc-SIG@python.org > http://www.python.org/mailman/listinfo/doc-sig