structuredtext-develop Mailing List for reStructuredText
Status: Pre-Alpha
Brought to you by:
goodger
Menu
▾
▴
structuredtext-develop — Project development discussions.
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-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-20 19:09:22
|
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:47
|
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: tav <ta...@es...> - 2002-04-13 13:15:17
|
>>>>> DG == "David Goodger" <go...@us...> wrote:
tav> could you elaborate on how you see it working without a
tav> file-like object?
DG> No, because I don't know yet! :-)
hehe, fair enough.
tav> you seem pretty set on this point... can you at least accomodate
tav> for a decode() method in the XHTMLTransformer class?
DG> No, I can't see adding broken functionality to the project.
DG> Why don't you just write a decode() function for yourself, and
DG> run the processed string through it?
ah, that's what i do now, and i don't mind doing that. however, i feel that
there would be lots of users of restructuredtext, who would appreciate such
a method...
tav> hmz. how could i go about disabling protocol recognition then?
tav> i.e. conversion of http://foo.com into a url.
DG> In the short-term, specific case you give, a backslash should
DG> do it: \http://foo.com.
is there some method that i can alter that will permanently disable the
protocol recognition?
if you could enlighten me on the protocol disabling, i shalt be a very happy
mariner. =)
DG> In the general case, I plan to make the parser modular
DG> somehow (don't ask me how, yet), so clients can enable and
DG> disable individual construct recognition.
very nice. if i someday manage to get my head round states.py, i'd love to
help out.
DG> After the merge (reStructuredText + DPS ==> Docutils), this
DG> weekend or next, I want to work on a PEP Reader component,
DG> which will require such functionality. I'll know more once
DG> that's done.
good luck.
--
best regards, tav
ta...@es...
|
|
From: David G. <go...@us...> - 2002-04-12 23:52:23
|
> DG> I may rethink the interface so you don't need > DG> StringIO, but not the way you've outlined: tav wrote: > could you elaborate on how you see it working without a file-like object? No, because I don't know yet! :-) [re mixing HTML & reStructuredText] > tav> can restx not adapt such a practise? > > DG> No! Or at least, not by me! > > you seem pretty set on this point... can you at least accomodate for a > decode() method in the XHTMLTransformer class? No, I can't see adding broken functionality to the project. Why don't you just write a decode() function for yourself, and run the processed string through it? > hmz. how could i go about disabling protocol recognition then? i.e. > conversion of http://foo.com into a url. In the short-term, specific case you give, a backslash should do it: \http://foo.com. In the general case, I plan to make the parser modular somehow (don't ask me how, yet), so clients can enable and disable individual construct recognition. It might be as simple as subclassing, or it might be more dynamic. I haven't given it much concrete thought. After the merge (reStructuredText + DPS ==> Docutils), this weekend or next, I want to work on a PEP Reader component, which will require such functionality. I'll know more once that's done. > thanks btw. You're welcome, and thanks for the feedback. -- 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: tav <ta...@es...> - 2002-04-12 09:16:19
|
>>>>> DG == "David Goodger" <go...@us...> wrote:
DG> I think I'll keep the document parts separate to some
DG> extent, within the Writer object, but leave the access
DG> up to client subclasses.
ah, nice plan.
tav> i simply added a couple of returns in core.py and [snip]
DG> I looked over them, and I think you can simplify life greatly
DG> if you rethink your approach. Instead of inserting "return"
DG> statements all over the place, take advantage of the
DG> interface, which allows for three types of "destination":
DG> (a) a file-like object, which is written directly;
DG> (b) a path to a file, which is opened and then written; or
DG> (c) `None`, which implies `sys.stdout`.
DG> You can get a return value by passing a file-like object as
DG> in (a). A StringIO object would do the trick.
i appreciate the interface, and in fact using a tempfile or a stringio
object was how i was going to approach it inittially. however, it seemed
like pointless overhead, given my singular application.
DG> I may rethink the interface so you don't need
DG> StringIO, but not the way you've outlined:
could you elaborate on how you see it working without a file-like object?
and, re the way that i have done it. please pay no heed. it was a quick hack
for my needs, and i wasn't suggesting that such a crude approach be taken in
the codebase.
tav> can restx not adapt such a practise?
DG> No! Or at least, not by me!
you seem pretty set on this point... can you at least accomodate for a
decode() method in the XHTMLTransformer class?
tav> the anchor tag is very problematic, as:
tav> [snip : example]
DG> All kinds of special-casing would have to be done,
DG> and the result would be a quagmire of ambiguity.
hmz. how could i go about disabling protocol recognition then? i.e.
conversion of http://foo.com into a url.
thanks btw.
--
best regards, tav
ta...@es...
|
|
From: David G. <go...@us...> - 2002-04-12 02:58:11
|
tav wrote:
[re the output of the HTML writer]
> if self.output could be controlled by a variable as to whether it
> included the headers/footers, that'd be even better.
I think I'll keep the document parts separate to some extent, within
the Writer object, but leave the access up to client subclasses. In
other words, I'll provide the internals, but leave the interface up to
you (for now, at least).
The "Publisher" class (& "publish()" front-end) are facades, meant to
provide convenient access to typical functionality. They are not
meant to provide arbitrary functionality. If you want something
different, subclass components; you can pass instances of your
subclasses to "publish()".
> tav> the second problem was with how you "output". the way
> tav> the publish() system was setup, one could only output to a
> tav> file or stdout.
>
> DG> The publish function (Publisher class) is a facade, a flat
> DG> front-end to the components of the system, meant to provide
> DG> enough functionality for 80% of clients. I'm only adding
> DG> functionality to the system as it is required, and yours is
> DG> the first case where a return value is required, instead of
> DG> writing to a file/stream. It may be a case of a new type of
> DG> "distribution", which I've thought about but haven't
> DG> implemented yet.
>
> a new type of distribution?
"Distributors" are an abstraction I've been mulling over. They're what
HappyDoc calls "docsets" (I think). You can distribute the output in
multiple ways:
- As a single, monolithic file.
- As a hierarchy of files & directories.
- As a data structure (monolithic or hierarchical).
- Others.
Each of these types of output would be generated by a different
"Distributor" object. I'm not yet sure if it will be useful (or
feasible) to keep distributors separate from writers. I'm not
worrying about it for now; I still have plenty of research of related
projects (HappyDoc etc.) to do first, to see how the problem has been
attacked there.
> i simply added a couple of returns in core.py and in
> writers/__init__.py and finally, in writers/xhtml.py.
I looked over them, and I think you can simplify life greatly if you
rethink your approach. Instead of inserting "return" statements all
over the place, take advantage of the interface, which allows for
three types of "destination":
(a) a file-like object, which is written directly;
(b) a path to a file, which is opened and then written; or
(c) `None`, which implies `sys.stdout`.
You can get a return value by passing a file-like object as in (a).
A StringIO object would do the trick.
I may rethink the interface so you don't need StringIO, but not the
way you've outlined:
> --- /home/services/zope/misc/stx/dps/dps/writers/__init__.py
...
> @@ -86,6 +87,9 @@
> if hasattr(self.destination, 'write'):
> destination.write(output)
> elif self.destination:
> + # tav : added a return output for text..
> + if type(self.destination) == StringType:
> + return output
> open(self.destination, 'w').write(output)
> else:
> sys.stdout.write(output)
...
> as you can see above, when `destination` is a string, recordfile()
> returns the output instead of writing it to a file or stdout.
Implemented this way, I wouldn't be able write to a file by passing a
path (which is a string), which defeats the purpose of the interface
as written.
[example of mixed HTML & reSructuredText omitted]
> how does stx co-exist with html?
Classic StructuredText doesn't treat HTML specially, that I recall.
StructuredTextNG does; its rules_ specify:
- SGML text is ignored and outputed as is.
.. _rules:
http://dev.zope.org/Members/jim/StructuredTextWiki/StructuredTextNGRules
There's a comment by Guido on that page:
The rule that SGML (you mean HTML?) text is passed through
unchanged is evil, because now we get all sorts of unpredictable
interactions between ST and HTML. Plus it's hard to quote
examples of HTML markup, which occur very frequently when talking
about Zope...
I concur wholeheartedly.
> can restx not adapt such a practise?
No! Or at least, not by me!
I'd strongly advise against it, but I can't stop you from trying.
> the anchor tag is very problematic, as:
>
> <a href="http://cvs.espnow.com/xnet">xnet cvs</a>
>
> would get parsed and converted to:
>
> <p><a href="<a
> class="referencehref="http://cvs.espnow.com/xnet">http://cvs.e
> spnow.com/xnet
> </a>">xnet cvs</a></p>
>
> not pretty.
All kinds of special-casing would have to be done, and the result
would be a quagmire of ambiguity. No 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: tav <ta...@es...> - 2002-04-10 04:26:19
|
>>>>> DG == "David Goodger" <go...@us...> wrote:
tav> i ran into restructuredtext a few weeks back, and finding it to be
tav> way cooler than the zope stx, decided to use it as the main render
tav> format in the xnet product that i have been hacking.
DG> Sounds good, but I don't understand "render format". You don't
DG> mean you *output* reStructuredText, do you?
my apologies. let me explain.
an xt_object renders itself according to the formats specified in the
xt_render_types list. and i'd like to have 'restx_to_html' (restructuredtext
to html) be the default render type. so, content would be stored as
restructuredtext and be output as html...
DG> I looked at your CVS but I don't see an overview of what you're
DG> doing. Is there one?
ah, there is no overview document ;p
however the xt_object class, where a lot of the action occurs, is fairly
well documented:
http://cvs.espnow.com/xnet/xnet/xt_object/xt_object.py?rev=HEAD&content-type
=text/vnd.viewcvs-markup
specifically, start out from __call__() and work down to render_apply()
tav> i ran into two main problems in using it "out of the box":
DG> It is all very experimental at this point, so usage anecdotes
DG> are welcome, thanks.
glad to help, and thanks in turn for a wonderful product.
tav> [snip : rant about xhtml compatability]
tav> ... so i took your html.py writer and did a quick adaptation of it:
tav> http://cvs.espnow.com/xnet/xnet/contrib/xhtml.py
DG> I see that your app is only interested in the tags between
DG> "<body>" and "</body>", exclusive. That's a useful
DG> distinction, when integrating with a wrapper system.
yea, my personal needs are to simply convert content from one format to
another... the presentation is handled by fancy zope page templates.
DG> XHTML is on my list of things to investigate. I may modify
DG> the HTML writer to output XHTML as you have done.
that'd be great, and if self.output could be controlled by a variable as to
whether it included the headers/footers, that'd be even better.
tav> the second problem was with how you "output". the way
tav> the publish() system was setup, one could only output to a
tav> file or stdout.
DG> The publish function (Publisher class) is a facade, a flat
DG> front-end to the components of the system, meant to provide
DG> enough functionality for 80% of clients. I'm only adding
DG> functionality to the system as it is required, and yours is the
DG> first case where a return value is required, instead of writing
DG> to a file/stream. It may be a case of a new type of
DG> "distribution", which I've thought about but haven't
DG> implemented yet.
a new type of distribution?
DG> I would like to support such usage in a generic form, but I'm
DG> not sure how yet. Please send me your patched files, so I can
DG> see exactly what you mean.
nothing spectacular. i simply added a couple of returns in core.py and in
writers/__init__.py and finally, in writers/xhtml.py.
here are the diffs:
---------------------------
--- /home/services/zope/misc/stx/dps/dps/core.py Thu Feb 7 02:02:02
2002
+++ core.py Fri Mar 22 05:45:09 2002
@@ -53,7 +53,8 @@
def publish(self, source, destination):
document = self.reader.read(source, self.parser)
- self.writer.write(document, destination)
+ # tav : added a return
+ return self.writer.write(document, destination)
def publish(source=None, destination=None,
@@ -70,4 +71,5 @@
pub.setparser(parsername)
if writer is None:
pub.setwriter(writername)
- pub.publish(source, destination)
+ # tav : added a return
+ return pub.publish(source, destination)
---------------------------
--- /home/services/zope/misc/stx/dps/dps/writers/__init__.py Thu Mar 7
04:00:18 2002
+++ __init__.py Fri Mar 22 05:48:27 2002
@@ -18,6 +18,7 @@
import sys
from dps import languages
from dps.transforms import universal
+from types import StringType # tav : see recordfile()
class Writer:
@@ -53,7 +54,7 @@
self.destination = destination
self.transform()
self.translate()
- self.record()
+ return self.record() # tav : added a return
def transform(self):
"""Run all of the transforms defined for this Writer."""
@@ -86,6 +87,9 @@
if hasattr(self.destination, 'write'):
destination.write(output)
elif self.destination:
+ # tav : added a return output for text..
+ if type(self.destination) == StringType:
+ return output
open(self.destination, 'w').write(output)
else:
sys.stdout.write(output)
tav> i patched some of your functions and methods with
tav> 'returns' so that the following would work:
tav>
http://cvs.espnow.com/xnet/xnet/xt_object/render/restx_to_html.py
DG> What does ``destination='here'`` mean? Is "here" a
DG> throwaway file, or is your patch treating the "here" value
DG> specially?
as you can see above, when `destination` is a string, recordfile() returns
the output instead of writing it to a file or stdout.
tav> and, now, i have ran into a third problem... i'd like to mix
tav> html and rstx in my original text.
DG> That's the purpose of the ".. raw::" directive, not yet
DG> implemented. But this should be used only sparingly. I do
DG> not intend to allow HTML mixed into reStructuredText
DG> without explicit marking.
aieee!
DG> What are you trying to do? Why mix in HTML? Perhaps
DG> there's a better way to do it. Make up a minimal
DG> example and I'll take a look.
well, there are numerous applications that i'd like to use xt_objects in...
from intranets to wikis to weblogs... and, i'd like to use restx as a
replacement for the rather incomplete and inconsistent stx in zope.
an example usecase would be in a blogging app, where the user might be
comfortable with basic html, e.g.:
------------
I had a <b>few ideas</b> for new blogs:
- The Bullshit Blog
- A community moderated blog rating other blogs ...
- The Bookmark Blog
- A sidebar blog (similar to BoingBoing's <a href="foo.com">Guestbar
blog</a>) ...
------------
in the above example, the user is aware of basic markup such as
<b>bold</bold> and <a>anchor</a> tags, but not much else, such as lists, etc
... which is where restx would come in very handy.
how does stx co-exist with html? can restx not adapt such a practise?
it strikes me that with the exception of the anchor tag, it is actually
pretty easy to get html and restx to co-exist. simply apply a reverse of the
encode() method on the returned output.
(i am sure there are other notable obstacles, but none come to mind right
now). however, the anchor tag is very problematic, as:
<a href="http://cvs.espnow.com/xnet">xnet cvs</a>
would get parsed and converted to:
<p><a href="<a
class="referencehref="http://cvs.espnow.com/xnet">http://cvs.espnow.com/xnet
</a>">xnet cvs</a></p>
not pretty.
could states.py be adapted to cater for such a situation?
DG> BTW, please post to Doc-SIG or the project mailing
DG> list in future.
doc-sig seems rather inappropriate, so am mailing the restructured-develop
list.
apologies to those on the list if this mail makes little sense. ;p
--
best regards, tav
ta...@es...
|
|
From: David G. <go...@us...> - 2002-03-28 00:58:20
|
Andreas Jung wrote: > - Is the project still maintained? The latest release is fairly old. As Richard said, reStructuredText *is* being actively developed (in CVS). There will be a final release (0.4) shortly, after which it will be merged with the Docstring Processing System project (http://docstring.sf.net/) and renamed to "Docutils" (http://docutils.sf.net/). The latest files are always available in the CVS snapshots (you'll need both): - http://docstring.sourceforge.net/dps-snapshot.tgz - http://structuredtext.sourceforge.net/rst-snapshot.tgz > - How does structuredtext handle charsets other than ASCII > e.g. latin-1 or UTF-8 or unicode ? The parser itself doesn't know or care about character sets; it's just passed a string which it processes. If passed a Unicode string, it should work just fine (I haven't tested this yet though). The reStructuredText parser is just one component of the Docutils system though. The rest of the system is using some Unicode internally, but there's no I/O support yet. I intend for it to support character sets flexibly, but haven't gotten around to it yet. The field is wide open; suggestions, patches, and enthusiastic developers welcome. BTW, it's called "reStructuredText" (abbreviation "rtxt" or "rst") to differentiate it from Zope Corp's "StructuredText" and "StructuredTextNG". The SF domain doesn't have the "re" because of a 14-character limit on project names. -- 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-27 22:07:25
|
On Thu, 28 Mar 2002 05:45, Andreas Jung wrote:
> - Is the project still maintained? The latest release is fairly old.
It's certainly very actively being developed. Get the latest dps and ReST CVS
checkouts until David makes a new release. I believe he wants to merge the
CVS trees (and hence the package) before the next release.
> - How does structuredtext handle charsets other than ASCII e.g. latin-1
> or UTF-8 or unicode ?
Sorry, no idea.
Richard
|
|
From: Andreas J. <an...@zo...> - 2002-03-27 18:45:31
|
- Is the project still maintained? The latest release is fairly old.
- How does structuredtext handle charsets other than ASCII e.g. latin-1
or UTF-8 or unicode ?
-aj
---------------------------------------------------------------------
- Andreas Jung Zope Corporation -
- EMail: an...@zo... http://www.zope.com -
- "Python Powered" http://www.python.org -
- "Makers of Zope" http://www.zope.org -
- "Life is too short to (re)write parsers" -
---------------------------------------------------------------------
|
|
From: David G. <go...@us...> - 2002-03-07 02:16:01
|
Richard Jones wrote: > Fixed in CVS. Was an import that didn't handle ReST being installed. Because of the two-project split, some fancy dancing is required in imports (because I don't work on the projects in their "installed" state). I missed a few steps. Thanks for finding them, Richard. That's just one of the many reasons I'm eager to merge the projects. I'll concentrate on fixing docs and essentials, then release, then merge to form "Docutils 0.1" ASAP. -- 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-07 02:08:42
|
On Thu, 7 Mar 2002 12:30, David Goodger wrote:
> It must be something simple that was overlooked (by you or by me, I
> don't know). It works fine for me...
Fixed in CVS. Was an import that didn't handle ReST being installed.
Richard
|
|
From: David G. <go...@us...> - 2002-03-07 01:27:26
|
Richard Jones wrote:
> ... I'm still getting
>
> Reporter: ERROR (3) Unknown directive type "image" at line 629.
>
> .. yet your example has an image used in it... help? :)
Please show us a source snippet. (Line 629 of what?)
Do you have recent snapshots installed? Both dps-snapshot.tgz &
rst-snapshot.tgz? (Merging them is on my to-do list.) Did you install
them with distutils ("python setup.py install")? What Python version?
It must be something simple that was overlooked (by you or by me, I
don't know). It works fine for 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-03-06 05:43:33
|
On Thu, 28 Feb 2002 15:24, David Goodger wrote: > I've made a lot of progress on my HTML Writer. Everything works, if crudely > at times. I don't have time to check in the files to CVS right now, but > here's a teaser. Check out these documents: > > - http://structuredtext.sourceforge.net/spec/test.html (published from > source at http://structuredtext.sourceforge.net/tools/test.txt) ... I'm still getting Reporter: ERROR (3) Unknown directive type "image" at line 629. .. yet your example has an image used in it... help? :) Richard |
|
From: David G. <go...@us...> - 2002-02-28 04:22:36
|
I've made a lot of progress on my HTML Writer. Everything works, if crudely at times. I don't have time to check in the files to CVS right now, but here's a teaser. Check out these documents: - http://structuredtext.sourceforge.net/spec/test.html (published from source at http://structuredtext.sourceforge.net/tools/test.txt) - http://structuredtext.sourceforge.net/spec/reStructuredText.html (published from source at http://structuredtext.sourceforge.net/spec/reStructuredText.txt) They're temporary, so don't bother linking to them. There will be permanent versions soon. -- 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-26 03:55:10
|
Thanks for the counter-examples. Always useful in disproving a
theory. The practical trumps the ideal. ;-)
[Tony]
> I'm not entirely sure that we should be aiming to support every
> weird and wonderful command line that someone can come up with
I suppose that if we don't at least attempt to cover the more common
variants, there will be no end to the debate. If we want successful
option lists, and not simply revert to literal blocks, we ought to
support actual usage.
[Alan]
> In my mind, the name of a command line option is "-a" or "--force",
> not "a" or "force". Likewise for "-geom" (not "geom" X-style),
> "/release" (not "release" DOS-style), or "co" (not "co" cvs-style).
> Hyphens never get stripped, and there's no parsing involved, let
> alone reparsing.
Fair enough. Since supporting every conceivable variant would be
difficult, it's reasonable to simply support a single abstract
"option" and leave the details in the element's content. (If you
check the CVS history, you'll see that that's how it was at one
point, before I "fixed" it.)
[David]
> In order to support nonstandard options (i.e. options which don't
> conform to the above), I'd rather introduce a fourth type, perhaps
> ``nonstandard_option`` ... Is it necessary?
[Alan]
> I think it's at least desirable; but then, once it's created, I
> don't understand the need for the other options. When does one need
> to know whether a given option is short, long, trapezoidal, or
> whatever?
I suppose from a document's point of view, we don't. The DPS/Docutils
is a documentation system. If there's ever an application that does
need to know, it can figure it out easily enough. Not our job.
Rethinking the whole thing, I realize that I'd been trying to come up
with a perfect model for option lists, but in order to achieve it I
had to limit their scope. The role of a documentation system is to
allow authors sufficient flexibility to describe their subject, not
for the tool to prescribe any restrictive forms, and certainly not to
proscribe. A successful documentation system is rich, flexible, and
doesn't get in the way. So let's loosen up the model.
Here's my idea for a new model to replace the current one (irrelevant
attribute lists omitted)::
<!ELEMENT option_list (option_list_item+)>
<!ELEMENT option_list_item (option_group, description)>
<!ELEMENT option_group (option, option_argument*)+>
<!ELEMENT option (#PCDATA)>
<!ELEMENT option_argument (#PCDATA)>
<!ATTLIST option_argument
%basic.atts;
delimiter CDATA #IMPLIED>
<!ELEMENT description (%body.elements;)+>
There are no longer separate option types for long/short/vms options.
The "delimiter" attribute on "option_argument" contains the delimiter
(typically either " " or "=") between the "option" and the
"option_argument". If there are multiple option arguments [#]_,
"delimiter" contains the delimiter between them (typically either " "
or ",").
.. [#] I don't know if I'll support multiple option arguments in the
parser, but the DTD ought to.
[Tony]
> Thinking-out-loud-again,
That's what mailing lists are for. :-) Please continue.
> > still-haven't-read-perl-getopt::long-ly yr's --David
[Alan]
> I didn't expect you would. I've never managed to make it all the
> way through myself. :-)
Scanned it today. Not too hairy, was expecting worse. Perhaps my bias
is showing, ex-Perler that I am. Luckily for me, Python was waiting
when I gave up after only two and a half years of Perl. Could've been
worse.
--
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: Alan J. <ja...@po...> - 2002-02-25 16:18:09
|
On Sat, 23 Feb 2002, David Goodger wrote:
> Alan Jaffray wrote:
> > I don't see the value in the "dashes are implicit" behavior. It loses
> > the ability to document non-GNU-style option lists. What does it gain?
>
> Once an option has been parsed and encoded in the doctree, the thing we're
> most interested in is the option name, not the punctuation that goes along
> with it.
In my mind, the name of a command line option is "-a" or "--force",
not "a" or "force". Likewise for "-geom" (not "geom" X-style),
"/release" (not "release" DOS-style), or "co" (not "co" cvs-style).
Hyphens never get stripped, and there's no parsing involved, let
alone reparsing.
Of course, that doesn't necessarily mean that the reStructuredText
parser is going to recognize "#$&foo" ("foo" martian-style) as part
of an option list. :)
> <!ELEMENT option
> ((short_option | long_option | vms_option), option_argument?)>
>
> In order to support nonstandard options (i.e. options which don't conform to
> the above), I'd rather introduce a fourth type, perhaps
> ``nonstandard_option`` which either keeps the punctuation in the text or in
> an attribute: either ``<nonstandard_option>-long-option-with-one-hypen</>``
> or ``<nonstandard_option marker="-">long-option-with-one-hyphen</>``. Is it
> necessary?
I think it's at least desirable; but then, once it's created, I don't
understand the need for the other options. When does one need to know
whether a given option is short, long, trapezoidal, or whatever?
> > There's a huge amount of existing software that uses single-dash long
> > options.
>
> I wonder if any of that is a target audience for reStructuredText? ;-)
Possibly. There's also a lot of new software that uses single-dash
long options. Any new X program ought to support -geometry and -font.
There's also the situation of someone writing internal docs describing
a program for their users.
> still-haven't-read-perl-getopt::long-ly yr's --David
I didn't expect you would. I've never managed to make it all the way
through myself. :-)
Alan
|
|
From: Tony J I. (Tibs) <to...@ls...> - 2002-02-25 09:57:57
|
David Goodger wrote > Besides, this is consistent with how bullet lists and enumerated lists > are put together. We store the bullet character or enumeration details > once, at the beginning of the list. Hmm. I'm not entirely sure that we should be aiming to support every weird and wonderful command line that someone can come up with, but I do *actually* have a case (that I use) that mixes the slash and dash forms. Specifically, I do a lot of work on Windows/NT, and tend thus to have batch files that encapsulate common commands. These are done "properly", with /help switches, and so on. The specific example I am thinking of is a small batch file that runs the javac, javah or javadoc tools for me. Its command line is of the form: jmake /javac -verbose where the /javac is telling it which tool to choose (and there are other options, like /debug and so on), whilst the rest of the command line is being passed down to the particular tool. Being Unix originated, despite being on NT the Java tools expect dash-style switches (and, as you can see, they don't follow the Gnu conventions). Of course, strictly speaking the dash switches *are* just the "rest of line", and I don't really expect to process them myself, so it perhaps isn't strict doc-tools territory - except that it can be useful to describe the more common switches for each tool. Thinking-out-loud-again, 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...> - 2002-02-23 16:45:13
|
Alan Jaffray wrote:
> I don't see the value in the "dashes are implicit" behavior. It loses
> the ability to document non-GNU-style option lists. What does it gain?
Once an option has been parsed and encoded in the doctree, the thing we're
most interested in is the option name, not the punctuation that goes along
with it. If we keep the hyphens/slashes in the text, we'll have to reparse
whenever we want to extract the name. A trivial operation, perhaps, but
unnecessary. Allowing for variant syntaxes makes it less trivial.
> We don't want to spend complexity dealing with every weird option-parsing
> behavior out there, but we don't have to. Just leave the dashes in, and
> people can use option lists no matter what style of parsing they use - or
> what style of parsing is used by whatever they're documenting, it's not
> necessarily a choice that the document author can make.
As I've designed the DTD, there are three types of option, the punctuation
for each is implicit and invariant::
<!ELEMENT option
((short_option | long_option | vms_option), option_argument?)>
In order to support nonstandard options (i.e. options which don't conform to
the above), I'd rather introduce a fourth type, perhaps
``nonstandard_option`` which either keeps the punctuation in the text or in
an attribute: either ``<nonstandard_option>-long-option-with-one-hypen</>``
or ``<nonstandard_option marker="-">long-option-with-one-hyphen</>``. Is it
necessary?
> There's a huge amount of existing software that uses single-dash long
> options.
I wonder if any of that is a target audience for reStructuredText? ;-)
There's also a lot of existing software that uses "+option" and other
variants. I don't see the need for the reStructuredText parser to support
them, but the Docutils DTD could, via "nonstandard_option" above.
> In the DOS world, using a single slash before both short and
> long options is nearly universal.
Already supported; no distinction is made between long & short vms_options.
still-haven't-read-perl-getopt::long-ly yr's --David
--
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-23 16:36:03
|
I've been mulling it over; here's what I've come up with:
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.
I've implemented a new attribute ``optarg_delimiter`` to element
``option_list``, in the DTD, parser, and test suite.
``optarg_delimiter`` contains the delimiter (either " " or "=")
consistently used by ``long_option`` and/or ``vms_option`` elements.
(Note that ``short_option`` elements may only use spaces as opt/arg
delimiters; they don't affect the attribute.) If no such options
exist, no ``optarg_delimiter`` attribute will be present. If delimiter
usage is mixed (both " " and "=" used), ``optarg_delimiter`` will
contain the value "mixed".
Here are the possibilities:
``<option_list>``
No delimiters were detected.
``<option_list optarg_delimiter=" ">``
Spaces should be used for long POSIX and VMS option/argument
delimiters.
``<option_list optarg_delimiter="=">``
Equals signs should be used for long POSIX and VMS option/argument
delimiters.
``<option_list optarg_delimiter="mixed">``
Mixed usage: representation is up to the client.
I initially thought of adding an attribute to the ``option`` element,
populated with each option's delimiter usage. But in a single option
there may be multiple long POSIX or VMS options, each with a different
delimiter, so that wouldn't be enough. I could have added an attribute
to the ``option_argument`` element instead. But on reflection, if a
single option list is using mixed delimiters, that program's option
parser must be able to handle mixed delimiters as well. Otherwise
there's a bug in the documentation at least. So just one attribute per
option list.
Besides, this is consistent with how bullet lists and enumerated lists
are put together. We store the bullet character or enumeration details
once, at the beginning of the list.
--
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: Alan J. <ja...@po...> - 2002-02-22 23:22:17
|
I don't see the value in the "dashes are implicit" behavior. It loses the ability to document non-GNU-style option lists. What does it gain? We don't want to spend complexity dealing with every weird option-parsing behavior out there, but we don't have to. Just leave the dashes in, and people can use option lists no matter what style of parsing they use - or what style of parsing is used by whatever they're documenting, it's not necessarily a choice that the document author can make. There's a huge amount of existing software that uses single-dash long options. In the DOS world, using a single slash before both short and long options is nearly universal. Alan |
|
From: David G. <go...@us...> - 2002-02-22 01:06:38
|
engelbert gruber wrote:
> i indent by 2 characters, e.g.
> ---
> 1. first we have to
> see this.
> ---
> this gives an error because of the unindent
> although the text looks reasonable.
The reason is because it's ambiguous. Assume this is acceptable::
1. first line
second line
Then what do we do in these cases? ::
2. first line
second line
3. first line
second line
At what point does the paragraph become a definition list?
Indentation is significant in reStructuredText, so there is a
near-zero-tolerance policy for ambiguity.
> it gets problematic when e.g.
> ---
> 9. a growing indentation, when
> using the current implementation
> 10. because here it walks over
> onto a
> 986. ...
> ---
If alignment is your concern, I would suggest this, which is perfectly
valid::
9. start with plenty
of indentation
10. so that when the
number of digits
grows, there's
986. enough space for all!
> cheers
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-21 04:12:23
|
Richard Jones wrote: > Which part of the interface are you still working on? I don't know yet. When I find some aspect of the API insufficient for the growing needs of the project, I fix it. If you notice any insufficiencies, please feel free to suggest changes. > at least we've got something in the short-term that can be used to generate > the documentation for roundup :) Cool. -- 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-21 02:02:12
|
On Thu, 21 Feb 2002 12:31, David Goodger wrote: > 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. OK, I'll start re-working the code to fit the dps frameworks. Which part of the interface are you still working on? Looks like my quick hack needs to be beaten into shape - at least we've got something in the short-term that can be used to generate the documentation for roundup :) Richard |
