docstring-develop Mailing List for Docstring Processing System
Status: Pre-Alpha
Brought to you by:
goodger
Menu
▾
▴
docstring-develop — Project development discussions.
You can subscribe to this list here.
| 2001 |
Jan
|
Feb
|
Mar
|
Apr
|
May
|
Jun
|
Jul
(11) |
Aug
(27) |
Sep
(23) |
Oct
(4) |
Nov
|
Dec
|
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 2002 |
Jan
|
Feb
(4) |
Mar
(5) |
Apr
(7) |
May
|
Jun
|
Jul
|
Aug
|
Sep
|
Oct
|
Nov
|
Dec
|
|
From: David G. <go...@us...> - 2002-04-21 16:44:56
|
All development has been transferred to the Docutils project. The home pages and project summary pages now reflect this. I will be shutting down the DPS & reStructuredText mailings lists soon. Please subscribe to the new lists: - Development discussions (doc...@li...): http://lists.sourceforge.net/lists/listinfo/docutils-develop - CVS checkin messages: http://lists.sourceforge.net/lists/listinfo/docutils-checkins -- David Goodger <go...@us...> Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ - The Go Tools Project: http://gotools.sourceforge.net/ |
|
From: David G. <go...@us...> - 2002-04-21 03:33:07
|
Ueli wrote:
> Incidentally, I once meant to enter an option list, but typed::
>
> -1 Option "1"
> -2
> - 4 Option "4". Option "2" proves that options need no
> description.
>
> first. I found the warning ::
>
> Reporter: WARNING (2) Unindent without blank line at line <deleted>.
>
> not very helpful...
I've improved the system messages. The parser now reports:
Reporter: WARNING (2) Option list ends without a blank line;
unexpected unindent at line 2.
Other cases of a construct ending without a blank line (which is often
because of a markup problem) now offer similarly improved diagnostics. If
you find any other, please let me know!
--
David Goodger <go...@us...> Open-source projects:
- Python Docutils: http://docutils.sourceforge.net/
- The Go Tools Project: http://gotools.sourceforge.net/
|
|
From: David G. <go...@us...> - 2002-04-20 19:09:21
|
The purpose of the Docutils project is to create a set of tools for
processing plaintext documentation into useful formats, such as HTML,
XML, and TeX. It is the subject of PEPs 256 & 258. Docutils
currently supports input from standalone files; soon it will process
PEPs, and eventually it will support inline documentation from Python
modules and packages. Docutils uses the reStructuredText markup, the
subject of PEP 287; other markups are possible. It produces simple
HTML for CSS; other formats will become available in time.
Quick link to the download:
http://prdownloads.sf.net/docutils/docutils-0.1.tar.gz
Docutils home page: http://docutils.sourceforge.net/
To subscribe to the mailing lists:
- Development discussions (doc...@li...):
http://lists.sourceforge.net/lists/listinfo/docutils-develop
- CVS checkin messages:
http://lists.sourceforge.net/lists/listinfo/docutils-checkins
High-level discussions take place on the Python Doc-SIG mailing list:
http://mail.python.org/mailman/listinfo/doc-sig,
mailto:Do...@py...
A ReStructuredText Primer (gentle introduction):
http://docutils.sf.net/docs/rst/quickstart.html
Quick reStructuredText (user reference):
http://docutils.sf.net/docs/rst/quickref.html
There has been a lot of progress lately. The reStructuredText parser
is feature-complete, there's a standalone input file reader, and a
simple HTML/CSS writer. The web site's HTML files are generated from
reStructuredText source (the quickref being the only exception).
There are a few simple front-ends in docutils/tools; see the README:
http://docutils.sf.net/README.html.
There is still much work to be done. Contributors are welcome!
Release 0.1 (2002-04-20)
========================
This is the first release of Docutils, merged from the now inactive
reStructuredText_ and `Docstring Processing System`_ projects. For
the pre-Docutils history, see the `reStructuredText HISTORY`_ and
`DPS HISTORY`_ files.
.. _reStructuredText: http://structuredtext.sf.net/
.. _Docstring Processing System: http://docstring.sf.net/
.. _reStructuredText HISTORY:
http://structuredtext.sf.net/HISTORY.html
.. _DPS HISTORY: http://docstring.sf.net/HISTORY.html
General changes: renamed 'dps' package to 'docutils'; renamed
'restructuredtext' subpackage to 'rst'; merged the codebases; merged
the test suites (reStructuredText's test/test_states renamed to
test/test_rst); and many modifications required to make it all work.
--
David Goodger <go...@us...> Open-source projects:
- Python Docutils: http://docutils.sourceforge.net/
- The Go Tools Project: http://gotools.sourceforge.net/
|
|
From: David G. <go...@us...> - 2002-04-19 04:00:46
|
Release 0.4 of each of the Docstring Processing System and reStructuredText markup parser projects have been posted to their project sites (URLs in my .sig below). These releases are the final ones for these projects. The two projects will be merged and renamed to "Docutils"; a SourceForge project is being constructed at http://docutils.sourceforge.net/, and a 0.1 release of Docutils will follow shortly. Once the DPS and reStructuredText projects are merged and renamed, they will become inactive. So this is really a contractual obligation non-announcement; you might as well wait a day or three for Docutils 0.1. Quick links to the downloads: - http://prdownloads.sf.net/structuredtext/restructuredtext-0.4.tar.gz - http://prdownloads.sf.net/docstring/dps-0.4.tar.gz There has been a lot of progress since the last release, long ago. The parser is construct-complete, there's a standalone input file reader, and a simple HTML/CSS writer. There are a few simple front-ends in restructuredtext/tools; see its README.txt. There is still much work to be done. If you would like to be added as a developer to the new Docutils project, please let me know (I've already added some people as developers). -- 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-04-18 03:03:04
|
The bug with negative numbers being mistaken for option lists has been fixed in CVS. CVS snapshots are also available. -- 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-04-16 22:55:29
|
Hi Ueli,
You've definitely found a bug. The negative numbers are the key here; the
tables have nothing to do with it. A freestanding paragraph like this would
also produce incorrect output:
-1
I think your first suggestion is the way to go:
> Require non-empty descriptions for options
I'll try to fix it as soon as possible.
If you find any other surprises, an easy way to diagnose them is to use the
"publish.py" front-end, which produces pretty-printed pseudo-XML of the
internal data strucutre. It will show you exactly what the parser sees.
Thanks for the bug report!
--
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: Ueli S. <u_s...@bl...> - 2002-04-16 21:56:18
|
David,
After lots of painless usage, I had my first unpleasant surprise with
reStructuredText recently, when negative integers in tables appeared
in monospaced text in my browser. It wasn't very hard to find out why
-- they are recognised as option lists items and have empty
descriptions. An `example file`_ is attached below.
If my interpretation of the DTD is correct, then this behaviour is a
bug. From my limited understanding of XML, ``description`` entities
contain ``body.elements``, and these in turn can't be empty -- please
correct my if I'm wrong on this!
Otherwise, it's probably a misfeature. Negative integers as table
elements are probably a frequent case in daily life (especially since
reST is intended for more than "just" Python docstrings!), and the
surprise I had should be avoided. I see three ways around it:
- Require non-empty descriptions for options (so a negative integer by
itself surrounded by blank lines would be a paragraph, or an error
within an option list);
- Disallow option lists in tables (and maybe other constructs too?);
- Documenting this behaviour.
The second point compromises the ability to document reST with itself,
so -1 on this one. The third one isn't really a solution for obvious
reasons, so -2 ... The first solution probably doesn't break
anything, so it's my preferred one.
What do you think?
Ueli
.. _`example file`:
----------------------------------------------------------------------
The table:
+-------------------+-------------------------------------------+
|Example |Note |
+===================+===========================================+
|1 |A simple integer |
+-------------------+-------------------------------------------+
|-1000 |Negative integers are options... |
+-------------------+-------------------------------------------+
|-100.0 |... but negative floats are not an option. |
+-------------------+-------------------------------------------+
|-200 |This option list consists of two options |
|-300 |and an option group. |
|-400, -500 | |
+-------------------+-------------------------------------------+
|-100 and a comment |This is not an option list, as there is |
| |only one space after the ``-100``. |
+-------------------+-------------------------------------------+
was entered as::
+-------------------+-------------------------------------------+
|Example |Note |
+===================+===========================================+
|1 |A simple integer |
+-------------------+-------------------------------------------+
|-1000 |Negative integers are options... |
+-------------------+-------------------------------------------+
|-100.0 |... but negative floats are not an option. |
+-------------------+-------------------------------------------+
|-200 |This option list consists of two options |
|-300 |and an option group. |
|-400, -500 | |
+-------------------+-------------------------------------------+
|-100 and a comment |This is not an option list, as there is |
| |only one space after the ``-100``. |
+-------------------+-------------------------------------------+
but should, IMHO, be rendered as:
+-------------------+-------------------------------------------+
|Example |Note |
+===================+===========================================+
|1 |A simple integer |
+-------------------+-------------------------------------------+
|\-1000 |Negative integers need quoting... |
+-------------------+-------------------------------------------+
|-100.0 |... but negative floats are not an option. |
+-------------------+-------------------------------------------+
|\-200 |A bunch of negative numbers. |
|\-300 | |
|\-400, -500 | |
+-------------------+-------------------------------------------+
|-100 and a comment |This is not an option list, as there is |
| |only one space after the ``-100``. |
+-------------------+-------------------------------------------+
without the need for quoting the negative integer. This time, I
entered the table as::
+-------------------+-------------------------------------------+
|Example |Note |
+===================+===========================================+
|1 |A simple integer |
+-------------------+-------------------------------------------+
|\-1000 |Negative integers need quoting... |
+-------------------+-------------------------------------------+
|-100.0 |... but negative floats are not an option. |
+-------------------+-------------------------------------------+
|\-200 |A bunch of negative numbers. |
|\-300 | |
|\-400, -500 | |
+-------------------+-------------------------------------------+
|-100 and a comment |This is not an option list, as there is |
| |only one space after the ``-100``. |
+-------------------+-------------------------------------------+
.. Note::
Incidentally, I once meant to enter an option list, but typed::
-1 Option "1"
-2
- 4 Option "4". Option "2" proves that options need no
description.
first. I found the warning ::
Reporter: WARNING (2) Unindent without blank line at line <deleted>.
not very helpful...
|
|
From: Tony J I. (Tibs) <to...@ls...> - 2002-03-20 09:51:06
|
Richard Jones wrote: > On Wed, 20 Mar 2002 12:38, David Goodger wrote: > > All this browser-fiddling is outside my expertise and > > interest. Anybody want to take it on? > > I'd say that for now it's not worth trying to force it. Worry > about other stuff (like the nuking of the separate ReST CVS ;) Not having seen the details of what you're discussing (and for reasons too boring to go into, it's difficult for me to view PNG files at work), I'd still agree. The exact details of HTML representation can be left until later. After all, you're unlikely to do anything more horrible than javadoc. The important thing is to have *reasonable* output, and then people can argue (!). But later on. 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: Richard J. <rj...@ek...> - 2002-03-20 01:45:35
|
On Wed, 20 Mar 2002 12:38, David Goodger wrote: > All this browser-fiddling is outside my expertise and interest. Anybody > want to take it on? I'd say that for now it's not worth trying to force it. Worry about other stuff (like the nuking of the separate ReST CVS ;) Richard |
|
From: David G. <go...@us...> - 2002-03-20 01:38:58
|
Richard Jones wrote: > I've just snapped four screenshots of the latest table of contents efforts. I > believe this is a simple stylesheet issue. These shots may be viewed at > http://mechanicalcat.net/temp/. > Yep, it's the:: > > div.contents li { > margin-top: -20px } > > that's doing it. Yes, I suspected it would break. I was trying to get "compact" list behavior using CSS, but it seems difficult. Unless I'm missing something obvious? I tried using "margin-top: -2em", which should be proportional to the text size, but when I changed text sizes in IE, it screwed up. IE seems to add a fixed amount of margin per list item. But Netscape is different. And the other examples bear this out. Easy to see why people use tables for layout. Or graphics. CSS level 1 and HTML 4.01 "strict" are not sufficiently flexible; CSS1 doesn't provide what the "strict.dtd" takes away. But CSS level 2 is not supported well enough yet. We'll have to use "loose" HTML with more hard-coded attributes. Unfortunate. Any other options? I'm no HTML expert; advice welcome. As for the "links" output, it seems to be broken ("<P>" inside "<LI>" forces a newline perhaps?). The "lynx" contents output looks good though (but the docinfo table is screwed up). > If I render the page with the stylesheet from about two weeks ago (attached) > it's OK... > > - shot_konqi_ok.png At that time, there was no specific support for contents at all. It seems Konqueror doesn't add much margin/padding to list items at all. All this browser-fiddling is outside my expertise and interest. Anybody want to take it on? -- 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-03-19 23:03:22
|
On Wed, 20 Mar 2002 09:55, I wrote:
> I've just snapped four screenshots of the latest table of contents efforts.
> I believe this is a simple stylesheet issue.
Yep, it's the::
div.contents li {
margin-top: -20px }
that's doing it.
Richard
|
|
From: Richard J. <rj...@ek...> - 2002-03-19 22:55:51
|
I've just snapped four screenshots of the latest table of contents efforts. I believe this is a simple stylesheet issue. These shots may be viewed at http://mechanicalcat.net/temp/. - shot_konqi.png - shot_links.png - shot_zilla.png - shot_lynx.png If I render the page with the stylesheet from about two weeks ago (attached) it's OK... - shot_konqi_ok.png Richard |
|
From: Richard J. <rj...@ek...> - 2002-02-24 21:53:42
|
On Fri, 22 Feb 2002 20:01, Tony J Ibbs (Tibs) wrote:
> David Goodger wrote:
> > Over time you'll see that I continually evolve my designs,
> > searching for a sometimes-elusive ideal.
>
> The *good* thing is that, so far, David has turned out to be rather good
> at this (in my opinion - I'm not very good at "humble" - at least).
Oh, I agree - I've been very impressed with what I've seen so far.
> BTW - glad to see Richard joining in - the more the merrier.
>
> Tibs
> ...hoping to get back to spare-time work on DPS next week some time...
Heh - here's hoping I can get some real time to devote to it. I'm definitely
interested in incorporating ReST into Zope3, for example (though I haven't
raised that with the Zope guys yet).
Richard
|
|
From: Tony J I. (Tibs) <to...@ls...> - 2002-02-22 09:02:07
|
David Goodger wrote: > Abstracts work as a fixed-title mini section. I like that. > Over time you'll see that I continually evolve my designs, > searching for a sometimes-elusive ideal. The *good* thing is that, so far, David has turned out to be rather good at this (in my opinion - I'm not very good at "humble" - at least). BTW - glad to see Richard joining in - the more the merrier. Tibs ...hoping to get back to spare-time work on DPS next week some time... -- Tony J Ibbs (Tibs) VoxNav - http://www.yeomannavigation.com/ - "We talk. You arrive" Turn-by-turn route planning to your mobile 'phone - 09050 505050 My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) |
|
From: Richard J. <rj...@ek...> - 2002-02-22 03:15:36
|
On Fri, 22 Feb 2002 13:44, David Goodger wrote:
> I've revised my design, for three reasons. First, I think of the docinfo as
> the "copyright page" metadata stuff, and the abstract doesn't belong there.
> Second, because unlike all the other docinfo elements which contain only
> text (%text.model;), abstracts may contain multiple body elements. Third, I
> already had (artificial, in retrospect) limitations on abstracts: there
> could be only one, and it had to be at the end of the docinfo.
>
> Working on my HTML Writer forced me to think about the roles of the various
> pieces. Abstracts work as a fixed-title mini section.
OK, I was trying to shoe-horn abstracts into meta descriptions, which is out
of their scope :)
> Over time you'll see that I continually evolve my designs, searching for a
> sometimes-elusive ideal. Please bear with me, and consider *everything*
> experimental until 1.0. It's a pain, I know. (Believe me, I know. It's
> painful to *me* to rip out code sometimes.) But it's for the best.
Sounds fair enough to me.
> If you notice anything that smells bad, please point it out. Debates on the
> mailing lists have helped considerably.
No problem, as long as it's welcome :)
> > I was actually going to stuff the abstract into the html head as a meta
> > description tag.
>
> You can still do that. But what if the abstract is half a page long? Or
> includes a bullet list or table?
The information destined for the HTML meta tags should be PCDATA, yes.
> Besides, there's now a ``.. meta::``
> directive specifically for HTML metadata.
I noticed that when it broke the parser :)
Richard
ps. sorry, meant to cc the list on the last mail, but hit the w0rng button ;)
|
|
From: David G. <go...@us...> - 2002-02-22 02:42:41
|
I checked dps/spec/gpdi.dtd in to CVS: >> Log Message: >> - Made ``abstract`` a structural element, after ``docinfo``. Richard Jones wrote: > In my mind, the abstract forms a part of the docinfo. I've revised my design, for three reasons. First, I think of the docinfo as the "copyright page" metadata stuff, and the abstract doesn't belong there. Second, because unlike all the other docinfo elements which contain only text (%text.model;), abstracts may contain multiple body elements. Third, I already had (artificial, in retrospect) limitations on abstracts: there could be only one, and it had to be at the end of the docinfo. Working on my HTML Writer forced me to think about the roles of the various pieces. Abstracts work as a fixed-title mini section. Over time you'll see that I continually evolve my designs, searching for a sometimes-elusive ideal. Please bear with me, and consider *everything* experimental until 1.0. It's a pain, I know. (Believe me, I know. It's painful to *me* to rip out code sometimes.) But it's for the best. If you notice anything that smells bad, please point it out. Debates on the mailing lists have helped considerably. > I was actually going to stuff the abstract into the html head as a meta > description tag. You can still do that. But what if the abstract is half a page long? Or includes a bullet list or table? Besides, there's now a ``.. meta::`` directive specifically for HTML metadata. -- 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: Ueli S. <u_s...@bl...> - 2001-10-04 20:55:19
|
OK - here you go!
David -- I tried to submit a patch to sourceforge, but I think it
didn't work as I kept getting an error message from some script
("Fatal error: Call to a member function on a non-object in
common/tracker/ArtifactFile.class on line 106").
Tony -- I don't think you should accept the patches into pydps for
your releases. They're really meant as a starting point for a
discussion on the required APIs, not as a model the actual
implementation. You'll probably see that quickly...
[David]
> I haven't had time lately to do much (renovations, the in-laws arrived from
> Japan, and gotta watch "Enterprise"!). Today I began the process of putting
All in all I still consider myself very happy without a TV...
I'm waiting for feedback!
Ueli
|
|
From: Tony J I. (Tibs) <to...@ls...> - 2001-10-04 09:30:23
|
Ueli Schläpfer wrote: > If it's in the general interest, I'll be happy to post the code. Definitely in the general interest! As David says, going through Sourceforge is probably best, if you can. I'm very likely to be willing to accept the change to pydps - but I'm hoping to try to get it into CVS some time soon (my excuses for not doing reST work recently are not as good as David's, though). David - what's the best way of actually getting Ueli's patch integrated into pydps? I'm assuming they're fairly trivial, so maybe just copying them on my part, for the moment... 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-10-04 03:15:27
|
Hi Ueli,
Yes, please do post the code. A patch on SourceForge would be best:
http://sourceforge.net/tracker/?func=add&group_id=26626&atid=387777
I haven't had time lately to do much (renovations, the in-laws arrived from
Japan, and gotta watch "Enterprise"!). Today I began the process of putting
the docs into shape for the transforms, but I haven't done anything with the
code yet. I'd like to see what you've done.
--
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: Ueli S. <u_s...@bl...> - 2001-10-03 22:14:03
|
Hello all, As I am working mostly with plain text (reST) files, I liked the bibliographic fields and the document title promotion. So I went ahead and implemented: - a reader package (which is trivial for now, as it contains only a plain text reader); - a transformer package, which basically includes David's code that he removed from the reST parser following the discussion on Doc-SIG and here (around Sept. 24) and implements the new specs (docinfo and subtitle); - some changes to Tony's pydps, which now uses this reader and transforms for text files if asked to do so. If it's in the general interest, I'll be happy to post the code. I haven't spent much time designing the API's (well, I profited from David's design for the parser and formatter packages!), but it may provide a useful starting point for a discussion on sensible API's for these components. Ueli |
|
From: Tony J I. (Tibs) <to...@ls...> - 2001-09-26 10:51:35
|
Ho hum, http://www.tibsnjoan.co.uk/reST/pydps.tgz This may be the last upload before refactoring. Which I discussed elsewhere. The package now contains a README.txt file at David's request (yes, it's a text file written in reST, despite my grumbles at David the other day about file extensions). The HTML writer will attempt to sort out autonumbered footnotes - I believe it works for a single document (e.g., an reST text file), but of course this is the wrong approach for Python source. Rather more of the standard DPS elements now get converted to HTML (including tables - neat stuff), although they are not necessarily very pretty (pretty is not an aim as yet - or at least that's what I'm sticking to). All this means I can now turn restructuredtext/spec/reStructuredText.txt into HTML and produce something that I find easier to read. Yeh. Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "I'm a little monster, short and stout Here's my horns and here's my snout When you come a calling, hear me shout I will ROAR and chase you out" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) |
|
From: Tony J I. (Tibs) <to...@ls...> - 2001-09-26 09:54:27
|
I started this to reply to Ueli, and then realised that my response was
essentially just:
I think that David's approach (as I understand it)
of providing optional methods to produce the effect
wanted is probably the best way forward.
but that I wanted to diverge sideways...
I'm aiming to refactor pydps (bouncy fun - and maybe produce pysource
out of it, who knows) to follow David's Reader/Transformer/Writer model
in the next week or so (I've not got very far yet, though, apart from
thinking about it lots).
I *actually* expect to have a flowline that's something like (sorry, no
ASCII art):
1. Reader
- uses compiler [1]_ to extract information
from the Python source code
- calls the reST parser on any docstrings
that need it
- combs_ any of the resultant docstrings
2. Transformer
- (actually, the last two steps from the Reader
might arguably go here - we need to do the
docstring parsing after we *know* we've found
any ``__docformat__`` value, after all)
- produces a DPS tree from the Python information
- combs_ it as required [2]_
3. Writer
- outputs the DPS tree as (in the first instance)
HTML
Since the HTML Writer would be handling a pure DPS tree, it would then
be a good candidate for moving out of pysource into the main docutils
tree (if we have one by then). I rather hope that at least the
FootnoteComb would also be such a candidate.
Combs
-----
The metaphor of combing through hair to remove tangles is a bit iffy,
but I like the term (I think David calls them Filters, which is less
obvious to me). I'm expecting to have a series of combs which can be run
on a DPS tree or subtree. Obvious ones are:
TitleComb
This does what David wants to produce a title.
I suspect that it raises an exception if it
can't do so, at which point it is up to the
caller to do something sensible (either ignore
the problem, or provide a default title).
FootenoteComb
This runs over a subtree (clearly for Python code,
we don't want to run it over anything bigger than
a docstring, lest we confuse footnotes!) and sorts
out the numbering (in my development version of
pyspd (not on the web yet) this is actually done
as part of the HTML output phase, which is clearly
the Wrong Place for it.
David - a question or two on this. Each autonumbered
footnote/footnote reference has the attribute 'auto'
set to "1". I want to *insert* actual footnote numbers
into the tree. I can just add a new attribute 'auto-number'
into elements as required, *or* I could ask that you set
'auto' to be "-1" for the "no number yet" case, and use
'auto' to store the *actual* number calculated. Which to
do is a style issue, so I'd prefer to leave it up to you
(but using the same attribute would make things a bit
neater in the code - I'm not sure if it would generate
as elegant XML, though - I'd need to look up the detailed
attribute present/absent rules).
ContentsComb
This runs over the entire tree, and locates <section>
elements. It produces a <contents> subtree, which can
be inserted at the appropriate place, with links to
the <section>s. It needs to make sure that the links
it uses are *real*, so ideally it will use the "implicit"
link for a section when it exists, and it will have to
invent one when the implicit link isn't there (presumably
because the section is the twelfth "Introduction" in the
document...).
LinksComb
This handles the indirect hyperlinks. It probably comes
in two phases, because in a Python context we need to
*resolve* them on a per-docstring basis, but if the
user is trying to do the callout form of presentation,
they would then want to group them all at the end of the
document.
.. [1] I note that in the CVS for Python, the compiler module
is now in the standard library - hurrah! And it also looks
like the bug that stopped the 1.2aX compiler module from
*working* has also been fixed (just as I was about to find
out how to submit a bug report - even more hurrah!)
.. [2] does that count as verbing a noun?
Tibs
(So much to do, so little etc. And I've just been given news that I'm to
start on a *really exciting* project for paid work, as well.)
--
Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/
"Bounce with the bunny. Strut with the duck.
Spin with the chickens now - CLUCK CLUCK CLUCK!"
BARNYARD DANCE! by Sandra Boynton
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)
|
|
From: Ueli S. <u_s...@bl...> - 2001-09-25 17:47:00
|
(Warning: Some of what follws may not be sorted out well enough -- I
don't have the time to write and rewrite as much as I
should, but I don't want to miss the opportunity to add my 2
cents worth before going off line for a couple days...)
[Tony]
> As to HTML. The normal convention in HTML is that the document title
> (that is, the thing in <title> ) be the same as the <h1> title, and that
> there be one (and only one) <h1> in a document. The <title> is then
[...]
> at the top, which is used for both <title> and <h1>, and the "section
> hierarchy" (if any) starts with an <h2>.
Thanks for the explanations! I don't see how it would make HTML
easier, though, as the final output is
[...]
>
> My problem is that I'm trying to write formatters for *any* document
> that might come in (yes, I know I'm writing pydps/pysource, but I want
> the Writer to work for any document), so we have to be able to cope
> with:
>
> 1. Document with no titles at all
> 2. Document with one title (OK - David does that)
> 3. Document with more than one title (at the same level)
> - which in essence *really* resolves back to case 1.
>
> I'm afraid that the only "perfect" solution I can see for that (in the
> sense of *predictable*) is to require the user to indicate that they
> *do* have a document title, and that it is *this* thing, here. That then
> makes them aware of the problem, also, which I think is a necessary
> thing (otherwise, surprise will eventuate).
>
[...]
> Hmm. In PySource mode, the parser should not be trying to introduce
> titles - it is, after all, handling arbitrary document fragments, and
> can't know anything about their global scope (unless it is told!).
>
> *If* the final tree shall always have a title, where does it come from
> if the document author didn't provide one? Surely in that case it is not
> up to the *parser* to decide on what a title should be - that is up to
> the application. So one has three options:
>
> 1. The parser makes one up (yuck)
> 2. The application makes one up (yuck)
> 3. An error is generated (yuck)
>
> I'd vote for 3, not least for ease of explanation (I cite "there are no
> complex rules about making up document titles" versus "well, if the
> document is one section, we'll use the section title as a title, and not
> have any sections, but if the document is zero sections we'll do XXX and
> if the document is two or more sections we'll do YYY" - sorry to harp on
> the point!).
You've a point here... Still, I believe the promotion is a Good Thing
at least for standalone documents. Let me try to reformulate:
The first title becomes the document title if
- it's at the very beginning of the document and
- it's the only title at this level.
Does that sound too complicated? Once I realized how it worked, I
went "oh, cool!" and wouldn't miss this feature now.
> Ueli seems, to me, to be partially arguing for the case I want in his
> next message. He also writes:
I don't have a firm point of view yet, and I second your point that
it's not a trivial issue.
My current opinion is that it really depends on what input we're
processing -- what is good for docstring processing may be wrong for
standalone documents and vice versa. Hence I believe that the
promotion of a lone first section title should be optional.
Similarly, specifying and enforcing whether a documents needs a title
or not should be left to the writer, as this depends on the output
format and possibly on the context the system is used in, and the
application, as it may also depend on contecxt entirely *outside* the
DPS. Which obviously opens up a whole new discussion, namely on how
to pass such context information down to the DPS...
> > The source filename isn't known to the writer, is it?
>
> Well, it is in the pysource/pydps case (and I don't see why it shouldn't
> be elsewhere) - I attach a "filename" attribute to the Package and
> Module elements (which later on will become appropriate DPS structures,
> of course).
>
> > Still, say I want ``<title>filename.rtxt</title>`` in HTML, but I
> > definitely don't want ``\title{filename}`` in LaTeX. How about
> > giving the title a "generated" attribute? Then it's left to the
> > writer to use (or ignore) it, but any document could be required to
> > have a title. (Which would mean to update the DTD.)
>
> *If* David still really wants to produce a title of his own, then yes,
> that's a good distinction to make.
It's not enough, though -- the writer still needs to be told by the
application whether it may use it or not. Again, a docstring
vs. standalone-document issue (the document title for a docstring
will probably be generated by the reader, but should be respected).
But I really have to go now... Hope I was clear enough!
Ueli
|
|
From: Tony J I. (Tibs) <to...@ls...> - 2001-09-24 09:36:31
|
David Goodger wrote: > [Tony] > > First, I've uploaded a new pydps > > Great; I'll have to take a look at it. Where should it be installed on > the source tree? (Perhaps a short README.txt file?) At the moment, it doesn't need to be anywhere particular - it just imports things from DPS and restructuredtext (easy if they've been installed). I'll try to coin a README.txt file sometime soon, since this thing begins to approach usability (hah, until I restructure it under the new scheme!) > [Tony] > > 2. When processing the string module (yes, I know it isn't marked as > > containing reST texts!), the text:: > > > > [1:2] > > > > (or similar) is incorrectly identified as a link. Not a > Good Thing. > > ``1:2`` won't be a link (as your example confirms), but ``a:b`` will > be. Why? Because according to RFC2396, 'a' could be a URI scheme (as > in 'http' or 'mailto'). The solution? Use inline literals. Hmm. Will `a:b` be treated as a URI? (I haven't tested it). Is ``a:b`` *really* likely to be a sensible URI, given that ``a`` is entirely "local"? Should we be treating with the whole possible gamut of URIs, or restricting ourselves to those most likely? And other exciting questions I shall try not to think too hard about for the moment... 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-09-24 09:30:20
|
Ueli Schläpfer gave a good explanation of why David Goodger had chosen
to do something I didn't understand - namely make a document with a
title at the start have no section within it (except it was subtler than
that).
By the way, I did check the documentation, and it seemed to me that the
current documentation indicated that a title would cause a section to be
started - so David, if you want to perform this promotion, then it needs
to be documented (unless I've missed it *again*).
On the other hand, I don't actually see why the DPS system should have
to do the promotion for the user, when it's not clear that it is always
wanted (in other words, why is it up to the DPS system to decide that
the case of a single section is special, and then have a sudden
disjunction in its behaviour for two sections - that's my inner pedant
objecting!).
Regardless, an immediate solution to resolve the docstring case (and
possibly a useful thing to do anyway) would be to have an argument to
the Parser that states upfront that we are working on a document
*fragment* - that is, something that is going to be "stitched in" by
hand, later on, to an existing DPS tree. I would imagine that we may
come across other actions in the future that are sensible in the context
of a full document, but not in the cause of a fragment.
As to HTML. The normal convention in HTML is that the document title
(that is, the thing in <title> ) be the same as the <h1> title, and that
there be one (and only one) <h1> in a document. The <title> is then
displayed on the window as decoration (e.g., as the text on the top of
the browser window). This is a strong convention, but is (of course) not
part of the standard.
A relevant cutting from HTML4 is:
Every HTML document must have a TITLE element in the HEAD
section.
Authors should use the TITLE element to identify the contents
of a document. Since users often consult documents out of
context, authors should provide context-rich titles. Thus,
instead of a title such as "Introduction", which doesn't
provide much contextual background, authors should supply
a title such as "Introduction to Medieval Bee-Keeping" instead.
For reasons of accessibility, user agents must always make the
content of the TITLE element available to users (including
TITLE elements that occur in frames). The mechanism for doing
so depends on the user agent (e.g., as a caption, spoken).
Broadly, HTML common practise treats a document as having a single title
at the top, which is used for both <title> and <h1>, and the "section
hierarchy" (if any) starts with an <h2>.
That makes HTML easy - it doesn't, of course, address any of Ueli's
other points.
Maybe (horrors) we should reserve one specific markup form to mean
"overall title"::
==============
Document title
==============
===================
This is not allowed
===================
(because it is a form reserved for the document
title, of which we may only have one).
Or perhaps we'll have to resort to::
:Title: Document title
Somehow, I don't see David liking either of those...
Anyway, to some specific comments:
Ueli wrote:
> This makes sense to me, so I consider it a feature. I'm actually not
> sure how I'd be able to give a title to the document as a whole if the
> parser worked as you expected (unless you special-cased the first
> section level!) (Explicitly discriminating between a document title
> and regular section titles doesn't count here.)
Hmm. Having concentrated on the HTML case (sorry, it's what I've been
working on) I hadn't seen the distinction, of course.
My problem is that I'm trying to write formatters for *any* document
that might come in (yes, I know I'm writing pydps/pysource, but I want
the Writer to work for any document), so we have to be able to cope
with:
1. Document with no titles at all
2. Document with one title (OK - David does that)
3. Document with more than one title (at the same level)
- which in essence *really* resolves back to case 1.
I'm afraid that the only "perfect" solution I can see for that (in the
sense of *predictable*) is to require the user to indicate that they
*do* have a document title, and that it is *this* thing, here. That then
makes them aware of the problem, also, which I think is a necessary
thing (otherwise, surprise will eventuate).
Ueli wrote:
> Now, it seems to me that the structures of documents and sections are
> close relatives:
>
> - A document may or may not have a title, a section always has one.
> - A document may have a subtitle, bibliographic elements, and an
> abstract. A section has none of these.
> - The rest of the content follows the same model.
>
> Can thus sections be treated as simpler cases of documents (instead of
> the other way round, which is how I understand your post)? I'm not
> sure how I would exploit this, though...
I'm not sure either (nor if one should), but your analysis is clearly
correct. Again, I've been too focused on the HTML case.
David Goodger wrote:
> It is actually intended that by the time the document tree
> gets to the writer, it must have a title. The parser can't
> always determine the title by itself, such as in PySource
> mode. The PySource reader is expected to supply all the
> titles as appropriate.
Hmm. In PySource mode, the parser should not be trying to introduce
titles - it is, after all, handling arbitrary document fragments, and
can't know anything about their global scope (unless it is told!).
*If* the final tree shall always have a title, where does it come from
if the document author didn't provide one? Surely in that case it is not
up to the *parser* to decide on what a title should be - that is up to
the application. So one has three options:
1. The parser makes one up (yuck)
2. The application makes one up (yuck)
3. An error is generated (yuck)
I'd vote for 3, not least for ease of explanation (I cite "there are no
complex rules about making up document titles" versus "well, if the
document is one section, we'll use the section title as a title, and not
have any sections, but if the document is zero sections we'll do XXX and
if the document is two or more sections we'll do YYY" - sorry to harp on
the point!).
Ueli seems, to me, to be partially arguing for the case I want in his
next message. He also writes:
> The source filename isn't known to the writer, is it?
Well, it is in the pysource/pydps case (and I don't see why it shouldn't
be elsewhere) - I attach a "filename" attribute to the Package and
Module elements (which later on will become appropriate DPS structures,
of course).
> Still, say I want ``<title>filename.rtxt</title>`` in HTML, but I
> definitely don't want ``\title{filename}`` in LaTeX. How about
> giving the title a "generated" attribute? Then it's left to the
> writer to use (or ignore) it, but any document could be required to
> have a title. (Which would mean to update the DTD.)
*If* David still really wants to produce a title of his own, then yes,
that's a good distinction to make.
> (BTW, my first idea was to add a "sourcefile=filename.rtxt"
> attribute to the document. I like the "generated" much better,
> though!)
I think that the sourcefile as an optional attribute on the document is
probably a useful thing, as well.
Anyway, this is difficult stuff (in terms of folding it in to something
easy to use and remember, not in terms of implementing!), so I await
David's responses with interest.
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.)
|
