docutils-users Mailing List for Docutils: Documentation Utilities

El 29/12/10 19:00, Christophe Delord escribió:
> Le 29/12/2010 22:50, lu...@gm... a écrit :
>> Helo friends...
> 
> Hello,
> 
>> Bt, is there any option to *get the original rst file* of the docs that
>> are in the site?
>> IE. de rst of *
>> http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html * ??
>>
> There is a link at the bottom of the page 
> (http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.txt)
> 
> Regards,
> Christophe.
> 
Thanks!!!! Wonderfull... Sorry, I don't read it... I don't click there.. :(

I thonk I need some *oil* to my mind !!!
Happy Crist. and New Year from Pigüé - ARG.

Rolfox

On 2010-12-29, lu...@gm... wrote:

> Bt, is there any option to *get the original rst file* of the docs that
> are in the site?

There are "see source" links for almost all of the documentation.
(BTW, the source files match *.txt not *.rst.)

> IE. de rst of *
> http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html * ??

You might have hit the exception to the above rule: the only one
hand-crafted HTML file without rst source, though.

Günter

Le 29/12/2010 22:50, lu...@gm... a écrit :
> Helo friends...

Hello,

> Bt, is there any option to *get the original rst file* of the docs that
> are in the site?
> IE. de rst of *
> http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html * ??
>
There is a link at the bottom of the page 
(http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.txt)

Regards,
Christophe.

On Wed, Dec 29, 2010 at 06:50:02PM -0300, lu...@gm... wrote:
> Bt, is there any option to *get the original rst file* of the docs that
> are in the site?
> IE. de rst of *
> http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html * ??

See the link in the footer. Ie.
http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.txt

> I think I learn  much more if I get the source.

Good luck,


--Berend



> ------------------------------------------------------------------------------
> Learn how Oracle Real Application Clusters (RAC) One Node allows customers
> to consolidate database storage, standardize their database environment, and, 
> should the need arise, upgrade to a full multi-node Oracle RAC database 
> without downtime or disruption
> http://p.sf.net/sfu/oracle-sfdevnl
> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
> 
> Please use "Reply All" to reply to the list.


-- 
 :e: be...@do...
 :t: +31(0)6 - 19160770
 :w: - http://services.dotmpe.com/
     - http://www.linkedin.com/pub/13/261/286

Helo friends...

I' m using/learning/ and so on rst...

I look in the site * http://docutils.sourceforge.net/rst.html * , I
read, download somethings...

Bt, is there any option to *get the original rst file* of the docs that
are in the site?
IE. de rst of *
http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html * ??

I think I learn  much more if I get the source.

Best for you

Rolfox

I'm using docutils programmatically for converting ReST to HTML (specifically
docutils.core.publish_from_doctree). Since the usage is programmatic (controlled
by my application) I must have full control of exceptions for logging. However,
I noticed that the FileInput class used by docutils for various purposes exits
the application (sys.exit) when it can't find a file. 

Reraising the IOError seems possible by passing in handle_io_errors=False, but
no user-accessible publishing API seems to expose that. 

Am I missing something, or is this a valid feature request? 
Thanks in advance, and happy holidays

Alan G Isaac <ai...@am...> writes:

> On 12/19/2010 5:22 PM, Ben Finney wrote:
> > If the distinct markups for emphasis are all conflated to a single
> > markup in the reST document, then they can't be distinct any more
> > from that point forward.
>
> In the part of my email that you cut (why?) I said one could imagine
> wanting to produce two different emphasis styles in the same document

I cut that because it didn't address what I'm talking about: not styles,
but markup.

> PS Please use more gracious quote strategies, to avoid creating the
> mere appearance of controversy.

I considered saying the same thing to you in my previous reply. Since
you feel the same way I expect the best explanation is that we're simply
talking past each other at this point, and Marcello needs to contribute
to help us understand his position.

-- 
 \      “[I]t is impossible for anyone to begin to learn that which he |
  `\                thinks he already knows.” —Epictetus, _Discourses_ |
_o__)                                                                  |
Ben Finney

On 2010-12-17, Alan G Isaac wrote:
> On 12/17/2010 6:20 PM, Ben Finney wrote:

> Marcello seems to be asking *in effect* for a directive
> that determines a style.

He provided a patch that allows class arguments for built-in roles.

> What is unclear is why e.g. using a docinfo field would
> not be adequate.  E.g.,

>:suggested-styles: em:letterspaced

...

> Perhaps hearing objections to this approach would shed
> light on the best way forward.

The problem with this approach is, that it would be printed in output
documents created "the normal way".

My suggestion is a class argument for the document, like ::

  .. class:: em-gesperrt
  
  Document Title
  ==============

which works out of the box (with CSS styling rules) without side-effects.

See the thread on docutils-devel for an example.

Günter

On 12/19/2010 5:22 PM, Ben Finney wrote:
> If the distinct markups for emphasis are all
> conflated to a single markup in the reST document, then they can't be
> distinct any more from that point forward.

In the part of my email that you cut (why?) I said one could
imagine wanting to produce two different emphasis styles in
the same document, but that this "imagined" conflict did not
describe Marcello's post as I understood it.  I even
provided a concrete example (also cut from your reply).

It is true that I've assumed Marcello would not ask for one
unclassed markup for emphasis to produce two different
markup styles for a single output document.  This I think is
the most reasonable assumption even without his explicit
example, which I cannot see as implying any such desire.  In
the absence of such an odd proposal, the problem may boil
down to how one can best associate style sheets with the PG
documents, as I proposed before.

I am still waiting to learn what that proposal lacks from
PG's perspective.

Alan

PS Please use more gracious quote strategies, to avoid
creating the mere appearance of controversy.

Alan G Isaac <ai...@am...> writes:

> In the reST markup one can "conflate all the different X". E.g., you
> simply *emphasize* text regardless of preferred emphasis style. In the
> style sheets, you "maintain the distinction between different X".

No, because the “X” that you omitted is referring to the emphasis
markup: not the abstract concept of emphasis, but the actual reST markup
used for emphasis. If the distinct markups for emphasis are all
conflated to a single markup in the reST document, then they can't be
distinct any more from that point forward.

Marcello's description of his constraints seems to entail simultaneously
erasing the distinction in the reST document, and maintaining the
distinction in the same document. If so, then at least one of those
can't be achieved.

I'm still awaiting Marcello's input in this thread, to see whether this
is all based on a misunderstanding of his constraints.

-- 
 \          “That's all very good in practice, but how does it work in |
  `\                                             *theory*?” —anonymous |
_o__)                                                                  |
Ben Finney

On 12/18/2010 5:03 PM, Ben Finney wrote:
> You don't see a conflict between
> “maintain the distinction between different X” versus “conflate all the
> different X”?

Not in any case yet mentioned. As I said,
that is **exactly** what style sheets are for.
Since you did not respond to that, it is hard
to know what you intend in restating the question.

In the reST markup one can "conflate all the different X".
E.g., you simply *emphasize* text regardless of preferred emphasis style.
In the style sheets, you "maintain the distinction between different X".
I.e., you say what "emphasis" implies for documents produced with that style.

The only real question I see is:
by what mechanism will documents be associated with preferred style sheets?
I suggested one.

Of course I can *imagine* a conflict.  (E.g., production of a single document
with both italic emphasis and letterspaced (gesperrt) emphasis.)  But that
does not match the use cases described so far, unless I misunderstood.

Alan Isaac

Alan G Isaac <ai...@am...> writes:

> On 12/17/2010 6:20 PM, Ben Finney wrote:
> > You [Marcello and Project Gutenberg] appear to have conflicting
> > goals, then:
>
> > * Maintain the distinction between many different markups for emphasis.
> > * Conflate all the different markups to a single markup.
>
> > Which is more important to you?
>
> I'm missing something: why need these goals be in conflict?

I don't know how better to say it. You don't see a conflict between
“maintain the distinction between different X” versus “conflate all the
different X”?

They seem obviously opposed to me: either the distinction between
different emphasis markups is to be maintained, or to be conflated.

Again, I would like Marcello, to weigh in on which of the above is more
important to him, or whether I've misrepresented his position.

-- 
 \     “First they came for the verbs, and I said nothing, for verbing |
  `\    weirds language. Then, they arrival for the nouns and I speech |
_o__)                           nothing, for I no verbs.” —Peter Ellis |
Ben Finney

On 12/17/2010 6:20 PM, Ben Finney wrote:
> You appear to have conflicting goals, then:

> * Maintain the distinction between many different markups for emphasis.
> * Conflate all the different markups to a single markup.

> Which is more important to you?


I'm missing something: why need these goals be in conflict?
This is precisely what stylesheets are for.

Marcello seems to be asking *in effect* for a directive
that determines a style.

What is unclear is why e.g. using a docinfo field would
not be adequate.  E.g.,

:suggested-styles: em:letterspaced

The script to compile the document into various formats
could begin with an inspection for this field and make
a choice from a small set of style sheets.

Perhaps hearing objections to this approach would shed
light on the best way forward.

fwiw,
Alan Isaac

On 12/17/2010 5:38 AM, Marcello Perathoner wrote:
> The reason I wanted to use*text*  instead of :gesperrt:`text` was to
> retain the semantic of emphasis for people writing and
> reading the reST source file.

Definitely.


> One stylesheet per books is not possible within our
> environment.

Istm that his would not be at all necessary.
You just need a small collection of style sheets,
and some way to recommend which to use for a document.
(E.g., a standardized comment.)

fwiw,
Alan Isaac
(another user)

On 2010-12-17, Eduardo Bustamante wrote:

> Hi, is it possible to setup a directive, or some type of configuration in a
> reStructuredText document, so the :Author:, :Contact:, : ... fields get
> translated to other languages, or what should I do to specify that
> information in my language?

If your language is supported by Docutils, you can use the native
words for the fields in your document.

Don't forget to tell Docutils the document language, e.g. via::

  rst2html.py --language=de test.txt test.html
  
  
Günter

Alan G Isaac <ai...@am...> writes:

> On 12/16/2010 4:14 PM, Marcello Perathoner wrote:
> > Maybe PG is stretching RST here, as it was never intended to record
> > existing works. OTOH, RST is elegant and fairly complete for our needs.
>
> PG is a wonderful project and I've wondered for a while why it did not
> use reST as a base format. My question looks about to be answered!

I think the simple explanation is that Project Gutenberg already had
markup conventions long before reST existed.

Marcello, welcome to the reST fold! Here's to a relatively smooth
transition for Project Gutenberg. Feel free to ask any questions about
usage of the markup or the Docutils tools in this forum.

-- 
 \       “When I get new information, I change my position. What, sir, |
  `\             do you do with new information?” —John Maynard Keynes |
_o__)                                                                  |
Ben Finney

Hi, is it possible to setup a directive, or some type of configuration in a
reStructuredText document, so the :Author:, :Contact:, : ... fields get
translated to other languages, or what should I do to specify that
information in my language?

Thanks,
Eduardo Bustamante

On 12/16/2010 4:14 PM, Marcello Perathoner wrote:
> Maybe PG is stretching RST here, as it was never intended to record
> existing works. OTOH, RST is elegant and fairly complete for our needs.
>


PG is a wonderful project and I've wondered for a while
why it did not use reST as a base format.  My question
looks about to be answered!

Good luck.  Be patient if responses are not immediate:
good questions almost always get good answers on this
list in not too much time.

Cheers,
Alan Isaac
(reST user and fan of PG)

On 2010-12-13, Ryan Krauss wrote:
> I need to put "\usepackage{fullpage}" verbatim in a sentence in a
> document that will be processed using rst2latex.  I would like it to
> be typeset in typewriter font.  I seem to be having a great deal of
> trouble with this and I don't know why.  In pure latex, I might do
> something like \lstinline!\usepackage{fullpage}!, but when I try
> something similar in rst, I lose the first \.  My other approaches,
> such as `\verb=\usepackage{fullpage}=`, lead to errors.

> What is the best and easiest way to accomplish verbatim inclusion of
> \usepackage?

Inline literal: ``\usepackage{fullpage}``.

Günter

I need to put "\usepackage{fullpage}" verbatim in a sentence in a
document that will be processed using rst2latex.  I would like it to
be typeset in typewriter font.  I seem to be having a great deal of
trouble with this and I don't know why.  In pure latex, I might do
something like \lstinline!\usepackage{fullpage}!, but when I try
something similar in rst, I lose the first \.  My other approaches,
such as `\verb=\usepackage{fullpage}=`, lead to errors.

What is the best and easiest way to accomplish verbatim inclusion of
\usepackage?

Thanks,

Ryan

Thank you for suggestions, but finally I ended up with this::

    import lxml.etree

    from docutils import io
    from docutils.core import publish_parts, publish_doctree

    from devblog.models import Page


    def sync(filename):
        params = {
            'source_class': io.FileInput,
            'settings_overrides': {
                'output_encoding': 'unicode',
            },
        }

        params['source'] = open(filename, 'r')
        tree = publish_doctree(**params)
        etree = lxml.etree.XML(tree.asdom().toxml())
        docinfo = {}
        fields = ('author', 'date')
        for element in etree.findall('docinfo/*'):
            if element.tag in fields:
                docinfo[element.tag] = element.text

        params['source'] = open(filename, 'r')
        parts = publish_parts(**dict(params, writer_name='html'))
        page = Page(title = parts['title'],
                    created=docinfo.get('date', None),
                    body = parts['html_body'])
        page.save()



2010.12.11 23:26, Berend van Berkum rašė:
> 
> You need to set up a publisher with a null writer and some special transforms
> that pick the data your need from the tree.
> I'm currently blank on the details, but Nabu [1] does this using
> Extractors/Storage pairs.
> And there's my own project [2] that includes extractors that allow use of 
> RSt documents as forms, but those specific parts are lacking documentation I
> think.
> 
> [1] http://furius.ca/nabu
> [2] https://code.launchpad.net/~mpe/python-docutils/docutils.mpe


-- 
                 Mantas aka sirex
      __o                                   /\
    _ \<,_   -- launchpad.net/~sirex --  /\/  \
___(_)/_(_)_____________________________/_/    \
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

On 2010-12-11, Berend van Berkum wrote:


> trying to get a nice title for the document. But it is included in the
> table of contents. I've tried using the 'local' flag but not with much
> success.

> Also, using sectnum directive a number is inserted for every title,
> including the document title.

Looks very much like your title is not promoted to document title but
counts as section title.  What is the output of your document with HTML?
Can you please provide a *minimal working example*?

> And the contents directive; with --use-docutils-toc and the local flag
> I get a better fit, but that has no page numbering. Otherwise I cant
> seem to do much with 'local'. I get an unsupported warning (see below)
> in contrast with what the text at [1] says.

> main.rst.src:15: (WARNING/2) Skipping local ToC at subparagraph level.
>   Feature not supported with option "use-latex-toc"

This is a warning: Do you really want a ToC down to subparagraph?

Also, the "local" option is not intended for the global toc.

> Any suggestions? 

Details for generating LaTeX with docutils with many tips and links are
at http://docutils.sourceforge.net/docs/user/latex.html.

Günter

Someone else will have to help with the LaTeX-specific stuff, but this
may help with the title question:
http://docutils.sourceforge.net/FAQ.html#how-can-i-indicate-the-document-title-subtitle

-- David Goodger <http://python.net/~goodger>


On Sat, Dec 11, 2010 at 16:18, Berend van Berkum <li...@do...> wrote:
>
> Hello,
>
>
> trying to get a nice title for the document. But it is included in the table
> of contents. I've tried using the 'local' flag but not with much success.
>
> Also, using sectnum directive a number is inserted for every title, including
> the document title.
>
> I'm trying to get a title page without numbering it, or it showing up
> in the TOC. I suppose could write some raw LaTeX, but I'm thinking
> about the contents and sectnum directives. How about something like a
> 'start-depth' option for the latter?
>
> And the contents directive; with --use-docutils-toc and the local flag I get a
> better fit, but that has no page numbering. Otherwise I cant seem to do much
> with 'local'. I get an unsupported warning (see below) in contrast with what
> the text at [1] says.
>
> This needs to be fit for print. Seems I need a hand titlepage only I'm new to
> LaTex. I'm getting some progress with these [2] nice examples. But now the page
> itself gets numbered. Perhaps I need to write a template for the writer?
>
> Any suggestions?
>
>
> regards, Berend
>
>
>
> [1] http://docutils.sourceforge.net/docs/user/latex.html#table-of-contents
> [2] http://zoonek.free.fr/LaTeX/LaTeX_samples_title/0.html
>
> ----
>
> main.rst.src:15: (WARNING/2) Skipping local ToC at subparagraph level.
>  Feature not supported with option "use-latex-toc"

On Sat, Dec 11, 2010 at 16:05, Mantas <si...@gm...> wrote:
> I'm writing my blog application based on reST and docutils. Each blog
> post is a single reST file. Each file has some meta information that is
> called docinfo in docutils or elements in documentation:
>
>  http://docutils.sourceforge.net/docs/ref/doctree.html#element-reference

You seem to be confused on the terminology. "docinfo" is the name of
an element in the document tree (doctree).

> Is it possible some how to get those elements using docutils api?

Use the publish_doctree function, then traverse the tree.
http://docutils.sourceforge.net/docs/api/publisher.html

-- 
David Goodger <http://python.net/~goodger>

Hi,

You need to set up a publisher with a null writer and some special transforms
that pick the data from the tree.
I'm currently blank on the details, but Nabu [1] does this using
Extractors/Storage pairs.
And there's my own project [2] that includes extractors that allow use of 
RSt documents as forms, but those specific parts are lacking documentation I
think.


-- Berend

[1] http://furius.ca/nabu
[2] https://code.launchpad.net/~mpe/python-docutils/docutils.mpe

On Sat, Dec 11, 2010 at 11:05:32PM +0200, Mantas wrote:
> Hi,
> 
> I'm writing my blog application based on reST and docutils. Each blog
> post is a single reST file. Each file has some meta information that is
> called docinfo in docutils or elements in documentation:
> 
>   http://docutils.sourceforge.net/docs/ref/doctree.html#element-reference
> 
> Is it possible some how to get those elements using docutils api?
> 
> Currently I need at least ``author`` and ``date`` elements from reST files.
> 
> 
> -- 
>                  Mantas aka sirex
>       __o                                   /\
>     _ \<,_   -- launchpad.net/~sirex --  /\/  \
> ___(_)/_(_)_____________________________/_/    \
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>