structuredtext-develop Mailing List for reStructuredText (Page 2)
Status: Pre-Alpha
Brought to you by:
goodger
You can subscribe to this list here.
2001 |
Jan
|
Feb
|
Mar
|
Apr
|
May
|
Jun
|
Jul
(20) |
Aug
(21) |
Sep
(6) |
Oct
|
Nov
(1) |
Dec
|
---|---|---|---|---|---|---|---|---|---|---|---|---|
2002 |
Jan
|
Feb
(25) |
Mar
(7) |
Apr
(8) |
May
|
Jun
|
Jul
|
Aug
|
Sep
|
Oct
|
Nov
|
Dec
|
From: David G. <go...@us...> - 2002-02-21 01:55:44
|
Richard Jones wrote: > I'm trying to insert some biblio fields into a document and handle them > specially in the HTML writer. Trouble is, I can't get the parser to spit out > the docinfo DOM element. ... > You'll notice that I'm getting a field_list element, not a docinfo element. ... > Also, the "document" element is defined as having an optional subtitle:: > > ... but I can't seem to get it to generate one of those either. I tried by > just putting a different level title under the first title, and it just > generated another section like any other. These are further examples of transforms that need to be done. The parser alone cannot finish the job. Sometimes, such as with docstrings, we *don't want* the parser to finish the job. > Am I just reading the DOM and documentation incorrectly? It's there, in pieces; maybe you missed them. Here's one piece: Specifically, there is no way to specify a document title and subtitle explicitly in reStructuredText. Instead, a lone top-level section title (see Sections_ below) can be treated as the document title. Similarly, a lone second-level section title immediately after the "document title" can become the document subtitle. See the `DocTitle transform`_ for details. .. _transforms: http://docstring.sourceforge.net/dps/transforms/__init__.py .. _DocTitle transform: .. _DocInfo transform: http://docstring.sourceforge.net/dps/transforms/frontmatter.py (reStructuredText.txt: Syntax Details: Document Structure: Document) The last sentence is the bit you're missing. The docs are in the module docstrings. Trace how restructuredtext/tools/publish.py & html.py do their work, and you'll see what's missing. -- David Goodger go...@us... Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net |
From: David G. <go...@us...> - 2002-02-21 01:29:19
|
Sorry, I meant to send this yesterday. For some reason, it didn't go through. Richard Jones wrote: > ps. 90% of the html formatter is done - biblio and some reference stuff still > to be done. I'm also going to assume from the terminology above that the > formatter should be renamed "HTMLWriter"? Actually, it should conform to the (not yet finalized) dps.writers.Writer interface. I'm working on a dps.writers.html.Writer, which I'll check in so you can see what I'm thinking. It walks the doctree using dps.nodes.NodeVisitor. I'll check in your code into sandbox/richardj and give you access (maybe tonight, maybe tomorrow, I'll let you know). It doesn't take into account all the transforms that need to be performed on the raw doctree. Take a look at dps.core.Publisher (used by restructuredtext/tools/publish.py and html.py) to see what I mean. -- David Goodger go...@us... Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net |
From: Richard J. <rj...@ek...> - 2002-02-20 23:55:50
|
I'm trying to insert some biblio fields into a document and handle them specially in the HTML writer. Trouble is, I can't get the parser to spit out the docinfo DOM element. The following at the top of a document:: =============================================================== Roundup: An Issue-Tracking System for Knowledge Workers =============================================================== :Authors: - Richard Jones, ekit, rj...@ek... - Englebert Gruber :Version: 0.4.1 results in:: <document> <section name="roundup: an issue- ... snip ... workers"> <title> Roundup: An Issue-Tracking System for Knowledge Workers <field_list> <field> <field_name> Authors <field_body> <bullet_list bullet="-"> <list_item> <paragraph> Richard Jones, ekit, <reference refuri="mailto:rj...@ek..."> rj...@ek... <list_item> <paragraph> Englebert Gruber <field> <field_name> Version <field_body> <paragraph> 0.4.1 You'll notice that I'm getting a field_list element, not a docinfo element. Am I just reading the DOM and documentation incorrectly? Also, the "document" element is defined as having an optional subtitle:: ((title, subtitle?)?, docinfo?, %structure.model;) ... but I can't seem to get it to generate one of those either. I tried by just putting a different level title under the first title, and it just generated another section like any other. Richard |
From: David G. <go...@us...> - 2002-02-20 03:58:36
|
Richard Jones wrote: > I believe it's up to the original source - which knows how the program > accepts arguments - to determine whether an '=' is required, not the output > writer. Assuming that all programs that accept long arguments must use '=' is > dangerous. For the purposes of the reStructuredText parser, I think the tighter the rules are, the better. I'm tempted to tighten the rules even further, to avoid ambiguity. I'll spell it out in the spec, that the syntax rules for short and long POSIX options are based on what's acceptable to getopt.py. As Alan pointed out, there's a lot of variation in option syntax out there. So much variation that it's virtually if not absolutely impossible to support it all. I've no desire to support all the wonky variations out there. >>> 3. short options can't have '=' arguments: >>> >>> -DC_DEFINE_FLAG=value >>> >>> results in an error. I'll add a test case for this, and make sure the result is sane. It should just produce a paragraph, since it doesn't fit reStructuredText's definition of an option. The only error I'd expect would be from having a paragraph immediately following an option list with no blank line between. > The above is a fairly standard define argument for a C compiler. For example: > > -DHAVE_CONFIG_H > -DPREFIX='"$(prefix)"' > > Is used all over the place in autoconf-generate Makefiles. In the above, the > -D is the option, the rest of the text is the option argument. In other words, it's a short option (-D) with a complex argument? That's not a problem. The documented option list would look something like:: -D DEF Process as if '#define DEF' exists at the head of the source code. Don't forget, an option list is documentation, not actual usage. The '-LONG' style (single hyphen with a long option name) is not supported by getopt.py, so we won't support it either. GNU libc getopt_long_only() does support such options but only by using an algorithm that can break down and produce erroneous results. We won't. -- David Goodger go...@us... Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net |
From: David G. <go...@us...> - 2002-02-20 03:44:29
|
> Read the documentation for Perl's Getopt::Long to get a sense of how many > different styles of option parsing there are in common use - it's rather > depressing. Perhaps I will, one day when I'm too happy and need bringing down. ;-) > (Getopt::Long, in the Perl fashion, supports all of them.) Perl is the "everthing *including* the kitchen sink" language, so I'm not surprised. I think it behooves us to choose a self-consistent subset and stick with it, and getopt.py's choices seem just fine to me. -- David Goodger go...@us... Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net |
From: Richard J. <rj...@ek...> - 2002-02-20 02:38:12
|
On Wed, 20 Feb 2002 12:42, David Goodger wrote: > Richard Jones wrote: > > 1. the leading dashes are removed from the short_option and long_option. > > Is this intentional? If so, I'll re-add the dashes, but it seems odd. > > Yes, it's intentional. The various option types are uniformly represented > in the tree. Once the options have been parsed into "long_option" or > "short_option" elements, the dashes are implicit; they're boilerplate text, > redundant and uninteresting. It's text to be inserted by the Writer. OK. > > 2. similarly, the arguments lose the '='. > > "=" are lost for the same reason: redundancy. The back-end Writer may > choose to always use "--option=arg" or always use "--option arg", but it > should be consistent. > > > This becomes ambiguous: > > I don't see the ambiguity. Please explain. I believe it's up to the original source - which knows how the program accepts arguments - to determine whether an '=' is required, not the output writer. Assuming that all programs that accept long arguments must use '=' is dangerous. > > 3. short options can't have '=' arguments: > > > > -DC_DEFINE_FLAG=value > > > > results in an error. > > Correct. Short options never have '=' (not on any system I've seen, > anyhow). Short option names are never more than one letter long, either -- > that's why they're short! Your example is actually equivalent to:: The above is a fairly standard define argument for a C compiler. For example: -DHAVE_CONFIG_H -DPREFIX='"$(prefix)"' Is used all over the place in autoconf-generate Makefiles. In the above, the -D is the option, the rest of the text is the option argument. > > 4. any chance of a format like: > > > > -i / --info get information > > I chose ", " as the separator from observation of the "--help" output of > various tools. I don't see the need for two ways to spell it. Also, "/" is > used for VMS/DOS-style options, so it may be confusing here. OK, and it's documented, so I'm happy. Sorry I didn't notice that in the spec. Richard ps. 90% of the html formatter is done - biblio and some reference stuff still to be done. I'm also going to assume from the terminology above that the formatter should be renamed "HTMLWriter"? |
From: Alan J. <ja...@po...> - 2002-02-20 01:59:03
|
On Tue, 19 Feb 2002, David Goodger wrote: > Yes, it's intentional. The various option types are uniformly represented in > the tree. Once the options have been parsed into "long_option" or > "short_option" elements, the dashes are implicit; they're boilerplate text, > redundant and uninteresting. It's text to be inserted by the Writer. > [...] > The option list syntax is based on common practice in command-line tools > such as GNU utilities, and on the command-line parsers that they use, such > as getopt.py and Optik. Unfortunately this is not at all ubiquitous. ImageMagick, to cite the first example that comes to mind, uses long options with one dash and won't accept two dashes. Many standard X utilities use long options prefixed with either a single dash or a single plus. ps and tar are worlds of their own. Read the documentation for Perl's Getopt::Long to get a sense of how many different styles of option parsing there are in common use - it's rather depressing. (Getopt::Long, in the Perl fashion, supports all of them.) Alan |
From: David G. <go...@us...> - 2002-02-20 01:39:58
|
Richard Jones wrote: > 1. the leading dashes are removed from the short_option and long_option. Is > this intentional? If so, I'll re-add the dashes, but it seems odd. Yes, it's intentional. The various option types are uniformly represented in the tree. Once the options have been parsed into "long_option" or "short_option" elements, the dashes are implicit; they're boilerplate text, redundant and uninteresting. It's text to be inserted by the Writer. > 2. similarly, the arguments lose the '='. "=" are lost for the same reason: redundancy. The back-end Writer may choose to always use "--option=arg" or always use "--option arg", but it should be consistent. > This becomes ambiguous: I don't see the ambiguity. Please explain. > 3. short options can't have '=' arguments: > > -DC_DEFINE_FLAG=value > > results in an error. Correct. Short options never have '=' (not on any system I've seen, anyhow). Short option names are never more than one letter long, either -- that's why they're short! Your example is actually equivalent to:: -D C_DEFINE_FLAG=value While this may be valid as an actual option (i.e., as entered on the command line), it doesn't make sense as a placeholder. The option list syntax is based on common practice in command-line tools such as GNU utilities, and on the command-line parsers that they use, such as getopt.py and Optik. > 4. any chance of a format like: > > -i / --info get information I chose ", " as the separator from observation of the "--help" output of various tools. I don't see the need for two ways to spell it. Also, "/" is used for VMS/DOS-style options, so it may be confusing here. -- David Goodger go...@us... Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net |
From: Richard J. <rj...@ek...> - 2002-02-19 22:51:42
|
I'm working through more of the html formatter, and have come across some option list strangenesses: 1. the leading dashes are removed from the short_option and long_option. Is this intentional? If so, I'll re-add the dashes, but it seems odd. 2. similarly, the arguments lose the '='. This becomes ambiguous: --foo=bar blah blah blah -u flebble tblah blahb asadf results in: <option_list> <option_list_item> <option> <long_option> foo <option_argument> bar <description> <paragraph> the description of foo <option_list_item> <option> <short_option> u <option_argument> flebble <description> <paragraph> the description of u 3. short options can't have '=' arguments: -DC_DEFINE_FLAG=value results in an error. 4. any chance of a format like: -i / --info get information being acceptable too? I've seen that around a bit. Richard |
From: David G. <go...@us...> - 2002-02-19 04:29:26
|
Richard Jones wrote: > At the moment, I assume that there's always going to be a "term" > and "definition" For the final word, see http://docstring.sourceforge.net/spec/gpdi.dtd. If the DOM-ish tree produced by the parser doesn't conform to the DTD (with possible exceptions from directives), it's a bug. -- David Goodger go...@us... Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net |
From: Richard J. <rj...@ek...> - 2002-02-19 04:04:31
|
On Tue, 19 Feb 2002 14:59, David Goodger wrote: > Richard Jones wrote: > > At the moment, the term, classifier and definition are all on equal > > footing, when it seems to me that the term and classifier are quite > > closely related. > > The classic definition list has (term, definition) pairs. I added the > optional "classifier" for compatibility with Grouch. I could have redefined > "term" as (term_text, classifier?), but that would introduce an extra layer > that wouldn't be needed most of the time. You could also think of the > classifier as a formal part of the definition, like the pronunciation or > parts of speech (noun, verb, etc.) bits in a dictionary entry. It just > happens to be on the same line as the term. A matter of perception, > methinks. OK, that's fair - so it's really a matter of formatting. The "classifier" could just go in with the "definition" (but in a different style), if one was so inclined. > > This has mostly come about because I'm having to do nastinesses in the > > html formatter to handle the classifier in the term handler (ie. I open a > > <dt> but I don't close it immediately just in case there's a > > classifier... yecch) > > Such are the joys of tree transforms! This is a trivial one though. > Suggestion: when you encounter a "definition_list_item", check its > children. Or have "term" check its next sibling. Yeah, that's probably what I'm going to have to do. At the moment, I assume that there's always going to be a "term" and "definition", so I leave the tag started in the "term" hanging until the "definition" so if there's an intervening "classifier" all will be OK. Better logic will be added "later" :) Richard |
From: David G. <go...@us...> - 2002-02-19 03:57:25
|
Richard Jones wrote: > ...it occurs to me that definition_list classifier should be more closely > related to the term. ... > At the moment, the term, classifier and definition are all on equal footing, > when it seems to me that the term and classifier are quite closely related. The classic definition list has (term, definition) pairs. I added the optional "classifier" for compatibility with Grouch. I could have redefined "term" as (term_text, classifier?), but that would introduce an extra layer that wouldn't be needed most of the time. You could also think of the classifier as a formal part of the definition, like the pronunciation or parts of speech (noun, verb, etc.) bits in a dictionary entry. It just happens to be on the same line as the term. A matter of perception, methinks. > This has mostly come about because I'm having to do nastinesses in the html > formatter to handle the classifier in the term handler (ie. I open a <dt> but > I don't close it immediately just in case there's a classifier... yecch) Such are the joys of tree transforms! This is a trivial one though. Suggestion: when you encounter a "definition_list_item", check its children. Or have "term" check its next sibling. > Of course I might be completely out of line, but this is how I see it :) All input welcome. > ps. note also the typo in the diagram "defninition" ;) Noted, thanks. -- David Goodger go...@us... Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net |
From: David G. <go...@us...> - 2002-02-19 03:32:17
|
Richard Jones wrote: > I've just whacked together a very basic HTML formatter. ... > Anyone interested? Yes, I'd like to see your code. Please post a patch to SourceForge or send it to me. I'm working (very slowly) on an HTML formatter as well, so either I'll incorporate it into my code or put it in the sandbox so others can see it. -- David Goodger go...@us... Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net |
From: Richard J. <rj...@ek...> - 2002-02-19 00:14:11
|
I'm just working through http://structuredtext.sourceforge.net/spec/reStructuredText.txt and it occurs to me that definition_list classifier should be more closely related to the term. The diagram from that document: +---------------------------+ | term [ " : " classifier ] | +--+------------------------+--+ | defninition | | (body elements)+ | +---------------------------+ implies to me that it should be - and structurally it will be. Either that or there needs to be another higher-level DOM construct like definition_label or something that encompasses the term and classifier. At the moment, the term, classifier and definition are all on equal footing, when it seems to me that the term and classifier are quite closely related. This has mostly come about because I'm having to do nastinesses in the html formatter to handle the classifier in the term handler (ie. I open a <dt> but I don't close it immediately just in case there's a classifier... yecch) Of course I might be completely out of line, but this is how I see it :) Richard ps. note also the typo in the diagram "defninition" ;) |
From: Richard J. <rj...@ek...> - 2002-02-18 23:45:19
|
I've just whacked together a very basic HTML formatter. I write standard, unadulterated HTML tags (except the system message, which defines a <span class>) with the prettification expected to be done using CSS. Anyone interested? I had trouble finding out what all the elements were that I needed to support. I'm still not sure I handle them all. I'm pretty sure this means I missed something obvious somewhere though :) Richard |
From: Alan J. <ja...@po...> - 2001-11-11 15:22:37
|
Text::Restructured ================== I wrote a simple `Perl module`_ interface to the reStructuredText parser:: focus% echo '**reStructuredText**: Not just for reptiles anymore!' | perl -MText::Restructured -e 'undef $/; print Text::Restructured->new->html(<>);' <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd"> <html> <head> <meta content="text/html; charset=UTF-8" http-equiv="Content-Type"> <title></title> </head> <body><p> <strong>reStructuredText</strong>: Not just for reptiles anymore!</p></body> </html> It requires reStructuredText and Inline::Python, and the HTML output method currently requires XML::LibXSLT. The `Perl module`_ and `documentation`_ are on my website. .. _Perl module: http://pobox.com/~jaffray/rst/Text-Restructured.tgz .. _documentation: http://pobox.com/~jaffray/rst/Text-Restructured.pod.html |
From: Tony J I. (Tibs) <to...@ls...> - 2001-09-28 10:05:56
|
David Goodger wrote: > > * VMS allows switches to take arguments, using an "=" sign (I *seem* > > to rememeber that a colon may work as well, but this is less usual). Hmm - I'd ignore that last, since I think it may be a holdover from PDPs (I'm afraid I remember when VMS was a thin shell over RSX-11), and thus a compatibility issue. > > DOS seems to work the same way, with "=" and ":" being equivalent, > > except that whitespace is not, I believe, allowed... > > Could you confirm this? It will be easy enough to support all these > variants, but I'd like to get it right. Hmm. OK, looking up my old copy of VMS General User's Manual (April 1988! - but some things don't change), the command line format is:: [$] [label:] command [/qualifier[=value]...] [parameter[/qualifier...]] "qualifier" is what one might call "switch", and "parameter" is "argument". Note that on VMS is it possible to specify that a qualifier in one position has a different effect than the same qualifier in a different position (VMS provides a (compiled) macro language for specifiying such things). So in:: $ PRINT/COPIES=5 LAUNDRY.LIS the "$" is the prompt, "PRINT" is the comand, "/COPIES" the qualifier, with value 5, and "LAUNDRY.LIS" the parameter. Upper and lowercase are equivalent (or, more precisely, lower case is translated to upper case), except when enclosed in quotation marks in paramater and paramater qualifier values. Whitespace is *not* needed to separate qualifiers - the "/" serves that purpose. Typing a hyphen at the end of a line causes it to continue. There are limits on the number of elements in a line, and its absolute length (note that wildcard expansion is done by the command line library, so this is not the problem it would be/is on Unix). Ah: """You can abbreviate any command name by typing only the first four characters. You can abbreviate a command name to fewer than four characters as long as the abbreviated name remains unique among all DCL command names. """ Examples of command description: DIRECTORY [file-spec] "file-spec" is optional SHOW PRINTER device-name Commands may be composed of more than one word. DELETE file-spec[,...] Optional items occur in square brackets. COPY PLUTO.TXT,SATURN.TXT,EARTH.TXT PLANETS.TXT A list of items may be grouped together by separating them with commas (the norm) or plus marks. PRINT/COPIES=2 A.TXT,B.TXT PRINT A.TXT/COPIES=2,B.TXT Command qualifiers may be positional - the first prints two copies of each file, the second only of the first. DELETE/ENTRY=(231,231) LN03_PRINT A list of parameter values is enclosed in parentheses and separated by commas. DELETE *.*;*/AFTER=23-DEC-2000:12:00:00 DELETE *.*;*/AFTER=-5:00 The first specifies an absolute date/time, the second a relative time. Oh, and don't forget the VMS file system: DIR SYS$DISK:[FRED.1234.JIM]FILE.TXT;99 That should be more than enough information on VMS, particularly since it presumably now counts as a legacy system. DOS (and its variants) is more important, but has *much* less documentation. However, a quick Google search gives http://www.qvctc.commnet.edu/classes/csc277/syntax.html which seems to cover the basics. As to spaces around "=" marks, and other things (I've omitted "extra" blank lines for clarity, and this is on Windows/NT system):: z:\tony\>set fred = a z:\tony\>echo %fred% %fred% z:\tony\>set fred=a z:\tony\>echo %fred% a z:\tony\>set fred:a Environment variable fred:a not defined z:\tony>dir /o:n <<<directory sorted in name order>>> z:\tony\>dir /o=n <<<standard header gumph>>> File Not Found > > Discussion - literal blocks and doctest blocks > > ---------------------------------------------- Your responses were what I expected, but then I wasn't really sure I wanted them to be otherwise (whilst I think it's an issue, I don't see what other approach makes particular sense). > > Post-parse transformations > > -------------------------- > Although some transformations are parser-specific, I've > decided to put all transforms in the dps package itself > (either dps/transforms.py or a new subpackage dps/transforms/, > depending on the volume). I'd go for the subpackage, for flexibility, since I think the organisation by module makes life simpler. Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.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: David G. <go...@us...> - 2001-09-28 03:34:12
|
Tony J Ibbs (Tibs) wrote: > I was rereading (version 1.18 of) the reStructuredText markup > specification last night (which, by the way, is becoming exceedingly > excellent), and have some comments... Thank you (and, by the way, thanks!). I'm making the changes now. I'll let the changes speak for themselves; please let me know if anything needs further work. > * VMS allows switches to take arguments, using an "=" sign (I *seem* > to rememeber that a colon may work as well, but this is less usual). > > DOS seems to work the same way, with "=" and ":" being equivalent, > except that whitespace is not, I believe, allowed... Could you confirm this? It will be easy enough to support all these variants, but I'd like to get it right. > Discussion - literal blocks and doctest blocks > ---------------------------------------------- > According to :reST:`doctest blocks`_, "Indentation is not requried for > doctest blocks". This, of course, means that any indentation *present* > causes the production of an enclosing blockquote, and the resultant > indentation of the doctest block in the final result. This may be considered a feature. ;-> > Meanwhile, because indentation *is* required for literal blocks, it is > difficult to get the same effect The formatting is completely up to you. I consider HTML an entirely presentational markup; there's absolutely no requirement for any kind of correspondence between DPS elements and HTML tags. If you want to use <blockquote> to indent literal blocks, please go ahead. Doctest blocks too, if you want. (<blockquote> indents on both left & right though, so tables might be the way to go here.) > Or maybe I should just be making my Writer have an option to put a > blockquote around literals anyway... Or just make a stylistic decision one way or the other and be done with it. If somebody doesn't like it, they can make their own variation of an HTML Writer. > Post-parse transformations > -------------------------- > Yes, I like the descriptions you've already done here. Although some transformations are parser-specific, I've decided to put all transforms in the dps package itself (either dps/transforms.py or a new subpackage dps/transforms/, depending on the volume). I'm also going to put all the description (except for parser-specific stuff, which may end up being duplicated to some degree) into a new file (to incorporate your suggested text, thanks!): http://docstring.sourceforge.net/spec/transforms.txt > Favourite lines > --------------- > I like quite a bit of the document, but some lines strike me as very > nice - I'm not sure if I can explain why I find the first one funny, and > it probably isn't intended that way! > > * (please pay attention to the colons after "Paragraph") Not *intended* to be funny. Glad you enjoyed it though. > * Only those who understand the escaping and inline markup > rules may attempt the remaining 1% This one *is* a weak attempt at humour. Thanks again for the input! -- David Goodger go...@us... Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net |
From: Tony J I. (Tibs) <to...@ls...> - 2001-09-27 10:58:33
|
I was rereading (version 1.18 of) the reStructuredText markup specification last night (which, by the way, is becoming exceedingly excellent), and have some comments... .. linksto:: reST = reStructuredText.txt In :reST:`definition lists`_ it might be worth adding a note explaining (broadly) why "classifier" exists. In :reST:`option lists`_ VMS options, I would note that: * VMS switches are generally a "word", which may be shortened as much as the user likes, provided it is not ambiguous, and regardless must be unambiguous in 4 characters. So /directory can always be shortened to /dire, and *may* be able to go down as far as /d. If I had to represent such a thing, I might write it as:: /DIR[ECTORY] On DOS/Windows, this is obviously not so relevant, but it is not uncommon to have multi-letter arguments. (Someone from a VMS background doesn't understand the Unix urge to avoid typing so aggressively!) * VMS doesn't distinguish upper and lower case. Neither does DOS. On VMS is it conventional to use upper case to describe switches. * VMS allows switches to take arguments, using an "=" sign (I *seem* to rememeber that a colon may work as well, but this is less usual). DOS seems to work the same way, with "=" and ":" being equivalent, except that whitespace is not, I believe, allowed... Thus my example above now becomes:: /DIR[ECTORY] = path -- VMS example /DIR[ECTORY]=path -- DOS example The argument can actually be more complex than that on VMS - things like /OPTIONS=(a,b:c,d) are allowed - but I don't think we need to go into details! In :reST:`comments`_, the last clause says "insert an empty comment in-between". Should that be an empty *unindented* comment? That is, is it:: * This is a list .. This is a blockquote or must it be:: * This is a list .. This is a blockquote (I assume the latter, but haven't tried it). In :reST:`inline markup`_, second paragraph, you have "differenct". In :reST:`indirect hyperlinks`_, you say "After processing into HTML this would be expressed as", and I think that should be "might be expressed as", because of the choice of call-out or fold-in styles. Discussion - literal blocks and doctest blocks ---------------------------------------------- According to :reST:`doctest blocks`_, "Indentation is not requried for doctest blocks". This, of course, means that any indentation *present* causes the production of an enclosing blockquote, and the resultant indentation of the doctest block in the final result. Meanwhile, because indentation *is* required for literal blocks, it is difficult to get the same effect - one presumably has to resort to:: The following is indented literal text: :: Or at least I hope so. *However*, to the reader of the "raw" text, there is little difference between:: The following is not indented:: Because it is literal. and:: The following *is* indented: >>> # Because it is Python And yet the results in the output cannot be made as similar, because we have lost the "original" indentation of the literal text. I realise that you probably don't (for good reason) want to "preserve" the indentation of the literal block (after all, technically it isn't there, in some sense), but if one is trying to present the output of a Writer as faithful to what the writer of raw text would naturally write, this is a problem. Or maybe I should just be making my Writer have an option to put a blockquote around literals anyway... .. The next section is a source of frustration to me, because I had already spent a significant amount of time writing it when Outlook <fx:spit> reacted badly to some XEmacs keys I typed at it, and I lost it. So this version probably isn't as good as what almost existed! Post-parse transformations -------------------------- Yes, I like the descriptions you've already done here. Footnote numbering ~~~~~~~~~~~~~~~~~~ I certainly found the description in :reST:`auto-numbered footnotes`_ enough to implement the resolution of footnote numbering - I would initially just suggest a reference thereto! Indirect hyperlink resolution ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. OK, some proposed/possible text... There are likely to be two variants of indirect hyperlink resolution, depending upon the requirements of the particular Writer being used. The first, "call-out", is typically aimed at the production of printed matter. For "call-out" processing, all that is needed is to gather all of the indirect hyperlink targets together, and provide the user with an appropriate subtree (probably a <section> called something like "References") which they can insert at the appropriate point in their document. For instance, given the following input:: Go python_! .. _python:: http://www.python.org/ then the HTML produced from a call-out processed document might look like:: <p>Go <a href="#python">python</a>! <!-- omitted HTML --> <h2><a name="references">References</a></h2> <!-- other targets omitted --> <br><strong><em><a name="python">python:</a></em></strong> <a href="http://www.python.org/">http://www.python.org/</a> <!-- other targets omitted --> Alternatively, if a "References" section already exists in a document (containing more traditional textual references), a Writer might choose to merge the "call-out" links with that. The second mechanism, "fold-in", is typical of the traditional usage for HTML documents. In this instance, the indirect hyperlink is modified so that it points directly to the required resource, and the indirect hyperlink target is removed from the document tree. Thus the HTML output for the example above, with "fold-in", would be:: <p>Go <a href="http://www.python.org/">http://www.python.org/</a>! Favourite lines --------------- I like quite a bit of the document, but some lines strike me as very nice - I'm not sure if I can explain why I find the first one funny, and it probably isn't intended that way! * (please pay attention to the colons after "Paragraph") * Only those who understand the escaping and inline markup rules may attempt the remaining 1% Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.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: Garth T K. <ga...@de...> - 2001-09-10 05:21:59
|
> > - Removed -q/--quiet option. > (and also removed the printing of the delimiter, which was > suppressed by that option) > > Garth, do you think we need that delimiter? Nope. You did the right thing. :) Regards, Garth. |
From: David G. <go...@us...> - 2001-09-08 03:36:55
|
David Goodger wrote: > - Removed -q/--quiet option. (and also removed the printing of the delimiter, which was suppressed by that option) Garth, do you think we need that delimiter? As an I/O-filter-style program, I don't think it should be there, at least not by default. If you do (anybody does) want it, perhaps an opt-in -d/--delimiter option would be better? -- David Goodger go...@us... Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net |
From: David G. <go...@us...> - 2001-09-01 17:34:56
|
As you may have guessed from the volume of traffic on structuredtext-checkins [#]_, the test code refactoring initiated by Garth Kidd is complete. The monolithic test_states.py has been split up into a bunch of single-purpose test modules in test/test_states/; any 'test_*.py' module will be found and loaded (including those in 'test_*' subdirectories). I reworked (ruthlessly refactored) Garth's original "test package" code to make it simpler and more general. Once it has settled a bit, I think we can pass it on to the PyUnit folks. I've updated the snapshots manually, so it's all available right away. .. [#] Apologies. My CVS client doesn't send compound CVS commands, resulting in one message per file per checkin. -- David Goodger go...@us... Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net |
From: David G. <go...@us...> - 2001-08-29 02:35:13
|
Tony J Ibbs (Tibs) <to...@ls...> wrote on 2001-08-28 04:36: > For what it's worth, I'm happy to leave the call-out examples as > italics as you've laid them out - it's a valid representation... ... > Ah - you spotted that <br> in the "Authors" tag - in fact, the <p> > makes it look horrible when I look at the result. Rather than aesthetics, I think clarity of expression is more important for the QuickRef; make different things look different so there's no confusion. Which is why the boldfacing on field names and footnote labels (an arbitrary cosmetic decision) doesn't bother me (it serves to distinguish the parts). Perhaps *more* vertical space is required in the field lists, between fields as well as between paragraphs, to emphasize what's going on. > Gosh, doesn't one wish we could use Tim Peters' ndiff to look at > those changes! I had the same wish, for test_states.py (and BTW so did Tim, for doctest.py), so I volunteered to move the ndiff funtctionality into difflib in the standard library and update the docs. It's been checked in for Python 2.2 (class Differ and function ndiff). Also available as restructuredtext/difflib.py (what a coincidence!). Updated docs are here: http://www.python.org/doc/current/lib/module-difflib.html > I've called it 0.4.8a - should we (da da dum) move up to a higher > version number at some stage? Sure. I'll whip up a graphic for it one of these days as well. -- David Goodger go...@us... Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net |
From: Tony J I. (Tibs) <to...@ls...> - 2001-08-28 08:36:37
|
> - Removed trailing whitespace from remaining <pre> elements. This > ought to tighten up vertical space without any adverse effects. Thanks - there shouldn't have *been* any trailing whitespace (I spent some time looking, but see below!), so this is a Good Thing. > - Removed <pre> from LHS of table example. The example was > double-spaced because of it. Double thanks - I spent *ages* looking for why I got extra space at the end of that table example (it didn't double space for me, unfortunately, or I might have found it) - obviously I was too spent on looking at that document to see the "obvious" <pre> tag (and that'll teach me to rerun HTML Tidy again to check, instead of trying to do it by eye). For what it's worth, I'm happy to leave the call-out examples as italics as you've laid them out - it's a valid representation, and I'm not botherered enough to change it (so that settles the discussion in the other branch of this discussion! - I really should read more of my email before replying to an article). (this can get rethought, if necessary, when we have an *example* of actual doing this) > - Rewrote literal block section in a more logical and > easy-to-remember way. That's much better - thanks (coincidentally, I was thinking over the weekend (long, because I took Friday off and Monday was a public holiday here) that *in fact* the usage of spaces before a ``::`` and blank lines before a ``::`` were neat duals - it makes sense that *both* should omit the colons, if either does. Somehow that hadn't struck me before.) > - Fixed some minor leftovers. Ah - you spotted that <br> in the "Authors" tag - in fact, the <p> makes it look horrible when I look at the result. Please, therefore, change that:: <br>(and sundry to be, instead:: <tr><td><td>(and sundry which should "tighten up" the layout again (it's probably what I should have done in the first place, but still, laziness will out). Gosh, doesn't one wish we could use Tim Peters' ndiff to look at those changes! Thanks for the good work - I'll copy the new version back over my ntlworld copy (but with the tables change I've mentioned above). <fx: typing> - that's done. I've called it 0.4.8a - should we (da da dum) move up to a higher version number at some stage? Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ Give a pedant an inch and they'll take 25.4mm (once they've established you're talking a post-1959 inch, of course) My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) |
From: Tony J I. (Tibs) <to...@ls...> - 2001-08-28 08:07:57
|
David Goodger wrote: > I just meant that I want reStructuredText to avoid anything like the > x-platform crap HTML has to deal with, which arose because > the specs were loose (or loosely interpreted). Hmm - apart from doing only very simple things (which I'm OK with, mostly), one can't get away from that - for instance, to get reasonable appearance of lists on most platforms/browsers, one *needs* to insert "empty" paragraphs between list items. Yucky, but so. > Just one thing you missed: in the "call-out" form of > (esp. internal) hyperlink targets, the label looks just > like a footnote, so I put in a <BR> to break it up. I hadn't noticed that (and thus hadn't incorporated it into my form) - but in fact the reason it *looks* like a footnote was that in the "call out" form (which is, after all, aimed at printed matter more than anything else) I conceived of it as *being* a footnote - since that seemed to me to be the natural form to use, within printed text. > Perhaps some other form would be better? Instead of:: > > <p><b>[example]</b> This is an example crossreference target.</p> > > How about italicized? :: > > <p><i>example:</i><br> > This is an example crossreference target.</p> I don't particularly see what advantage the reader of the final document has in knowing that *this* footnote is due to something different than *that* footnote - to my mind they're much the same thing *in the printed text* - but I'm amenable to explanations that I'm wrong. Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ Give a pedant an inch and they'll take 25.4mm (once they've established you're talking a post-1959 inch, of course) My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) |