Mailman 3 March 2003 - Doc-SIG

reStructuredText: What a cool idea!!
by Stefan Merten April 2, 2003

April 2, 2003

-----BEGIN PGP SIGNED MESSAGE----- Hi hackers and others, first of all I'd like to apologize if this is off-topic on this list. If so it would be nice if someone could tell me, where this belongs to. I don't know whether you already know, but reStructuredText is mentioned on http://www.ibm.com/developerworks/library/x-matters24/ I saw it there, read the specification and some more - and I'm absolutely delighted :-) !! First, I'd like to tell you a bit about my background. I love the Perl idea of embedding documentation in the source code using POD. To me it became a habit documenting everything while or often even before coding something. I guess that was, what Larry had in mind when inventing POD :-) . Another nice aspect of POD is, that it's ASCII based and thus it is useful to use CVS on it and/or the miracles of the Emacs' ediff package. And of course you do not need any special editor to work with this format. Instead every editor supporting plain ASCII works. And nonetheless you can produce lots of output formats. By a simple `make' call if you like. All in all POD allowed for a lot of nice features with a high degree if automatization, versioning and so on. So I started to write all my documents in POD. However, POD is a rather limited markup format. If you want to write something different from a manual page you'll immediately run into a number of limitations. So I looked for an alternative. I found SDF [http://search.cpan.org/author/IANC/sdf-2.001/, the original site doesn't exist any more but it is embedded in the package]. SDF is a rather great tool very much in the spirit of reStructuredText. One feature I particularly like is, that it is possible to embed (Perl) code in your text document to do some very specific job. Anyway it is easy to combine SDF with Perl to create really great stuff. The most elaborated thing I did with SDF were some filters which take a high level interface description for an API and produce include files for C, C++, Sicstus Prolog, and Java. Well, since I discovered SDF I'm using SDF for nearly everything. In particular the web sites I'm maintaining are all created by SDF and `make'. However, SDF has a number of drawbacks: * The code is based on Perl 4 (before references were invented in Perl) and it's - ummm - somewhat ugly. I thought about rewriting it from scratch but I've got no time for such a task. * There is a great number of nice ideas but there is not much of an overall concept. * No community developed - at least no community visible to me. This may be partly because the maintainer Ian Clatworthy (thanks Ian for all of your efforts) seemingly gave up the project shortly after I discovered it (in 1999). (I never contacted him, so I could not have been the reason ;-) .) * It did not reach a wide distribution and thus virtually nobody is used to using it. So though personally I'm rather happy with SDF I don't like the thought of being trapped in a evolutionary dead end. And now I found reStructuredText. I read the specification and though today reStructuredText misses some things of what SDF has, I see that there is a potential for reStructuredText for being a very powerful tool - much more than SDF ever was. Particularly because there seems to be an active maintainer (thanks David Goodger and all for the *great* web site, I particularly like that the discussion of alternatives is listed) and seemingly a very interested community. Personally I think it would be a great gift to the world to establish a text format which is easy to write but yet powerful. In short: I fully support all the goals listed for reStructuredText. I think over time I'll reformat all my sources to use reStructuredText. Ahmm - as you may have noted I'm coming from the Perl community and I don't know Python yet and at the moment I'm not planning to change that. But when talking about a format this is of little importance of course. Well, now you know why I'm here :-) . Now for the question part of this mail. Indeed I have a number of questions about reStructuredText and it's implementation. I'm sorry if any of these questions is already answered on one some web page. I did not read all of the pages yet. * Is there a Perl implementation already? Does anybody plan such a beast? Admittedly I thought of doing it - but my time is *very* limited :-( . However, that's a itch I'd like to scratch. * Is there a Emacs mode already? Particularly it there `font-lock' support for reStructuredText documents available? Personally I got used so much to font-locking I find it an unbearable pain to read text containing formal syntax without appropriate coloring. If no such thing is available I could give it a try. * Are there transformation tools from OpenOffice format to reStructuredText? This question may need some explanation. I have the problem, that sometimes I receive M$ `.doc's and `.ppt's or `.rtf's I'd like to transform to SDF to embed them in a web site. Before OpenOffice and it's XML based document format this was a difficult task needing a lot of unautomatable work. I wrote a tool for RTF but Powerpoint was beyond automatization. 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. In effect by (ab)using the input filters of OpenOffice I now have a whole lot of formats I can transform to SDF with reasonable effort. 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. * 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? If so the Docutils Document Tree could be used as an XML based representation and all the nice things of XML are available. For instance one could write an XSLT transformation from an OpenOffice format to Docutils Document Tree format and transformations in all thinkable directions are possible. * Are there plans to support embedded code in reStructuredText documents? The embedded code needs access to the embedding document of course. May be this is similar to JavaScript embedded in HTML pages. Of course I'd prefer support for Perl ;-) . * Are there writers for plain text and/or manual pages? Finally I'd like to draw your attention to http://template-toolkit.org/ It's a very cool tool which allows for a wide range of automation. It virtually adds a powerful macro language to every ASCII based format. 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. However, as SDF is usually not available this feature is of limited use if you're going to share your source with others :-( . In the free software project I started lately [http://savannah.nongnu.org/projects/mamo/] I created a plug-in for the Template Toolkit which exactly does this sort of gathering of snippets of documentation from an arbitrary source file [http://savannah.nongnu.org/cgi-bin/viewcvs/mamo/mamo/lib/perl5/Mamo/Templat…]. Thinking reStructuredText and Docutils it might qualify as the input part of a reader. Mit Freien Grüßen Stefan -----BEGIN PGP SIGNATURE----- Version: 2.6.3in Charset: noconv Comment: Processed by Mailcrypt 3.5.7, an Emacs/PGP interface iQCVAwUBPlqjdAnTZgC3zSk5AQGjVgQArL3NYg0OThGf7Xi++LJPUgKnS0HyRfT6 bek6sjLiYOSfDLQPFAfWjeVhRKaMt4P+nKhIqVPuT/Jfe3nj/LgxTOMdWspjE7gU CT6VA2qKNpuAAvoIc9BoW9nL4bQE3fgnETENtdZROlg4kiQLwGKzTr1VWs+uLvqt nSzPi3EddpI= =alwL -----END PGP SIGNATURE-----

3 6

Wikis using reST
by Brett Cannon March 30, 2003

March 30, 2003

Someone asked me, and Kevin Altis suggested here at PyCon that wikis use reST for syntax. Are there currently any wikis using reST? Obviously MoinMoin is the obvious preference, but since I am just a user and not developer of both reST and MoinMoin I am just dropping the suggestion. -Brett

6 6

Choosing a language?
by Pearu Peterson March 27, 2003

March 27, 2003

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

2 1

Unicode Charent Substitutions
by David Priest March 27, 2003

March 27, 2003

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!).

1 0

Substitutions, encoding results
by David Priest March 26, 2003

March 26, 2003

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.

2 1

support for character-level inline markup added to reStructuredText
by David Goodger March 24, 2003

March 24, 2003

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 <http://docutils.sf.net/tools/test.html#inline-markup>. Gory details: <http://docutils.sf.net/spec/rst/reStructuredText.html#character-level-inlin…>. 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

2 1

Hello and feedback
by David Priest March 21, 2003

March 21, 2003

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 <PRE>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 <guilabel>. 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 <B>:gui:</B> .. role:: docbook <guilabel>:gui:</guilabel> Note that DocUtils will need substitute the content of the interpreted text where the role label is shown. Thus :gui:`File` becomes <B>File</B> and <guilabel>File</guilabel>, 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

4 13

Technical Writing sample updated
by David Priest March 20, 2003

March 20, 2003

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 <guilabel> and <keycap> tags.

1 0

Slides for reST PyCon tutorial
by Brett Cannon March 12, 2003

March 12, 2003

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

2 1

Pferdemarkt.ws informiert! Newsletter 03/2003 http://www.pferdemarkt.ws
by webmaster＠pferdemarkt.ws March 6, 2003

March 6, 2003

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(a)pferdemarkt.ws

1 0