From webmaster@pferdemarkt.ws Thu Mar 6 14:01:01 2003 From: webmaster@pferdemarkt.ws (webmaster@pferdemarkt.ws) Date: Thu, 6 Mar 2003 06:01:01 -0800 Subject: [Doc-SIG] Pferdemarkt.ws informiert! Newsletter 03/2003 http://www.pferdemarkt.ws Message-ID: <200303061401.GAA21018@eagle.he.net> http://www.pferdemarkt.ws Wir sind in 2003 erfolgreich in des neue \"Pferdejahr 2003 gestartet. Für den schnellen Erfolg unseres Marktes möchten wir uns bei Ihnen bedanken. Heute am 06.03.2003 sind wir gut 2 Monate Online! Täglich wächst unsere Datenbank um 30 Neue Angebote. Stellen auch Sie als Privatperson Ihre zu verkaufenden Pferde direkt und vollkommen Kostenlos ins Internet. Zur besseren Sichtbarmachung Ihrer Angebote können SIe bis zu ein Bild zu Ihrer Pferdeanzeige kostenlos einstellen! Wollen Sie direkt auf die erste Seite, dann können wir Ihnen unser Bonussystem empfehlen. klicken Sie hier: http://www.pferdemarkt.ws/bestellung.html Ihr http://Pferdemarkt.ws Team Klicken Sie hier um sich direkt einzuloggen http://www.Pferdemarkt.ws Kostenlos Anbieten, Kostenlos Suchen! Direkt von Privat zu Privat! Haben Sie noch Fragen mailto: webmaster@pferdemarkt.ws From brett@python.org Wed Mar 12 22:16:13 2003 From: brett@python.org (Brett Cannon) Date: Wed, 12 Mar 2003 14:16:13 -0800 (PST) Subject: [Doc-SIG] Slides for reST PyCon tutorial Message-ID: I am giving a tutorial on reST at PyCon (http://www.python.org/pycon/ ) and I would like technical feedback on the slides I have done. You can find the web page at http://www.ocf.berkeley.edu/~bac/rest_tutorial.html . The one page is the whole presentation. The goal of the tutorial is to get people who have never touched reST to be able to read either a PEP or the python-dev Summaries with no troubles. Now I have a 15 minute time limit and I already had to cut out tables; I will probably have to cut out one or two more sections to be in under the time limit. If you have any comments, please email me personally (no need to bug the list about this). I am mostly looking for feedback on technical issues. I have enough friends who do not know reST to be able to test clarity out on them. -Brett From goodger@python.org Wed Mar 12 23:34:30 2003 From: goodger@python.org (David Goodger) Date: Wed, 12 Mar 2003 18:34:30 -0500 Subject: [Doc-SIG] Slides for reST PyCon tutorial In-Reply-To: Message-ID: I'd like to make some comments. The HTML seems to be at least partly based on Docutils output, so I'm guessing reST source may exist. Does it? Is it available somewhere, or could it be made available? -- David Goodger From priest@sfu.ca Fri Mar 14 23:36:15 2003 From: priest@sfu.ca (David Priest) Date: Fri, 14 Mar 2003 15:36:15 -0800 Subject: [Doc-SIG] Hello and feedback Message-ID: Hi, all. I'm a technical writer who has been looking for a way to allow my subject-matter experts (programmers and engineers) to contribute to the maintenance of documentation, freeing me to get on with writing some much- needed new documentation. These people are not willing to learn a new software tool. They'd really like to use Word, but that's simply a big, big mistake: it will crap out on us as the documents get big and complex. I'd like to use DocBook XML, but it's unweildly for them and difficult to read without an XML-aware editor -- which would be a new software tool, which they don't want. So it looks like structured text is the solution: as long as I can transform it into DocBook XML, so that I can import it into my layout app and generate a PDF in under five minutes, things will be cool. And as I improve the XSL, I can even bypass the layout app, which means they can publish straight to PDF themselves, no worries. After chasing a few false leads, ReST appears to be the best candidate for accomplishing what I want. The ASCIIDoc project was *almost* there, but lacked a few key pieces. I have spent the past couple days transforming a moderately complicated document to ReST. The transformation is not complete: there are some missing pieces. You can download the zipfile from http://www.sfu.ca/~priest/VRAS.zip The two key missing puzzle-pieces are as follows: - I am unable to insert Unicode character entities into the text. Substitutions are the answer, so I've created a |subst| replace:&xAAA; table, as included in the zipfile. Alas, the DocUtils insist on 
coding or &-substituting the replacement text.  If this is fixed 
(perhaps by a "replaceliteral:" role), DocUtils will be much improved.
 - I am unable to use regex macros to manipulate the input text.  There are 
two uses for this:

  1) To do standardized typographic replacement on naive-user's text.  For 
instance -- in print documentation -- the long dash, as I just used it, 
should be replaced using an em-dash surrounded by thin spaces.  This is a 
detail that no naive user should have to worry about: that's my job as 
technical writer.  Likewise, certain measurement units require marking-up: 
I'd like my naive users to write "36.8degrees" and get 36.8[degree sign], 
or 10m3 and get 10m[superscripted 3].

     .. use the formal en-dash with number ranges
     .. regex:: ([0-9]+?)-([0-9]+?) = \1–\2

     Note that the parenthesis in the prefix part of the equation indicate 
grouping: the regex says to look for one-or-more numbers (and remember 
them), a hyphen, and one-or-more numbers (and remember them, too).  The 
postfix equation says to insert the first memorized group, an en-dash, and 
the second memorized group.
 If a file has a regex definition, it will be run before all other macros 
and substitutions, mais non?  I think so.
 2) To supplement the :role:` ` coding.  In particular, the software 
documentation needs to indicate GUI elements.  In HTML they would be 
rendered bold; in DocBook as .  It would be appropriate for the 
source text to read " open the :gui:`File` menu and choose :gui:`Save` ".
 A :role: transformer program would be overkill for this.  All that is 
needed is the ability to run an appropriate regex against the enclosed 
text, appropriate being defined by the destination file type.
 .. role:: html
        :gui:

     .. role:: docbook
        :gui:
 Note that DocUtils will need substitute the content of the interpreted 
text where the role label is shown.  Thus :gui:`File` becomes File 
and File, respectively.

     DocUtils will have to match its destination file type to the 
appropriate role substitution, of course.

 I think the ideas I have presented here will allow ReST to be used far 
more broadly.  It is currently at the very cusp of being used for general 
technical writing.  I believe that as long as ReST can be converted to 
DocBook XML, it stands a very good chance of becoming a "front-end" 
replacement for DocBook XML.  Not that I'm knocking DocBook, but it is 
often overkill for most purposes.

I am now subscribed to the doc-sig list, daily digest format.
 Please take a look at my sample file, http://www.sfu.ca/~priest/VRAS.zip , 
for a demonstration of ReSTs application in moderately complex print 
documentation for a hardware and software product.
 (there are some other gaps, but I see that they've been addressed by 
others.  Figure/Table autonumbering and referencing are a biggie.  I see 
that someone has suggested a naming convention to allow referencing, and 
the autonumbering shouldn't be any problem at all, so I anticipate a 
solution is on the way.)

Thanks for reading,
  david


From goodger@python.org  Sat Mar 15 06:01:25 2003
From: goodger@python.org (David Goodger)
Date: Sat, 15 Mar 2003 01:01:25 -0500
Subject: [Doc-SIG] Hello and feedback
In-Reply-To: 
Message-ID: 

David Priest wrote:
>  The two key missing puzzle-pieces are as follows:
>  - I am unable to insert Unicode character entities into the text.

As I recently wrote on the docutils-users mailing list,

    With Unicode and encodings available (UTF-8, Latin-1, etc.), we
    can directly code   as \u00A0 or \xA0.  Same with soft
    hyphens (­: \u00AD or \xAD), and any other Unicode character.
    This lessens (eliminates?) the need for the "escape sequence ->
    concrete character" kind of character processing.

    

Why are you unable to insert the actual, encoded characters into the
text?  What *are* you able to insert?  What encoding are your files
using?  What platform (OS, editor, etc.)?  It could be that you *can*
insert real characters but don't know it.

In any case, the world is moving inexorably towards Unicode.  I don't
see the point in complicating reStructuredText in order to duplicate
what can be had for free with properly encoded input files.

> Substitutions are the answer, so I've created a |subst|
> replace:&xAAA; table, as included in the zipfile.  Alas, the
> DocUtils insist on 
coding or &-substituting the replacement
> text.

XML character entities (&xNNNN;) are unknown to reStructuredText and
are the wrong way to do it.  Docutils is correct in substituting
"&" in HTML output for every "&" in the input file (how could it
tell the difference between *using* an XML character entity and just
*talking* about one?).

Your substitution table idea ought to work though, but you need to use
real characters instead of "&xNNNN;" in it.  Use a character encoding
that contains all the characters you want -- Latin-1 if that's enough,
your platform's native encoding (e.g. a Windows CP-* encoding), or
UTF-8 for full Unicode capability.  If your normal text editor can't
handle the encoding you choose, use Emacs or VIM; if you can't handle
them, get one of your programmers to help.  It will be limited to the
one file.

For this to work, the encoding of the substitution table file has to
be the same as that of the input file.  Alternatively, some work has
to be done on the Docutils code to allow different encodings.

Also, the "\ " (backslash-space) escape sequence trick (also
) needs to be
implemented to allow for character-level inline markup or
substitutions inside words.  The implementation should be easy.

>  - I am unable to use regex macros to manipulate the input text.
> There are two uses for this:
> 
>   1) To do standardized typographic replacement on naive-user's
> text.  For instance -- in print documentation -- the long dash, as I
> just used it, should be replaced using an em-dash surrounded by thin
> spaces.  This is a detail that no naive user should have to worry
> about: that's my job as technical writer.  Likewise, certain
> measurement units require marking-up: I'd like my naive users to
> write "36.8degrees" and get 36.8[degree sign], or 10m3 and get
> 10m[superscripted 3].
> 
>      .. use the formal en-dash with number ranges
>      .. regex:: ([0-9]+?)-([0-9]+?) = \1–\2

As I said in private email, at first glance,

    I doubt it [a regex substitution mechanism] will make its way into
    the Docutils/reStructuredText core.  Such a function could easily
    be handled by pre-processing though.  A script could convert ' -- '
    into a UTF-8 em-dash, etc.  Such a pre-processing system *could*
    be made part of Docutils, but separate from the core code I think.

I realize that there is a problem with pre-processing.  "10m3" inside
a paragraph and "10m3" inside a literal block or inline literal should
probably be handled differently, and a simple pre-processor would find
it difficult to differentiate.

Personally, I would go with an 80/20 auto/manual system.  Write a
quick script (or Emacs lisp function) to do the changes (convert
"10m3" to "10m\ :sup:`3`", for example) and verify manually.  If you
try to add this conversion to the processing pipeline (in whatever
form), there will someday be an exception where you *won't* want the
conversion to take place.

OTOH, if a good design appears and somebody implements it, who knows?
The idea needs a lot of fleshing out first though.  As with the
substitution table file idea, "–" is no good; it would have to
be a properly encoded en-dash character.

>      Note that the parenthesis in the prefix part of the equation
> indicate grouping: ...

I don't think we need a lesson in regular expression syntax, thanks.
;-)

>  If a file has a regex definition, it will be run before all other
> macros and substitutions, mais non?  I think so.

What "other macros"?  reStructuredText doesn't have macros.

>  2) To supplement the :role:` ` coding.  In particular, the software
> documentation needs to indicate GUI elements.  In HTML they would be
> rendered bold; in DocBook as .  It would be appropriate
> for the source text to read " open the :gui:`File` menu and choose
> :gui:`Save` ".
>  A :role: transformer program would be overkill for this.  All that
> is needed is the ability to run an appropriate regex against the
> enclosed text, appropriate being defined by the destination file
> type.

There's absolutely no need for any regex substitution here.  That's
exactly what the Writers are for.  The ":gui:`File`" input may become
"File" in the internal document tree.  The HTML Writer
would write it with bold (or, better yet, with ,
made bold by the stylesheet).  The DocBook Writer would write it with
.

There has been some discussion about parameterizing the interpreted
text system somehow, to avoid proliferation of element types (gui,
keypress, etc.).  No decision or action yet.

> (there are some other gaps, but I see that they've been addressed by
> others.  Figure/Table autonumbering and referencing are a biggie.  I
> see that someone has suggested a naming convention to allow
> referencing, and the autonumbering shouldn't be any problem at all,
> so I anticipate a solution is on the way.)

They're on the To Do list, but I don't know when they'll be
implemented.  Contributions welcome!
-- David Goodger    http://starship.python.net/~goodger

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



From priest@sfu.ca  Sat Mar 15 07:05:24 2003
From: priest@sfu.ca (David Priest)
Date: Fri, 14 Mar 2003 23:05:24 -0800
Subject: [Doc-SIG] Hello and feedback
In-Reply-To: 
References: 
Message-ID: 

I'm feeling that I've perhaps pissed in someone's cornflakes, but I'm going 
to respond anyways.  If I've offended, I apologize profusely:
no offense was intended.
 On Sat, 15 Mar 2003 01:01:25 -0500, David Goodger  
wrote:

> XML character entities (&xNNNN;) are unknown to reStructuredText and
> are the wrong way to do it.  Docutils is correct in substituting
> "&" in HTML output for every "&" in the input file (how could it
> tell the difference between *using* an XML character entity and just
> *talking* about one?).
 The charent pattern can be detected easily enough, and the "&" encoding
skipped for those entities.  If you want to talk about an entity directly, 
literalizing it would do the trick.  In all other cases the
ampersand can be safely encoded.
 But the substitution table using "proper" characters is good enough, 
although I'm not entirely sure that all backends output will be able to 
deal with two-byte Unicode.

> There's absolutely no need for any regex substitution here.  That's
> exactly what the Writers are for.  The ":gui:`File`" input may become
> "File" in the internal document tree.  The HTML Writer
> would write it with bold (or, better yet, with ,
> made bold by the stylesheet).  The DocBook Writer would write it with
> .
 The problem with implementing it as a Writer is that Writers don't
travel with the source text files.  If I send you a ReST file with :gui: 
roles in it, what's your DocUtils installation going to do with it?

> There has been some discussion about parameterizing the interpreted
> text system somehow, to avoid proliferation of element types (gui,
> keypress, etc.).  No decision or action yet.
  If "parameterizing the interpreted text system" means that simple role
substitutions -- the kind that can be handled by regex -- can be placed 
within the source text files, great!  It makes the source text more
portable.
  If the role can't be handled by a regex, then of course it's going to
require a Writer.  (Although... if one could embed a Python script...
but, no.  That's verging on silly.)
 And if this email has been scrunched into a blob, I apologize.  I assure
you that there are blank lines scattered throughout it.  I've tossed
extra space characters in them, too.  But my email client may still
toss them aside.  I have submitted a bug report.


From goodger@python.org  Sat Mar 15 15:55:09 2003
From: goodger@python.org (David Goodger)
Date: Sat, 15 Mar 2003 10:55:09 -0500
Subject: [Doc-SIG] Hello and feedback
In-Reply-To: 
Message-ID: 

[David Priest]
> I'm feeling that I've perhaps pissed in someone's cornflakes, but
> I'm going to respond anyways.  If I've offended, I apologize
> profusely: no offense was intended.

No offense perceived or taken.  We're just debating the technical
issues; nothing personal.  Sorry if it seemed too blunt, but email
tends to look that way.  I don't have the time to be super-friendly or
the inclination to sprinkle smilies throughout.  When discussing
issues via email, one needs a thick skin.  Assume that the writer is
smiling continuously, trying to help, which I was and am.

[David Goodger]
>> XML character entities (&xNNNN;) are unknown to reStructuredText and
>> are the wrong way to do it.  Docutils is correct in substituting
>> "&" in HTML output for every "&" in the input file (how could it
>> tell the difference between *using* an XML character entity and just
>> *talking* about one?).

>  The charent pattern can be detected easily enough, and the "&" encoding
> skipped for those entities.  If you want to talk about an entity directly,
> literalizing it would do the trick.  In all other cases the
> ampersand can be safely encoded.

By literalizing do you mean ``inline literals`` or literal blocks?
That's not always acceptable.  I might want to say

    The '&' entity is used by HTML and XML to
    represent the '&' character.

I shouldn't have to use inline literals here.

Docutils uses Unicode internally, and I don't see a need for it to
grow a character entity subsystem.  So far, you're the only one who
has asked for one, and that's not convincing enough.  I suspect that
you may be asking Docutils to cover a deficiency in your toolset, or
there's a misunderstanding.  Please answer these questions from my
last message to help clear this up:

    Why are you unable to insert the actual, encoded characters into
    the text?  What *are* you able to insert?  What encoding are your
    files using?  What platform (OS, editor, etc.)?  It could be that
    you *can* insert real characters but don't know it.

> But the substitution table using "proper" characters is good enough,
> although I'm not entirely sure that all backends output will be able
> to deal with two-byte Unicode.

HTML can handle UTF-8.  XML uses Unicode internally and assumes UTF-8
or UTF-16 unless told otherwise.  As for back-ends, that's a Writer
issue.  If output format X can't handle Unicode, then the X format's
Writer needs to encode those characters or signal an error.  TeX can't
handle the &#xNNNN; form.

Here's an alternative for you.  If you want to use &whatever; XML
character entities in your source, just put a simple filter into your
tool chain that converts those entities into UTF-8.  Something like::

    charents2utf8 input.txt | docutils/tools/html.py > output.html

There must be filters like that "out there".  If not, it wouldn't be
hard to write one, I think.  A codec would do just as well, but Python
doesn't come with such a codec (more's the pity).

I just realized the front-ends don't have support for explicit
stdin/stdout with "-" arguments.  I'll add that soon.

[re: interpreted text roles]
>> There's absolutely no need for any regex substitution here.  That's
>> exactly what the Writers are for.  The ":gui:`File`" input may
>> become "File" in the internal document tree.  The HTML
>> Writer would write it with bold (or, better yet, with > class="gui">, made bold by the stylesheet).  The DocBook Writer
>> would write it with .

> The problem with implementing it as a Writer is that Writers don't
> travel with the source text files.  If I send you a ReST file with
> :gui: roles in it, what's your DocUtils installation going to do
> with it?

The set of roles built into Docutils itself will grow.  If the growth
proves to be unlimited or unmanageable, there will have to be an
alternative.  If those roles are not handled by the default Docutils
set, then they can be local to your installation.  They wouldn't be
portable, true; there's only so far a "standard" can go and we can't
please everybody 100%.

There's also this alternative:

>> There has been some discussion about parameterizing the interpreted
>> text system somehow, to avoid proliferation of element types (gui,
>> keypress, etc.).  No decision or action yet.

See the Doc-SIG thread, "master plan for interpreted text?" from last
month.

> If "parameterizing the interpreted text system" means that simple
> role substitutions -- the kind that can be handled by regex -- can
> be placed within the source text files, great!  It makes the source
> text more portable.

But I doubt it will take the form of "regex substitutions".  That's
just too low-level, IMHO.

> If the role can't be handled by a regex, then of course it's going
> to require a Writer.  (Although... if one could embed a Python
> script... but, no.  That's verging on silly.)

Have you read PEP 256 & 258 yet?  Please do.  They explain the
Docutils architecture and the purpose of the components (Writer,
Reader, Parser, etc.).
 
> And if this email has been scrunched into a blob, I apologize.
 
Try leaving a space on each blank line.
I.e., [return] [space] [return].  I've done that just above.

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

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



From priest@sfu.ca  Sat Mar 15 23:27:54 2003
From: priest@sfu.ca (David Priest)
Date: Sat, 15 Mar 2003 15:27:54 -0800
Subject: [work] Re: [Doc-SIG] Hello and feedback
In-Reply-To: 
References: 
Message-ID: 

On Sat, 15 Mar 2003 10:55:09 -0500, David Goodger  
wrote:
> The '&' entity is used by HTML and XML to
> represent the '&' character.
>
> I shouldn't have to use inline literals here.

Personal preference, I suppose.  I'm already used to "escaping" entities 
when I'm writing about them directly, so I've no problem with the idea that 
I can't just write & willy-nilly through my document and expect it to 
display as such.

> Why are you unable to insert the actual, encoded characters into
> the text?  What *are* you able to insert?  What encoding are your
> files using?  What platform (OS, editor, etc.)?  It could be that
> you *can* insert real characters but don't know it.

*I* am able to insert the actual encoded characters into the text. There's 
no guarantee, however, that *others* are going to be able to see them.  
These docs are going to be edited on Windows, Mac, Linux, and BeOS boxes 
using whatever flavour of editor the end-user wants to use.

That's why we have charents in the first place: it lets anyone, using any 
old editor on any old OS, and print the raw document on any printer -- even 
an old 1978 daisywheel wordwhacker.

> [re: interpreted text roles]
>> The problem with implementing it as a Writer is that Writers don't
>> travel with the source text files.  If I send you a ReST file with
>> :gui: roles in it, what's your DocUtils installation going to do
>> with it?
>
> The set of roles built into Docutils itself will grow.  If the growth
> proves to be unlimited or unmanageable, there will have to be an
> alternative.  If those roles are not handled by the default Docutils
> set, then they can be local to your installation.  They wouldn't be
> portable, true; there's only so far a "standard" can go and we can't
> please everybody 100%.

I think that ReST has the opportunity to become a dominant markup standard. 
 I've suggested to Opera that they make it their standard for email markup, 
as HTML email is a sin against humanity.  The WikiWorld would do well to 
standardize on a single markup: it's very confusing to have to remember 
subtly different markups between various wikis. The ASCIIDoc author used 
his ST markup to create his website, and I've pointed him toward ReST as a 
direction for his ST project. And I'm intent on using ReST for my technical 
documentation.

In the technical writing world DocBook is often overkill, especially when 
attempting collaborative work with naive users.  The XML is complex, 
virtually requiring a DTD-aware editor, and patient study of the spec.  
ReST is nearly a perfect solution: it's intuitive, simple, and can be 
written using even a PDA.

I hope I'm coming at this from a different angle than the rest of you, 
because that way I'll be able to contribute another view on how ReST can be 
used to best effect.

I think one of the best ways to encourage wide adoptation is to make it as 
easy as possible for functionality to be implemented within the source text 
files.  It's going to be next to impossible to keep up with everyone's 
various ideas for roles.  The more that a role's functionality can be put 
into a text sourcefile, the easier it is to share one's documents.


From aahz@pythoncraft.com  Sun Mar 16 00:26:19 2003
From: aahz@pythoncraft.com (Aahz)
Date: Sat, 15 Mar 2003 19:26:19 -0500
Subject: [work] Re: [Doc-SIG] Hello and feedback
In-Reply-To: 
References:  
Message-ID: <20030316002619.GB9482@panix.com>

On Sat, Mar 15, 2003, David Priest wrote:
>
> I hope I'm coming at this from a different angle than the rest of you,
> because that way I'll be able to contribute another view on how ReST
> can be used to best effect.

No, your attitude is similar to mine, but it sounds like you've got a
lot more experience as a tech writer with which to express your opinion.
-- 
Aahz (aahz@pythoncraft.com)           <*>         http://www.pythoncraft.com/

Register for PyCon now!  http://www.python.org/pycon/reg.html


From goodger@python.org  Sun Mar 16 01:09:08 2003
From: goodger@python.org (David Goodger)
Date: Sat, 15 Mar 2003 20:09:08 -0500
Subject: [work] Re: [Doc-SIG] Hello and feedback
In-Reply-To: 
Message-ID: 

[David Goodger]
>>      The '&' entity is used by HTML and XML to
>>      represent the '&' character.
>> 
>> I shouldn't have to use inline literals here.

[David Priest]
> Personal preference, I suppose.

It's practicality.  In many of my documents, I (and, I imagine, other
authors) write *about*  and &entities; and other uses of these
characters.  Some people write "&c" instead of "etc".  Should the parser
generate an error for this?  I think not.

>> Why are you unable to insert the actual, encoded characters into
>> the text?  What *are* you able to insert?  What encoding are your
>> files using?  What platform (OS, editor, etc.)?  It could be that
>> you *can* insert real characters but don't know it.
> 
> *I* am able to insert the actual encoded characters into the text. There's
> no guarantee, however, that *others* are going to be able to see them.
> These docs are going to be edited on Windows, Mac, Linux, and BeOS boxes
> using whatever flavour of editor the end-user wants to use.

So ASCII is your lowest common denominator?  I sympathize, but maintain that
Docutils doesn't need a character entity subsystem.  Your idea of a
substitution table file will work fine, and since *you* have control of it,
encoding it as UTF-8 shouldn't be a problem (and you can treat everything
else as UTF-8 since it's a strict superset of 7-bit ASCII).  Just change the
table from this form::

    .. exclamation point:
    .. |excl| replace:: !

to this form::

    .. exclamation point:
    .. |excl| replace:: !

I.e., use the concrete characters.

I just realized there's a problem: reStructuredText is case-insensitive, so
É and é will clobber each other.  You'll either have to come
up with a different name scheme, or perhaps the parser can be changed to be
case-sensitive-but-forgiving for substitution names.  I think that change is
feasible, but I haven't thought through the consequences.

> I hope I'm coming at this from a different angle than the rest of you,
> because that way I'll be able to contribute another view on how ReST can be
> used to best effect.

Your contributions are most welcome.  Just don't expect every idea to be
adopted. :-)

> I think one of the best ways to encourage wide adoptation is to make it as
> easy as possible for functionality to be implemented within the source text
> files. 

I'm very leery of making reStructuredText into a programming language or
meta-markup language.  Simplicity is one of its strengths, and the existing
extension mechanisms (directives, interpreted text roles, substitutions) are
already more than complex enough.

> It's going to be next to impossible to keep up with everyone's
> various ideas for roles.

Perhaps.  But I'm not going to implement a solution until it's the *right*
solution.  Regexes ain't it, sorry :-).

> The more that a role's functionality can be put
> into a text sourcefile, the easier it is to share one's documents.

I'd rather put the functionality into Docutils itself.

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

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



From priest@sfu.ca  Sun Mar 16 02:34:10 2003
From: priest@sfu.ca (David Priest)
Date: Sat, 15 Mar 2003 18:34:10 -0800
Subject: [Doc-SIG] Hello and feedback
In-Reply-To: <20030316002619.GB9482@panix.com>
References:   <20030316002619.GB9482@panix.com>
Message-ID: 

On Sat, 15 Mar 2003 19:26:19 -0500, Aahz  wrote:

> On Sat, Mar 15, 2003, David Priest wrote:
>>
>> I hope I'm coming at this from a different angle than the rest of you,
>> because that way I'll be able to contribute another view on how ReST
>> can be used to best effect.
>
> No, your attitude is similar to mine, but it sounds like you've got a
> lot more experience as a tech writer with which to express your opinion.

Experience writing end-user docs for hardware and software, not experience 
in writing docs for APIs, PEPs, and the like.


From priest@sfu.ca  Sun Mar 16 07:52:05 2003
From: priest@sfu.ca (David Priest)
Date: Sat, 15 Mar 2003 23:52:05 -0800
Subject: [work] Re: [Doc-SIG] Hello and feedback
In-Reply-To: 
References: 
Message-ID: 

On Sat David Goodger  wrote:
> Some people write "&c" instead of "etc".  Should the parser
> generate an error for this?  I think not.

Just a quick note: &c doesn't fall into the charent pattern.

So we're down to inconviencing one of two groups.

In group one, those who are writing anything involving extended characters 
(ie. mathematics, physics, papers with the occasional foreign word) will 
need to consult a lookup table to figure out what ALT+keypad combination 
will create the character they want, and will not be able to use just any 
old editor; but those writing about XML and such will be able to refer to 
charents without having to use ``&name;`` escaping.

In group two, those writing about XML and such will have to use ``&name;`` 
escaping, but everyone else will be able to use charents to insert the 
occassional extended character into their work and use any editor they care 
to use.

I know which group I want to belong to, but then I don't spend a lot of 
time writing about charents.

But it doesn't really matter: I can get the substitution table to work, so 
the problem is resolved.

Much to your relief, I'll drop the matter now.


From goodger@python.org  Sun Mar 16 17:04:47 2003
From: goodger@python.org (David Goodger)
Date: Sun, 16 Mar 2003 12:04:47 -0500
Subject: [work] Re: [Doc-SIG] Hello and feedback
In-Reply-To: 
Message-ID: 

> On Sat David Goodger  wrote:
>> Some people write "&c" instead of "etc".  Should the parser
>> generate an error for this?  I think not.

David Priest wrote:
> Just a quick note: &c doesn't fall into the charent pattern.

It does if followed by a semicolon.

Splitting hairs can be dangerous; may result in a chain reaction.

> Much to your relief, I'll drop the matter now.

Good.

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

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



From grubert@users.sourceforge.net  Mon Mar 17 08:52:14 2003
From: grubert@users.sourceforge.net (grubert@users.sourceforge.net)
Date: Mon, 17 Mar 2003 09:52:14 +0100 (CET)
Subject: [work] Re: [Doc-SIG] Hello and feedback
In-Reply-To: 
References:  
Message-ID: 

On Sat, 15 Mar 2003, David Priest wrote:

> I think one of the best ways to encourage wide adoptation is to make it as
> easy as possible for functionality to be implemented within the source text
> files.  It's going to be next to impossible to keep up with everyone's
> various ideas for roles.  The more that a role's functionality can be put
> into a text sourcefile, the easier it is to share one's documents.

BUT: this needs to thought out very well, because he more functionality is in
the source text, the more problems might arise having compatibility issues.

and of course this might interfere with separation of content and format.

OTOH: much might be done by preprocessor postprocessor and plugins.
* a preprocessor simply fixes some special constructs and emits reST.
  if this is successful it might become a new reader.
* postprocessing is similar but specialiced to the writer the preceeds it.
  on success make it a writer (option).
* a plugin might be considered an external transform:
  might be done by two stage docutils:
  1. reST to xml (or even the pickled internal data)
  2. custom xml processing
  3. xml to whatever writer might fit.
  on success becomes a transform ?



-- 
 BINGO: Wie gehts Ihnen mit ...?
 --- Engelbert Gruber -------+
 SSG Fintl,Gruber,Lassnig   /
 A6410 Telfs Untermarkt 9  /
 Tel. ++43-5262-64727 ----+


From priest@sfu.ca  Mon Mar 17 16:09:59 2003
From: priest@sfu.ca (David Priest)
Date: Mon, 17 Mar 2003 08:09:59 -0800
Subject: [work] Re: [Doc-SIG] Hello and feedback
In-Reply-To: 
References:   
Message-ID: 

 wrote:
>
> OTOH: much might be done by preprocessor postprocessor and plugins.
> * a preprocessor simply fixes some special constructs and emits reST.
> if this is successful it might become a new reader.
> * postprocessing is similar but specialiced to the writer the preceeds 
> it.
> on success make it a writer (option).
> * a plugin might be considered an external transform:
> might be done by two stage docutils:

It's worth checking out ASCIIDoc.  It was within a hair of being just 
enough functionality to allow me to do my technical publications with it.  
If it had had tables support, I probably would have stopped my search 
there.
 ASCIIDoc uses a config file to move some simple functionality out of the 
program, but at the same time keep it out of the source text files.  This 
includes substitutions (word, character, and tag) and regex macros.  It was 
the regex macro capability that made it possible to arbitrarily extend 
ASCIIDoc for my needs, without modifying the application installation.
 Anyway, I think Steve's ASCIIDoc has some ideas worth stealing.  I 
especially like his comments, sidebars, and boxes markup.  Most intuitive.


From priest@sfu.ca  Mon Mar 17 22:06:11 2003
From: priest@sfu.ca (David Priest)
Date: Mon, 17 Mar 2003 14:06:11 -0800
Subject: [Doc-SIG] Substitutions, encoding results
Message-ID: 

My substitution file nears completion.  I'll pass it on when I'm done.

So far using substition to insert characters by name more or less works.  
There are a few problems:

1) Some important Unicode characters can not be substituted.  This includes 
several variety of spaces and all the arrow characters.

2) Substitutions can not be against non-white space.  Thus you can not use 
a |sup3| substitution in your text.  You also can not emphasize 
substitutions.

I'll take a look at the code and see if there are obvious solutions to 
these two problems.


From priest@sfu.ca  Thu Mar 20 21:17:16 2003
From: priest@sfu.ca (David Priest)
Date: Thu, 20 Mar 2003 13:17:16 -0800
Subject: [Doc-SIG] CharEnt support in HTML4css1.py
References: 
Message-ID: <20030320211717.TMZN29647.priv-edtnes12-hme0.telusplanet.net@TOSH>

The following replacement code allows HTML4css1.py to support the use of 
charents.  It can be easily adapted to the other writers, I'm sure.

    def encode(self, text):
        """Encode special characters in `text` & return."""
        # @@@ A codec to do these and all other HTML entities would be 
nice.
#        text = text.replace("&", "&")
        # match standard charent forms (&NUM; &xHEXNUM; and &namedEntity;)
        text = re.sub(r'&(?!(([a-zA-Z]{2,};)|(#(x|X)?[0-9a-fA-F]{2,4};)))', 
r'&', text)
        text = text.replace("<", "<")
        text = text.replace('"', """)
        text = text.replace(">", ">")
        text = text.replace("@", "@") # may thwart some address 
harvesters
        return text



From priest@sfu.ca  Thu Mar 20 21:47:10 2003
From: priest@sfu.ca (David Priest)
Date: Thu, 20 Mar 2003 14:47:10 -0700
Subject: [Doc-SIG] Technical Writing sample updated
Message-ID: <20030320214710.SWBG9999.priv-edtnes27.telusplanet.net@TOSH>

I've updated my sample real-world document.  It provides a fairly 
comprehensive test of ReSTs applicability to professional print 
documentation.  There are tables, mathematical equations, figures, and 
such.

You can get the file at http://www.sfu.ca/~priest/VRAS.zip

Included in the file is a modified HTML4css1.py script which allows the use 
of HTML/XML character entities (ie. mathematical symbols).

I have not completed my work on adapting this manual to ReST.  In 
particular, I have not encoded user interface labels (ie. menu commands and 
keyboard shortcuts), have not double-checked for consistency in use of 
emphasis and spacing around equations, and have not adapted all the 
graphics files.

If I continue to work on this sample my next step will be to implement 
:gui: and :key: roles.  In HTML they would be rendered as bold; in DocBook 
as  and  tags.




From goodger@python.org  Sat Mar 22 06:13:17 2003
From: goodger@python.org (David Goodger)
Date: Sat, 22 Mar 2003 01:13:17 -0500
Subject: [Doc-SIG] support for character-level inline markup added to reStructuredText
Message-ID: <3E7BFEFD.30009@python.org>

Example:

     Possible in *re*\ ``Structured``\ *Text*, though not encouraged.

See it in action near the end of the first paragraph in section 2.1.1 of 
.

Gory details:
.
Please especially note the admonition cautioning against abuse of this
ugly feature.

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

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



From goodger@python.org  Sat Mar 22 06:24:21 2003
From: goodger@python.org (David Goodger)
Date: Sat, 22 Mar 2003 01:24:21 -0500
Subject: [Doc-SIG] CharEnt support in HTML4css1.py
In-Reply-To: <20030320211717.TMZN29647.priv-edtnes12-hme0.telusplanet.net@TOSH>
References:  <20030320211717.TMZN29647.priv-edtnes12-hme0.telusplanet.net@TOSH>
Message-ID: <3E7C0195.50601@python.org>

David Priest wrote:
> The following replacement code allows HTML4css1.py to support the use of 
> charents.

Unfortunately this code has a fatal side-effect.  The HTML Writer runs 
all text is run throught the HTMLTranslator.encode method, even that of 
inline literals () and literal blocks.  Ignoring XML-style 
character entities ("&example;") would make it impossible to even 
*discuss* such entities in documents without jumping through hoops; not 
even ``&this;`` would be immune from being ignored.

The addition of character-level inline markup support to the parser 
should enable you to implement the substitution table file scheme we 
discussed earlier.

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

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



From pearu@cens.ioc.ee  Sun Mar 23 22:26:43 2003
From: pearu@cens.ioc.ee (Pearu Peterson)
Date: Mon, 24 Mar 2003 00:26:43 +0200 (EET)
Subject: [Doc-SIG] Choosing a language?
Message-ID: 

Hi,

Q: How to specify in a rst document the language of its contents?

I have rst documents in Estonian language and I have prepared
docutils/languages/et.py file but I could not find out how to enable it.  
In case languages cannot be specified in rst documents, here follows a
codelet that I am using to transform documents:

  import docutils.core
  docutils.core.publish_file(source_path = src_name,
                             destination_path = dest_name,
                             reader_name='standalone',
                             parser_name='restructuredtext',
                             writer_name='html',
                             )

TIA,
	Pearu



From dave@boost-consulting.com  Sun Mar 23 03:51:39 2003
From: dave@boost-consulting.com (David Abrahams)
Date: Sat, 22 Mar 2003 22:51:39 -0500
Subject: [Doc-SIG] Re: support for character-level inline markup added to
 reStructuredText
References: <3E7BFEFD.30009@python.org>
Message-ID: 

David Goodger  writes:

> Example:
>
>      Possible in *re*\ ``Structured``\ *Text*, though not encouraged.
>
> See it in action near the end of the first paragraph in section 2.1.1
> of .
>
> Gory details:
> .
> Please especially note the admonition cautioning against abuse of this
> ugly feature.

Thank you thank you thank you thank you!!
My wife thanks you too.

-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com



From goodger@python.org  Thu Mar 27 04:04:22 2003
From: goodger@python.org (David Goodger)
Date: Wed, 26 Mar 2003 23:04:22 -0500
Subject: [Doc-SIG] Substitutions, encoding results
In-Reply-To: 
References: 
Message-ID: <3E827846.8030605@python.org>

David Priest wrote:
> My substitution file nears completion.  I'll pass it on when I'm done.

Please do.  I have just made substitutions case-sensitive but forgiving, 
falling back to case-insensitive matches whenever necessary.  Now 
"|eacute|" and "|Eacute|" can have distinct definitions and references.

> So far using substition to insert characters by name more or less 
> works.  There are a few problems:
> 
> 1) Some important Unicode characters can not be substituted.

Why not?

> 2) Substitutions can not be against non-white space.  Thus you can not 
> use a |sup3| substitution in your text.  You also can not emphasize 
> substitutions.

The recent addition of disappearing escaped whitespace should have 
solved this one.

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

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



From priest@sfu.ca  Thu Mar 27 16:34:39 2003
From: priest@sfu.ca (David Priest)
Date: Thu, 27 Mar 2003 08:34:39 -0800
Subject: [Doc-SIG] Unicode Charent Substitutions
In-Reply-To: <3E83263E.3040908@python.org>
References:  <3E827846.8030605@python.org>  <3E83263E.3040908@python.org>
Message-ID: 

The Unicode "charent" substitions file is available at

http://www.sfu.ca/~priest/ReST_Unicode_Substitutions.txt

It contains |substitutions| for various mathematical, Greek, punctuation, 
and miscellaneous symbols.  It requires the latest DocUtils beta, which 
supports the use of upper-and lower-case distinctive names in a 
substitution (ie. |Alpha| and |alpha| are different substitutions).

You'll frequently need to use the disappearing-space escape convention to 
use these substitutions correctly, ie.) "100\ |deg|\ C" to create 100°C (I 
think!).



From smerten@oekonux.de  Thu Mar 27 20:06:00 2003
From: smerten@oekonux.de (Stefan Merten)
Date: Thu, 27 Mar 2003 21:06:00 +0100
Subject: rest-mode.el and more (was: Re: [Doc-SIG] reStructuredText: What a cool idea!!)
In-Reply-To: Your message of "Wed, 26 Feb 2003 23:39:34 EST"
 
Message-ID: <200303272006.h2RK60906080@rosalu.merten-home.de>

-----BEGIN PGP SIGNED MESSAGE-----

Hi David and all!

Sorry for the delay but lately I have been too busy with other things
to code :-( .

Last month (28 days ago) David Goodger wrote:
> Stefan Merten wrote:
>> * Is there a Perl implementation already? Does anybody plan such a
>>   beast?
>=20
> Mark Nodine  is working on a Perl
> implementation of the reStructuredText parser.  He hasn't released any
> code yet, though.

Ok, so it's probably better to wait for some code from Mark while not
holding breath ;-) .

>> * Is there a Emacs mode already?
>=20
> Not yet.  There are a few functions in
> tools/editors/emacs/restructuredtext.el, available from CVS or the
> snapshot ().

Yes. This could and should be integrated with my work then.

>>   Particularly it there `font-lock'
>>   support for reStructuredText documents available?
>=20
> No.  It's an interesting idea, although I'm not sure how it would
> work.

I coded a font-lock mode which recognizes most reST constructs. I
checked it with

	http://docutils.sourceforge.net/spec/rst/reStructuredText.txt

and it worked pretty good.

At the moment blocks are not handled. For the most part this is no
problem, but comments, section headers, and literal blocks should
really be font-locked correctly. Also definition lists are not
font-locked yet. Apart from that it is not clear whether it makes
sense to font-lock tables. Everything else should work fine.
Everything missing is marked in the code by ``FIXME``.

I already played around a bit with font-locking for comment blocks,
but this is a bit difficult.

>>   If no such thing is available I could give it a try.
>=20
> Please do!

:-)

You can download it from

	http://www.merten-home.de/FreeSoftware/rest-mode/index.html

I tried it with Emacs 20 and Emacs 21. XEmacs 21 did not like
everything as it seems :-( . But for sure it's a start.

If you want to include it in an official CVS tree that's fine.
However, please contact me so I can continue to maintain it or we can
look for other arrangements.

Please note that in the file I'm suggesting file name extensions
``.rest`` and ``.reST`` for reStructuredText documents. I don't know
whether there is a widely accepted extension already. However, I think
there should be one.

Also take care about the mode settings at the end of for instance

	http://docutils.sourceforge.net/spec/rst/reStructuredText.txt

This conflicts with automated settings depending on the file name.

>> * Are there transformation tools from OpenOffice format to
>>   reStructuredText?
>=20
> There is work being done on OpenOffice.org XML *writers*, but nothing
> to my knowledge the other way.
>=20
>>   For SDF lately I created a suite of XSLT style sheets which
>>   transform the `styles.xml' and `content.xml' contained in `.sxw'
>>   and `.sxc' to SDF. Though this involves some post processing by
>>   hand it is *much* easier than anything I did before.
>=20
> Sounds like a good approach.  I've heard of people setting up
> semi-automated systems to assist with conversion.
>=20
>>   Of course I'd like to see this for reStructuredText as well. If
>>   no-one did this until know, I could rewrite my XSLT scripts a bit
>>   to support reStructuredText.
>=20
> Such code would be welcome.

:-)

Now font-locking turned the light on ;-) I'll work on that.

>> * Is there a transformation for Docutils Document Tree documents in
>>   XML to a reStructuredText source form? Or following PEP 258: Is
>>   there a writer for reStructuredText?
>=20
> There has been some discussion about a generic to-reStructuredText
> conversion system, perhaps a Docutils "Writer", but no implementation
> yet.

I'd find it useful because then one could use the XML format as a
general intermediate format.

>> * Are there plans to support embedded code in reStructuredText
>>   documents?
>=20
> I believe Mark Nodine's Perl implementation has it.

Perl people seem to like that ;-) .

> There are notes
> about at .  Such a
> feature is inherently dangerous though, and there have to be
> safeguards in place to prevent reStructuredText/Docutils being used as
> a vector for viruses & trojans.

Yes, security will be an issue then. May be it could help to have any
code execution switched off by default and code is only executed when
this is switched on explicitly.

>> * Are there writers for plain text and/or manual pages?
>=20
> Not that I know of.  I recall some discussion, but nothing concrete.

I'd find that great - particularly for manual pages.

Hmm... While thinking about it: It would suffice to have a writer for
POD. This way you'll indirectly have a writer for manual pages for
free.

>> Finally I'd like to draw your attention to
>>=20
>>     http://template-toolkit.org/
>=20
> Looks useful, but templating systems are plentiful.
>=20
>> One thing I particularly liked with SDF is the feature to embed SDF
>> or other stuff in anything which supports comments. This way you
>> were able to embed for instance POD documentation in a C++ file. One
>> of the nice features is, that it rearranges the embedded code
>> allowing you to write your documentation at the place of the
>> definition and nonetheless get every piece of documentation at the
>> right place in the final document.
>=20
> Sounds like "literate programming".  Do you have a link to a
> description of how SDF accomplishes this rearranging?

This was solved fairly easy. The extractor (``sdfget``) used a table
like this::

  Key           Format
  NAME          "=3Dhead1 $key\n\n$data\n\n"
  SYNOPSIS      "=3Dhead1 $key\n\n$data\n\n"
  DESCRIPTION   "=3Dhead1 $key\n\n$data\n\n"
  OPTIONS       "=3Dhead1 $key\n\n$data\n\n"
  FEATURES      "=3Dhead1 $key\n\n$data\n\n"
  EXAMPLE       "=3Dhead1 $key\n\n$data\n\n"
  EXAMPLES      "=3Dhead1 $key\n\n$data\n\n"
  RETURN VALUES "=3Dhead1 $key\n\n$data\n\n"
  EXIT STATUS   "=3Dhead1 $key\n\n$data\n\n"
  DIAGNOSTICS   "=3Dhead1 $key\n\n$data\n\n"
  ENVIRONMENT   "=3Dhead1 $key\n\n=3Dover 4\n\n$data\n\n=3Dback\n\n"
  FILES         "=3Dhead1 $key\n\n=3Dover 4\n\n$data\n\n=3Dback\n\n"
  PREREQUISITES "=3Dhead1 $key\n\n$data\n\n"
  SEE ALSO      "=3Dhead1 $key\n\n$data\n\n"
  AUTHOR        "=3Dhead1 $key\n\n$data\n\n"
  LICENSE       "=3Dhead1 $key\n\n$data\n\n"
  AVAILABILITY  "=3Dhead1 $key\n\n$data\n\n"
  NOTES         "=3Dhead1 $key\n\n$data\n\n"
  BUGS          "=3Dhead1 $key\n\n$data\n\n"

The table is given in an extra report file given as an argument to
``sdfget``. The ``Key`` column gives some keys to be recognized in
your source code while the ``Format`` column gave the format to be
used as a Perl string. ``$key`` was the ``Key`` from the first column
while ``$data`` was the data contained in *all* sections tagged with
the respective key. As you may have recognized the above table
transforms to POD snippets forming a manual page.

Then in the source you can write things like that::

  #>>NAME::
  #
  # rest-mode - An Emacs mode for reStructuredText documents

  #>>AUTHOR:: Stefan Merten 

  #>>SYNOPSIS::
  #
  # B I