From 8fiyhybs1 at aol.com  Mon Jun  9 14:13:15 2003
From: 8fiyhybs1 at aol.com (Frances Reaves)
Date: Mon Jun  9 12:11:15 2003
Subject: [Doc-SIG] Hi honey w vj
Message-ID: <m--3n5$481u$1@7cl0a.d.c6gjq>

Protect Your Privacy NOW!

Did you know that government agencies are spying on
your computer? Hackers? Marketers? Etc.

We'll the latest program gets rid of all these sources
and protects you.

Avoid the following:

* Unwanted people/agencies on your computer
* Your computer keeping a incriminating log of what
you do
* Being traced by others online
* Slow Computer Speeds
* PLUS MUCH MORE!

Click below to Learn more and get your essential copy
today!


http://www.bestdealss.net/cgi-bin/kherefer.cgi/he/index008.html?MID=khe008&r=New16534



"Many employees remain unaware technology isn't
private. They may visit sexually explicit Web sites
and not realize their employer is watching, for
example. Many don't know messages can be retrieved
months later."

-- USA Today
















To be removed click below:
http://cythsia.com/auto/index.htm

 
lebhfhfenu dyy sghzhq xi  qynqn 
uupzhnapbeup srkycl z qwpl
aun l jvgxyge
From priest at sfu.ca  Mon Jun  9 21:15:12 2003
From: priest at sfu.ca (David Priest)
Date: Mon Jun  9 23:15:49 2003
Subject: [Doc-SIG] The Use of Roles
Message-ID: <oprqi7bmq48v1t4r@mail.telus.net>

Directives seem to me to address only the mark-up of block text.  There's a 
decent document describing how to implement one's own directives in 
Docutils.

Roles seem to me to address the mark-up of inline text.  I can find nothing 
in the documentation nor the (recent, ie. 2003) archives regarding the 
implementation of one's own roles in Docutils.  I do see a fair bit of 
discussion about what roles to implement &c.

Why not allow users to add Roles in much the same manner that Directives 
can be added?  I'd much rather hack an __init__ file and add a .py role- 
handler, than hack the Docutils source itself.

What I'm looking to do is add :gui:, :key:, and :dic: roles that create 
<guilabel>, <keycap>, and <glossterm> docbook markup.  At some point I'd 
probably also like to add :idx: for indexing support.

Have I overlooked an easy add-on capability?  Is there any moral, logical, 
or political reason for allowing user directives but not user roles?  Or is 
there some amount of planning to do this eventually?

Curious, et al.
  (another) david





From aahz at pythoncraft.com  Tue Jun 10 01:51:56 2003
From: aahz at pythoncraft.com (Aahz)
Date: Tue Jun 10 00:52:01 2003
Subject: [Doc-SIG] The Use of Roles
In-Reply-To: <oprqi7bmq48v1t4r@mail.telus.net>
References: <oprqi7bmq48v1t4r@mail.telus.net>
Message-ID: <20030610045156.GA17156@panix.com>

On Mon, Jun 09, 2003, David Priest wrote:
> 
> Why not allow users to add Roles in much the same manner that Directives 
> can be added?  I'd much rather hack an __init__ file and add a .py role- 
> handler, than hack the Docutils source itself.

It's not much more difficult.  Read
docutils/parsers/rst/__init__.py

Mainly, you need to subclass from rst.states.Inliner, and you'll need to
update rst.languages.en.roles when your module gets imported.
-- 
Aahz (aahz@pythoncraft.com)           <*>         http://www.pythoncraft.com/

"If you don't know what your program is supposed to do, you'd better not
start writing it."  --Dijkstra

From goodger at python.org  Tue Jun 10 02:20:05 2003
From: goodger at python.org (David Goodger)
Date: Tue Jun 10 01:20:39 2003
Subject: [Doc-SIG] The Use of Roles
In-Reply-To: <oprqi7bmq48v1t4r@mail.telus.net>
References: <oprqi7bmq48v1t4r@mail.telus.net>
Message-ID: <3EE56A85.2050403@python.org>

David Priest wrote:
 > Directives seem to me to address only the mark-up of block text.
 > There's a decent document describing how to implement one's own
 > directives in Docutils.

The spec/howto/rst-directives.txt doc was started by Dethe Elza, who
also pushed for an easier API for directives.

 > Roles seem to me to address the mark-up of inline text.  I can find
 > nothing in the documentation nor the (recent, ie. 2003) archives
 > regarding the implementation of one's own roles in Docutils.

Hasn't been written yet.  You'll have to refer to the code, and ask
questions.  A howto for writing role handlers would be welcome.

 > Why not allow users to add Roles in much the same manner that
 > Directives can be added?  I'd much rather hack an __init__ file and
 > add a .py role- handler, than hack the Docutils source itself.

The interpreted-text role-handling mechanism could be ripped out of
the parser proper and made into a subpackage similar to directives.
Honestly, I hadn't thought of it, probably because nobody had
suggested it, and personally I have no problem hacking the Docutils
source. ;-)

 > What I'm looking to do is add :gui:, :key:, and :dic: roles that
 > create <guilabel>, <keycap>, and <glossterm> docbook markup.  At
 > some point I'd probably also like to add :idx: for indexing support.

I remember you suggesting these back in March.  Gotta be a squeaky
wheel to get the grease!  Helps if you supply your own grease too ;-).

The issue I have is, should these roles generate unique new elements
in the Docutils doctree, or should they generate <inline
class="something"> elements?  (The <inline> element didn't exist in
March, so there has been some progress!)  If the latter, the ideas in
the to-do list may cover it (see link below).  If the former, I try to
be cautious before adding new elements to the doctree.  We need to
spec out these roles and their semantics fully.

 > Have I overlooked an easy add-on capability?

No.  It doesn't exist yet.  Patches welcome!

 > Is there any moral, logical, or political reason for allowing user
 > directives but not user roles?

The functionality just hasn't been implemented yet.

 > Or is there some amount of planning to do this eventually?

There's <http://docutils.sf.net/spec/notes.html#role-bindings> and
other ideas around there.  We're still exploring the conceptual space
around interpreted text.

-- 
David Goodger    http://starship.python.net/~goodger

Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv


From priest at sfu.ca  Tue Jun 10 09:07:46 2003
From: priest at sfu.ca (David Priest)
Date: Tue Jun 10 11:17:35 2003
Subject: [Doc-SIG] The Use of Roles
In-Reply-To: <3EE56A85.2050403@python.org>
References: <oprqi7bmq48v1t4r@mail.telus.net>
Message-ID: <3EE591D2.6588.13B2918A@localhost>

> The interpreted-text role-handling mechanism could be ripped out of
> the parser proper and made into a subpackage similar to directives.
> Honestly, I hadn't thought of it, probably because nobody had
> suggested it, and personally I have no problem hacking the Docutils
> source. ;-)

I'd have no problem hacking the 
source, except that it makes it 
difficult to update when you release 
the next version...

> The issue I have is, should these roles generate unique new elements
> in the Docutils doctree, or should they generate <inline
> class="something"> elements?  (The <inline> element didn't exist in
> March, so there has been some progress!)  If the latter, the ideas in
> the to-do list may cover it (see link below).  If the former, I try to
> be cautious before adding new elements to the doctree.  We need to
> spec out these roles and their semantics fully.

If IIRC, the Docutils doctree is a 
separate idea from the actual 
Docbook output; ie. it's the 
responsibility of the output writer to 
convert doctree to tagging.

In which case, it seems to me to be 
appropriate to generate <inline 
class="rolename"> elements, 
which in DocBook would be output 
as proper tags (<guilabel>, etc); in 
HTML would be output as <span 
class="rolename"> (assuming CSS 
styling; output as <B> if not using 
CSS); in TeX would be output as 
whatever TeX uses.

Should the reader have some idea 
of what's a valid role, or should it 
just toss anything it doesn't know 
about into the class name and let 
the writers deal with it?  I can see 
arguments either way.

From cben at techunix.technion.ac.il  Tue Jun 10 20:24:05 2003
From: cben at techunix.technion.ac.il (Beni Cherniavsky)
Date: Tue Jun 10 12:52:08 2003
Subject: [Doc-SIG] The Use of Roles
In-Reply-To: <3EE591D2.6588.13B2918A@localhost>
References: <oprqi7bmq48v1t4r@mail.telus.net>
	<3EE591D2.6588.13B2918A@localhost>
Message-ID: <Pine.GSO.4.51.0306101917550.4411@techunix.technion.ac.il>

David Priest wrote on 2003-06-10:

> > The issue I have is, should these roles generate unique new elements
> > in the Docutils doctree, or should they generate <inline
> > class="something"> elements?  (The <inline> element didn't exist in
> > March, so there has been some progress!)  If the latter, the ideas in
> > the to-do list may cover it (see link below).  If the former, I try to
> > be cautious before adding new elements to the doctree.  We need to
> > spec out these roles and their semantics fully.
>
> If IIRC, the Docutils doctree is a separate idea from the actual
> Docbook output; ie. it's the responsibility of the output writer to
> convert doctree to tagging.
>
> In which case, it seems to me to be appropriate to generate <inline
> class="rolename"> elements, which in DocBook would be output as
> proper tags (<guilabel>, etc); in HTML would be output as <span
> class="rolename"> (assuming CSS styling; output as <B> if not using
> CSS); in TeX would be output as whatever TeX uses.
>
> Should the reader have some idea of what's a valid role, or should
> it just toss anything it doesn't know about into the class name and
> let the writers deal with it?  I can see arguments either way.
>
I think the criterion should be ignorability.  If you strip all
`class` attributes, you should still get acceptable results.  E.g. I
think that a `kbd` role should become a `literal` element with ``kbd``
style.  Ask yourself what's the closest approximations to each
proposed role.  It might be unmarked plain text - then `inline` fits.
It might have no acceptable approximation - then a new element might
be in order.

-- 
Beni Cherniavsky <cben@users.sf.net>


From goodger at python.org  Tue Jun 10 14:12:40 2003
From: goodger at python.org (David Goodger)
Date: Tue Jun 10 13:13:14 2003
Subject: [Doc-SIG] The Use of Roles
In-Reply-To: <Pine.GSO.4.51.0306101917550.4411@techunix.technion.ac.il>
References: <oprqi7bmq48v1t4r@mail.telus.net>	<3EE591D2.6588.13B2918A@localhost>
	<Pine.GSO.4.51.0306101917550.4411@techunix.technion.ac.il>
Message-ID: <3EE61188.30409@python.org>

Beni Cherniavsky wrote:
> I think the criterion should be ignorability.  If you strip all
> `class` attributes, you should still get acceptable results.  E.g. I
> think that a `kbd` role should become a `literal` element with ``kbd``
> style.  Ask yourself what's the closest approximations to each
> proposed role.  It might be unmarked plain text - then `inline` fits.
> It might have no acceptable approximation - then a new element might
> be in order.

Well put!

-- David Goodger


From fantasai at escape.com  Tue Jun 10 18:14:04 2003
From: fantasai at escape.com (fantasai)
Date: Tue Jun 10 23:15:22 2003
Subject: [Doc-SIG] The Use of Roles
In-Reply-To: <3EE591D2.6588.13B2918A@localhost>
References: <oprqi7bmq48v1t4r@mail.telus.net>
	<3EE591D2.6588.13B2918A@localhost>
Message-ID: <3EE64A1C.20909@escape.com>

David Priest wrote:
>
> Should the reader have some idea 
> of what's a valid role, or should it 
> just toss anything it doesn't know 
> about into the class name and let 
> the writers deal with it?  I can see 
> arguments either way.

I'd say just toss it into the class name.
The writer could then have a default handler for
anything it doesn't specifically recognize. In
HTML, it would be <span class="unrecognized-role">,
in DocBook maybe <phrase role="unrecognized-role">.
In some other format, it could be just to ignore
the tags and handle the element's content.

~fantasai


From goodger at python.org  Wed Jun 11 12:59:40 2003
From: goodger at python.org (David Goodger)
Date: Wed Jun 11 12:00:17 2003
Subject: [Doc-SIG] The Use of Roles
In-Reply-To: <3EE591D2.6588.13B2918A@localhost>
References: <oprqi7bmq48v1t4r@mail.telus.net>
	<3EE591D2.6588.13B2918A@localhost>
Message-ID: <3EE751EC.5060308@python.org>

David Priest wrote:
 > I'd have no problem hacking the source, except that it makes it
 > difficult to update when you release the next version...

So send in a patch!  If it's generally useful, we'll polish it
together and it will become part of the next version.

 > If IIRC, the Docutils doctree is a separate idea from the actual
 > Docbook output; ie. it's the responsibility of the output writer to
 > convert doctree to tagging.

Yes, but the Docutils doctree has to make sense.  It has to be
internally consistent and useful for all Writers.

Beni's description is on target.  The decision on how to represent
each proposed role is separate, case-by-case.

 > Should the reader have some idea of what's a valid role, or should
 > it just toss anything it doesn't know about into the class name and
 > let the writers deal with it?

The *Parser* must know *all* valid roles in advance.  Interpreted text
is a parser construct.  Interpreted text roles address a limitation of
the reStructuredText markup.  The writer doesn't know anything about
interpreted text itself.  From the spec:

     Only pre-determined roles are recognized; unknown roles will
     generate errors.  A core set of standard roles is implemented in
     the reference parser; see `reStructuredText Interpreted Text
     Roles`_ for individual descriptions.  In addition, applications
     may support specialized roles.

     -- http://docutils.sf.net/spec/rst/reStructuredText.html
        #interpreted-text

.. _reStructuredText Interpreted Text Roles:
    http://docutils.sf.net/spec/rst/interpreted.html

-- 
David Goodger    http://starship.python.net/~goodger

Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv


From goodger at python.org  Wed Jun 11 13:02:13 2003
From: goodger at python.org (David Goodger)
Date: Wed Jun 11 12:02:48 2003
Subject: [Doc-SIG] The Use of Roles
In-Reply-To: <3EE64A1C.20909@escape.com>
References: <oprqi7bmq48v1t4r@mail.telus.net>	<3EE591D2.6588.13B2918A@localhost>
	<3EE64A1C.20909@escape.com>
Message-ID: <3EE75285.9020708@python.org>

fantasai wrote:
> I'd say just toss it into the class name.
> The writer could then have a default handler for
> anything it doesn't specifically recognize.

No.  That way lies chaos and madness.  Extensions must be
explicitly declared somewhere.

-- David Goodger


From gherman at darwin.in-berlin.de  Thu Jun 12 14:48:44 2003
From: gherman at darwin.in-berlin.de (Dinu Gherman)
Date: Thu Jun 12 07:47:03 2003
Subject: [Doc-SIG] Getting HTML without header/footer etc.?
Message-ID: <D225A945-9CCB-11D7-A6CA-00039345C610@darwin.in-berlin.de>

Hi,

I'm pretty new to docutils, so please be patient with a maybe
silly question of mine. I checked the FAQ, looked into the tests
and tool samples, but can't find the answer, yet.

Basically, I want to expand an reST string using the docutils ma-
chinary, like this:

     from docutils.core import publish_string
     input = "**italics**"
     output = publish_string(input, writer_name='html')
     # output should be "<i>italics</i>" or sth. like this

So, I'd like to process only individual snippets of text and would
prefer not to see all the HTML headers and footers and what not
being added to the output. Is there some way to achieve this?

Thanks,

Dinu

--
Dinu C. Gherman
......................................................................
"Will the highways on the Internet become more few?"
(George W. Bush, 29 Jan. 2000)


From goodger at python.org  Thu Jun 12 11:22:45 2003
From: goodger at python.org (David Goodger)
Date: Thu Jun 12 10:23:20 2003
Subject: [Doc-SIG] Getting HTML without header/footer etc.?
In-Reply-To: <D225A945-9CCB-11D7-A6CA-00039345C610@darwin.in-berlin.de>
References: <D225A945-9CCB-11D7-A6CA-00039345C610@darwin.in-berlin.de>
Message-ID: <3EE88CB5.7000306@python.org>

Dinu Gherman wrote:
> So, I'd like to process only individual snippets of text and would
> prefer not to see all the HTML headers and footers and what not
> being added to the output. Is there some way to achieve this?

There's this code: 
<http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/193890>.  I 
wouldn't write it that way, but it may do what you want.

Ollie Rutherfurd has some code at 
<http://docutils.sf.net/sandbox/oliverr/ht/> and an article at 
<http://www.rutherfurd.net/articles/rst-ht2html.html>.

Implementing a general solution is on the to-do list.  The problem is, 
everybody who wants this functionality wants it in a slightly different way.

-- David Goodger


From gherman at darwin.in-berlin.de  Thu Jun 12 18:32:25 2003
From: gherman at darwin.in-berlin.de (Dinu Gherman)
Date: Thu Jun 12 11:30:30 2003
Subject: [Doc-SIG] Getting HTML without header/footer etc.?
In-Reply-To: <3EE88CB5.7000306@python.org>
Message-ID: <112B3C76-9CEB-11D7-A6CA-00039345C610@darwin.in-berlin.de>

David Goodger:

> Implementing a general solution is on the to-do list.  The problem
> is, everybody who wants this functionality wants it in a slightly
> different way.

Thanks! I've invented my own ugly workaround until then... (basi-
cally chopping off the stuff I don't need).

Another related issue is this: I'm generating code snippets outside
of docutils and would like to pass chunks containing some HTML to
docutils, but without having it transform them into entities like
&gt; etc. It should only care about the reST formatting rules. May-
be there is a clever way to do this?

Dinu

--
Dinu C. Gherman
......................................................................
"La perfection est atteinte, non pas lorsqu'il n'y a plus rien
? ajouter, mais lorsqu'il n'y a plus rien ? retirer."
(Antoine de Saint-Exup?ry)


From goodger at python.org  Thu Jun 12 12:40:19 2003
From: goodger at python.org (David Goodger)
Date: Thu Jun 12 11:40:54 2003
Subject: [Doc-SIG] Getting HTML without header/footer etc.?
In-Reply-To: <112B3C76-9CEB-11D7-A6CA-00039345C610@darwin.in-berlin.de>
References: <112B3C76-9CEB-11D7-A6CA-00039345C610@darwin.in-berlin.de>
Message-ID: <3EE89EE3.7080300@python.org>

Dinu Gherman wrote:
> Another related issue is this: I'm generating code snippets outside
> of docutils and would like to pass chunks containing some HTML to
> docutils, but without having it transform them into entities like
> &gt; etc. It should only care about the reST formatting rules. May-
> be there is a clever way to do this?

I'm not following you.  Can you provide examples?  What exactly do these 
"code snippets" contain, and how are they generated?

I suspect the "raw" directive may be part of the answer.

-- David Goodger


From gherman at darwin.in-berlin.de  Thu Jun 12 19:01:25 2003
From: gherman at darwin.in-berlin.de (Dinu Gherman)
Date: Thu Jun 12 11:59:29 2003
Subject: [Doc-SIG] Getting HTML without header/footer etc.?
In-Reply-To: <3EE89EE3.7080300@python.org>
Message-ID: <1E741BCF-9CEF-11D7-A6CA-00039345C610@darwin.in-berlin.de>

David Goodger:

> Dinu Gherman wrote:
>> Another related issue is this: I'm generating code snippets outside
>> of docutils and would like to pass chunks containing some HTML to
>> docutils, but without having it transform them into entities like
>> &gt; etc. It should only care about the reST formatting rules. May-
>> be there is a clever way to do this?
>
> I'm not following you.  Can you provide examples?  What exactly do
> these "code snippets" contain, and how are they generated?
> I suspect the "raw" directive may be part of the answer.

Ok, I've worked around that without "raw", since it affected only
hyperlinks, but I'll look into "raw", too, as this is probably the
more general solution...

In fact, I've got snippets that contain HTML hyperlinks like this:
<a href...>...</a> which the HTML writer of docutils seems to
translate into something like this &lt;a...a&gt; Now I do create
proper doctutils inline hyperlinks like this `%s <http:...>`__
which works just fine.

Thanks,

Dinu

--
Dinu C. Gherman
......................................................................
"I know the human being and fish can coexist peacefully."
(George W. Bush, 29 Sep. 2000)


From garth at deadlybloodyserious.com  Fri Jun 13 10:10:09 2003
From: garth at deadlybloodyserious.com (Garth Kidd)
Date: Thu Jun 12 19:10:56 2003
Subject: [Doc-SIG] Getting HTML without header/footer etc.?
In-Reply-To: <112B3C76-9CEB-11D7-A6CA-00039345C610@darwin.in-berlin.de>
Message-ID: <001601c33137$cb34e6f0$3f00800a@gkiddxp2>

> Thanks! I've invented my own ugly workaround until then... 
> (basi- cally chopping off the stuff I don't need).

PyDS' `StructuredText.py`__ shows how to derive a ``HTMLFragmentTranslator``
from ``docutils.writers.html4css1.HTMLTranslator`` without having to define
your own from scratch. Georg has hacked into the code since I wrote it,
though, so don't ask me what ``HTMLFragmentWriter.translate`` is up to. :) 

__ http://simon.bofh.ms/cgi-bin/cvsweb/PyDS/PyDS/StructuredText.py

> Another related issue is this: I'm generating code snippets 
> outside of docutils and would like to pass chunks containing 
> some HTML to docutils, but without having it transform them 
> into entities like &gt; etc. It should only care about the 
> reST formatting rules. May- be there is a clever way to do this?

I think we're talking ``raw:: html`` substitutions, here. The PyDS
WikiTool__ uses the PyDS ShortcutTool for that. Warning on the site: I'm
reworking MeshTool extensively, and at the moment things aren't being
rendered like they should. 

__ http://www.pycs.net/users/0000088/wiki/WikiTool.html

Regards,
Garth.


From gb at murphy.bofh.ms  Fri Jun 13 09:30:37 2003
From: gb at murphy.bofh.ms (Georg Bauer)
Date: Fri Jun 13 02:30:53 2003
Subject: [Doc-SIG] Getting HTML without header/footer etc.?
In-Reply-To: <001601c33137$cb34e6f0$3f00800a@gkiddxp2>
Message-ID: <r01050400-1026-8BD37D299D6811D7B0830050E4304D13@[10.0.0.123]>

Hi!

> your own from scratch. Georg has hacked into the code since I wrote it,
> though, so don't ask me what ``HTMLFragmentWriter.translate`` is up to. 
> :) 

That's just to pass in two switches to the inner classes. I need to override the
section_level and I need to get the suppress_paragraphs switch in, too. So the
code of the method is actually the same as in the parent class, only one call is
changed.

bye, Georg

From gherman at darwin.in-berlin.de  Fri Jun 20 11:49:52 2003
From: gherman at darwin.in-berlin.de (Dinu Gherman)
Date: Fri Jun 20 04:47:56 2003
Subject: [Doc-SIG] Release strategy
Message-ID: <2830F536-A2FC-11D7-9B7A-00039345C610@darwin.in-berlin.de>

Hi,

I see the last release will soon be a year old and the website says
the CVS snapshots are potentially unstable, so I wonder what people
think about a new official release 0.3?

At least I'd like to be able to use the HTML fragment rendering di-
rectly instead of pointing people to a CVS version to install or de-
ploy a patch myself.

Regards,

Dinu

--
Dinu C. Gherman
......................................................................
"The?government?announced?today?that?it?is?changing?its?emblem?to?
a condom?because?it?more?clearly?reflects?the?government's?politi-
cal stance.??A?condom?stands?up?to?inflation,?halts?production,?de-
stroys the?next?generation,?protects?a?bunch?of?pricks,?and?gives?
you?a sense?of?security?while?you?are?actually?being?screwed."
(Anonymous)


From aahz at pythoncraft.com  Fri Jun 20 11:42:33 2003
From: aahz at pythoncraft.com (Aahz)
Date: Fri Jun 20 10:42:36 2003
Subject: [Doc-SIG] Release strategy
In-Reply-To: <2830F536-A2FC-11D7-9B7A-00039345C610@darwin.in-berlin.de>
References: <2830F536-A2FC-11D7-9B7A-00039345C610@darwin.in-berlin.de>
Message-ID: <20030620144233.GA14022@panix.com>

On Fri, Jun 20, 2003, Dinu Gherman wrote:
> 
> I see the last release will soon be a year old and the website says
> the CVS snapshots are potentially unstable, so I wonder what people
> think about a new official release 0.3?
> 
> At least I'd like to be able to use the HTML fragment rendering di-
> rectly instead of pointing people to a CVS version to install or de-
> ploy a patch myself.

The wheels are grinding.  Real Soon Now.
-- 
Aahz (aahz@pythoncraft.com)           <*>         http://www.pythoncraft.com/

"If you don't know what your program is supposed to do, you'd better not
start writing it."  --Dijkstra

From goodger at python.org  Fri Jun 20 13:50:30 2003
From: goodger at python.org (David Goodger)
Date: Fri Jun 20 12:51:04 2003
Subject: [Doc-SIG] Release strategy
In-Reply-To: <20030620144233.GA14022@panix.com>
References: <2830F536-A2FC-11D7-9B7A-00039345C610@darwin.in-berlin.de>
	<20030620144233.GA14022@panix.com>
Message-ID: <3EF33B56.90001@python.org>

Dinu Gherman wrote:
 > I see the last release will soon be a year old and the website says
 > the CVS snapshots are potentially unstable,

In practice, the snapshots are very stable (in terms of lack of bugs);
any instability is very short-lived.  I should revise the website text
to be more encouraging.

 > so I wonder what people think about a new official release 0.3?

I hope to get 0.3 out this weekend.  There are a couple of small
issues remaining, and I suddenly got busy with other things.

-- 
David Goodger    http://starship.python.net/~goodger

Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv


From priest at sfu.ca  Fri Jun 20 11:02:43 2003
From: priest at sfu.ca (David Priest)
Date: Fri Jun 20 13:03:17 2003
Subject: [Doc-SIG] Release strategy
In-Reply-To: <3EF33B56.90001@python.org>
References: <20030620144233.GA14022@panix.com>
Message-ID: <3EF2DBC3.10319.5244852@localhost>

On 20 Jun 2003 at 12:50, David Goodger wrote:
> 
> I hope to get 0.3 out this weekend.  There are a couple of small
> issues remaining, and I suddenly got busy with other things.

Although my DocUtils XSL -> XSL-FO transformations aren't complete 
(the largest gap, by far, is in page sequencing), should I perhaps 
toss it out to y'all anyway?

I'd started out hacking Walsh's DocBook XSL transformations, but 
they're simply enormous and complex, and not well-suited for the 
limited number of tags generated by DocUtil's DocBook transformation. 
 Throwing my hands up in despair, I decided I'd just best learn 
XSL/XSL-FO myself, and start from scratch.

I've tried to make the file easy to customize, and I'm sure there are 
far better approaches to some of what I've done (in terms of making 
it all less deterministic, so that it's able to deal better with 
unusual tag combinations), but it is, in my humble opinion, a fine 
start...

I wouldn't mind receiving a few sample files to test my 
transformations.  They're currently directed at publishing a 
technical reference manual, and nothing else; this has limited 
ability to exercise all the tags and combinations of tags.

From gherman at darwin.in-berlin.de  Sat Jun 21 10:53:23 2003
From: gherman at darwin.in-berlin.de (Dinu Gherman)
Date: Sat Jun 21 03:51:27 2003
Subject: [Doc-SIG] CVS access data buglet on web page?
Message-ID: <6EEFA7AE-A3BD-11D7-A764-00039345C610@darwin.in-berlin.de>

Hi,

I think there is a wrong CVS command on the following page in
the section "Anonymous CVS Access".

   http://sourceforge.net/cvs/?group_id=38414

Instead of:

   cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/docutils login

shouldn't it rather be:

   cvs 
-d:pserver:anonymous@cvs.docutils.sourceforge.net:/cvsroot/docutils 
login

At least, the latter gets me connected, but the former doesn't...

Dinu

--
Dinu C. Gherman
......................................................................
"The war on terror involves Saddam Hussein because of the nature
of Saddam Hussein, the history of Saddam Hussein, and his willing-
ness to terrorize himself."
(George W. Bush, 29 Jan. 2003)


From gherman at darwin.in-berlin.de  Sat Jun 21 12:39:29 2003
From: gherman at darwin.in-berlin.de (Dinu Gherman)
Date: Sat Jun 21 05:37:41 2003
Subject: [Doc-SIG] Getting HTML without header/footer etc.?
In-Reply-To: <001601c33137$cb34e6f0$3f00800a@gkiddxp2>
Message-ID: <41314182-A3CC-11D7-A764-00039345C610@darwin.in-berlin.de>

Garth Kidd:

> PyDS' `StructuredText.py`__ shows how to derive a 
> ``HTMLFragmentTranslator``
> from ``docutils.writers.html4css1.HTMLTranslator`` without having to 
> define
> your own from scratch. Georg has hacked into the code since I wrote it,
> though, so don't ask me what ``HTMLFragmentWriter.translate`` is up 
> to. :)
>
> __ http://simon.bofh.ms/cgi-bin/cvsweb/PyDS/PyDS/StructuredText.py

Having some headaches with my own approach I tried this and found
I'm getting a traceback like this (on a fresh CSV checkout):

[localhost:test/fragments] dinu% python StructuredText.py
Traceback (most recent call last):
   File "StructuredText.py", line 140, in ?
     class Latin1StringIO(docutils.io.StringIO):
AttributeError: 'module' object has no attribute 'StringIO'

Simply replacing docutils.io.StringIO with (c)StringIO.StringIO
doesn't work, either.

Dinu

--
Dinu C. Gherman
......................................................................
"I want to put a ding in the universe." (Steve Jobs)


From goodger at python.org  Sat Jun 21 10:56:54 2003
From: goodger at python.org (David Goodger)
Date: Sat Jun 21 09:57:28 2003
Subject: [Doc-SIG] CVS access data buglet on web page?
In-Reply-To: <6EEFA7AE-A3BD-11D7-A764-00039345C610@darwin.in-berlin.de>
References: <6EEFA7AE-A3BD-11D7-A764-00039345C610@darwin.in-berlin.de>
Message-ID: <3EF46426.6090801@python.org>

Dinu Gherman wrote:
> I think there is a wrong CVS command on the following page in
> the section "Anonymous CVS Access".
> 
>   http://sourceforge.net/cvs/?group_id=38414

Those are the official SourceForge instructions.  I don't have any
control over that page.

> Instead of:
> 
>   cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/docutils login
 >
> shouldn't it rather be:
> 
> cvs \
> -d:pserver:anonymous@cvs.docutils.sourceforge.net:/cvsroot/docutils  \
 > login

That's what the above-referenced web page used to say.

> At least, the latter gets me connected, but the former doesn't...

SF's CVS has been slowing down lately.  They're doing some
reorganization.  It could be that the latter command will stop
working at some point.  If it works for you, fine.  Otherwise, the
snapshots are always up to date.

-- David Goodger


From moe20 at mail.ru  Sun Jun 22 10:39:38 2003
From: moe20 at mail.ru (usic@rambler.ru)
Date: Sun Jun 22 12:40:37 2003
Subject: [Doc-SIG] Increase in Web Traffic
Message-ID: PM20009:39:38 AM

An HTML attachment was scrubbed...
URL: http://mail.python.org/pipermail/doc-sig/attachments/20030622/b5a726b3/attachment.htm
From garth at deadlybloodyserious.com  Mon Jun 23 17:58:38 2003
From: garth at deadlybloodyserious.com (Garth Kidd)
Date: Mon Jun 23 02:59:15 2003
Subject: [Doc-SIG] Getting HTML without header/footer etc.?
In-Reply-To: <41314182-A3CC-11D7-A764-00039345C610@darwin.in-berlin.de>
Message-ID: <002f01c33954$e13d4170$0601010a@gkiddxp2>

> Having some headaches with my own approach I tried this and 
> found I'm getting a traceback like this (on a fresh CSV checkout):

The code is written for docutils-0.2. The CVS version of docutils changes
the API, breaking the code. 

Regards,
Garth.


From goodger at python.org  Tue Jun 24 23:47:08 2003
From: goodger at python.org (David Goodger)
Date: Tue Jun 24 22:47:41 2003
Subject: [Doc-SIG] [ANN] Docutils 0.3 released
Message-ID: <3EF90D2C.70401@python.org>

Docutils is a system for processing plaintext documentation
(reStructuredText markup).  Docutils currently supports input from
standalone files and PEPs; a future release will be include support
for inline documentation from Python modules and packages.  It
currently produces simple HTML4 for CSS1, LaTeX (which can be
processed to PDF), and Docutils-native XML.  DocBook XML output is
under development, and other formats will become available in time.

Quick link to the download:

     http://prdownloads.sourceforge.net/docutils/docutils-0.3.tar.gz

Docutils home page: http://docutils.sourceforge.net/

Although useful and solid, Docutils should be considered experimental
software.  There are plans to overhaul the configuration system and
rename the front-end tools.  Internal and API details may change.

There have been many improvements since release 0.2:

* Extensions to reStructuredText syntax & parser: embedded URIs in
   hyperlink references; interpreted text; block quote attributions.
   New directives: admonition, topic, sidebar, line-block,
   parsed-literal, rubric, epigraph, highlights, pull-quote, include,
   raw, replace, unicode, class, sectnum, target-notes.

* Added convenience functions for easy programmatic/library use.

* Added LaTeX output support (thanks to Engelbert Gruber).

* The front-end tools have increased in number and now have support
   for command-line options (thanks to Greg Ward's Optik) and
   configuration files.

* reStructuredText has become an official format for PEPs (see
   http://www.python.org/peps/pep-0001.html).

* Thanks to international Docutils users, language support has been
   added for Spanish, French, Italian, and Slovak.  These join the
   existing Swedish, German, and English language support.  Support for
   more languages is welcome and easy to add!

* Lots of improvements and bug fixes.  Details in HISTORY.txt.

To subscribe to the mailing lists:

* Development discussions (docutils-develop@lists.sourceforge.net):
   http://lists.sourceforge.net/lists/listinfo/docutils-develop

* Docutils usage Q&A (docutils-users@lists.sourceforge.net):
   http://lists.sourceforge.net/lists/listinfo/docutils-users

* CVS checkin messages:
   http://lists.sourceforge.net/lists/listinfo/docutils-checkins

High-level discussions also take place on the Python Doc-SIG mailing
list: http://mail.python.org/mailman/listinfo/doc-sig.

User documentation:

* 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

* Docutils Front-End Tools: http://docutils.sf.net/docs/tools.html

Further details here:

* Docutils FAQ: http://docutils.sf.net/FAQ.html

* Docutils README: http://docutils.sf.net/README.html

* Docutils History: http://docutils.sf.net/HISTORY.html

* Copying Docutils: http://docutils.sf.net/COPYING.html

* reStructuredText Markup Specification:
   http://docutils.sf.net/spec/rst/reStructuredText.txt

* PEP 256, Docstring Processing System Framework:
   http://www.python.org/peps/pep-0256.html

* PEP 258, Docutils Design Specification:
   http://www.python.org/peps/pep-0258.html

* PEP 287, reStructuredText Docstring Format:
   http://www.python.org/peps/pep-0287.html

There are still many features to be added.  Contributors are welcome!

-- 
David Goodger    http://starship.python.net/~goodger

Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv


From goodger at python.org  Sun Jun 29 20:30:21 2003
From: goodger at python.org (David Goodger)
Date: Sun Jun 29 19:30:57 2003
Subject: [Doc-SIG] A plan for configuration files
Message-ID: <3EFF768D.2050803@python.org>

I've just posted a plan for reorganizing Docutils configuration files
on the docutils-develop list, but it affects all users of Docutils,
not only its consulting developers.  See the message here:
<http://article.gmane.org/gmane.text.docutils.devel/876>.  Subscribe
here: <http://lists.sourceforge.net/lists/listinfo/docutils-develop>.

-- 
David Goodger    http://starship.python.net/~goodger
For hire: http://starship.python.net/~goodger/cv
Docutils: http://docutils.sourceforge.net/
(includes reStructuredText: http://docutils.sf.net/rst.html)


From goodger at python.org  Mon Jun 30 23:29:56 2003
From: goodger at python.org (David Goodger)
Date: Mon Jun 30 22:30:31 2003
Subject: [Doc-SIG] [ANN] Character entity sets for reStructuredText
Message-ID: <3F00F224.6030607@python.org>

I have generated files containing substitution definitions (that use
the "unicode" directive) and temporarily posted them here:
<http://docutils.sf.net/tmp/charents/> (tarball:
<http://docutils.sf.net/tmp/charents.tgz>).  A description and
instructions for use are here:
<http://docutils.sf.net/tmp/charents/README.html>`__.  Thanks to David
Priest for the original idea.  Incorporating these files into Docutils
is on the to-do list.

I'm thinking of adding these to Docutils in a built-in "include"
directory.  From the to-do list:

     Default directory for "built-in includes", using the C syntax
     ``#include <name>``?

         Use C-preprocessor semantics for locating include files?
         E.g., ``.. include:: file.txt`` will read another file into
         the current one, relative to the current file's directory, and
         ``.. include:: <standard>`` will read a standard include file
         from ``docutils/include/``.  (Should "quotes" be required
         around non-standard include files?)

         -- http://sf.net/mailarchive/message.php?msg_id=1938401

     I now think that ``docutils/parsers/rst/include/`` is a better
     place for these files, since they're reStructuredText-specific.

     Keeping standard data files together with the package code makes
     sense to me.  It seems much less complex to implement than a
     separate system data directory, such as ``/usr/share/docutils``.
     Any reason a system data directory should be used?  How does
     Distutils handle data files?

An invocation would look like this::

     .. include:: <isonum.txt>

Other possiblilities for the standard includes directory are macros;
see <http://docutils.sf.net/spec/notes.html#text-date> for an example.

If there are enough other standard include files, it may be desirable
to make subdirectories, such as "charents".  Under such a scheme, an
invocation would look like this::

     .. include:: <charents/isonum.txt>

Comments are welcome.

-- 
David Goodger    http://starship.python.net/~goodger
For hire: http://starship.python.net/~goodger/cv
Docutils: http://docutils.sourceforge.net/
(includes reStructuredText: http://docutils.sf.net/rst.html)