docutils-users — General discussions, questions, help requests.

[Docutils-users] RE to D.Goodger: Docutils tools syntax (command-line with option(s)) - XSL sheet option

[Pierre-Yves D. <py....@li...>]

Bonjour,

Thank you,

I have  found my answer (see below).
I will be testing the XSL option.
If somebody already has experience with the XSL option, please tell me.

Thanks
___________________________________________________
P-Y Delens

Resp. "Technologies de l'Information et de la Communication"
pour la FAB - Federation des Architectes de Belgique
pour la SAF - Societe des Architectes Francophones
www.saf-arch.be
mail : web...@sa...

c/o LIENTERFACES -  PY Delens, sprl

Avenue Dolez, 243  -  1180          Bruxelles
phone : 32 2 375 55 62              fax : 32 2 374 75 74
mail  : py....@li...   web : www.lienterfaces.be
___________________________________________________

Found in the docs and modules :
1?. the XSL option in the quicktest.py (front-end tools) :

                    Options:
                    """

                    options = [('pretty', 'p',
                                'output pretty pseudo-xml: no "&abc;"
entities (default)'),
                               ('test', 't', 'output test-ready data (input
& expected output, '
                                'ready to be copied to a parser test
module)'),
                               ('rawxml', 'r', 'output raw XML'),
                               ('styledxml=', 's', 'output raw XML with XSL
style sheet '
                                'reference (filename supplied in the option
argument)'),
                               ('xml', 'x', 'output pretty XML (indented)'),
                               ('attributes', 'A', 'dump document attributes
after processing'),
                               ('debug', 'd', 'debug mode (lots of
output)'),
                               ('version', 'V', 'show Docutils version then
exit'),
                               ('help', 'h', 'show help text then exit')]
                    """See ``distutils.fancy_getopt.FancyGetopt.__init__``
for a description of
                    the data structure: (long option, short option,
description)."""

================== ==================
2?. in http://docutils.sourceforge.net/docs/tools.html :
	example of option syntax :
	html.py -stg --stylesheet my.css test.txt test.html

================== ==================

3?. in Python/distutils.fancy_getopt

                    """distutils.fancy_getopt

                    Wrapper around the standard getopt module that provides
the following
                    additional features:
                      * short and long options are tied together
                      * options have help strings, so fancy_getopt could
potentially
                        create a complete usage summary
                      * options set attributes of a passed-in object
                    """

                    # created 1999/03/03, Greg Ward

                    __revision__ = "$Id: fancy_getopt.py,v 1.20 2001/12/06
20:51:35 fdrake Exp $"

                    import sys, string, re
                    from types import *
                    import getopt
                    from distutils.errors import *

                    # Much like command_re in distutils.core, this is close
to but not quite
                    # the same as a Python NAME -- except, in the spirit of
most GNU
                    # utilities, we use '-' in place of '_'.  (The spirit of
LISP lives on!)
                    # The similarities to NAME are again not a
coincidence...
                    longopt_pat = r'[a-zA-Z](?:[a-zA-Z0-9-]*)'
                    longopt_re = re.compile(r'^%s$' % longopt_pat)

                    # For recognizing "negative alias" options, eg.
"quiet=!verbose"
                    neg_alias_re = re.compile("^(%s)=!(%s)$" % (longopt_pat,
longopt_pat))

                    # This is used to translate long options to legitimate
Python identifiers
                    # (for use as attributes of some object).
                    longopt_xlate = string.maketrans('-', '_')

                    # This records (option, value) pairs in the order seen
on the command line;
                    # it's close to what getopt.getopt() returns, but with
short options
                    # expanded.  (Ugh, this module should be OO-ified.)
                    _option_order = None

================== ================== ================== ==================
-----Original Message-----
From: David Goodger [mailto:go...@py...]
Sent: mercredi 26 mars 2003 19:22
To: py....@li...
Cc: go...@us...
Subject: Re: Docutils tools syntax


Pierre-Yves Delens wrote:
> Bonjour, could you give me the clue to syntax of complex command
> lines for docutils ?

See <http://docutils.sf.net/docs/tools.html>, or use the "--help"
option for each tool.

> How should I specify the XSL reference ?

I don't think there is such an option yet.  What form of XML are
you using?

In future, please address questions to <doc...@li...>.
Thank you.

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

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

[Docutils-users] Docutils raises UnicodeError

[Morten W. P. <mo...@ni...>]

Hi!

I'm using the docutils package in the IssueManager[1] product, and this
error is raised on some types of texts:

Error Type: UnicodeError
Error Value: Latin-1 encoding error: ordinal not in range(256)
Error traceback: Traceback (innermost last): File
C:\PROGRA~1\WEBSITE\lib\python\ZPublisher\Publish.py, line 98, in
publish File C:\PROGRA~1\WEBSITE\lib\python\ZPublisher\mapply.py, line
88, in mapply (Object: index_html) File
C:\PROGRA~1\WEBSITE\lib\python\ZPublisher\Publish.py, line 39, in
call_object (Object: index_html) File
C:\PROGRA~1\WEBSITE\lib\python\Shared\DC\Scripts\Bindings.py, line 252,
in __call__ (Object: index_html) File
C:\PROGRA~1\WEBSITE\lib\python\Shared\DC\Scripts\Bindings.py, line 283,
in _bindAndExec (Object: index_html) File
C:\PROGRA~1\WEBSITE\lib\python\App\special_dtml.py, line 172, in _exec
(Object: index_html) File
C:\PROGRA~1\WEBSITE\lib\python\DocumentTemplate\DT_Util.py, line 159, in
eval (Object: render_contents(size=400)) (Info: render_contents) File ,
line 0, in ? File
C:\PROGRA~1\WEBSITE\lib\python\Products\IssueManager\issue.py, line 336,
in render_contents (Object: 1047322986X56) File
C:\PROGRA~1\WEBSITE\lib\python\Products\IssueManager\issue.py, line 121,
in render_stx_as_html (Object: 1047322986X56) File
C:\PROGRA~1\WEBSITE\lib\python\Products\IssueManager\docutils\core.py,
line 326, in publish_string File
C:\PROGRA~1\WEBSITE\lib\python\Products\IssueManager\docutils\core.py,
line 174, in publish File
C:\PROGRA~1\WEBSITE\lib\python/Products/IssueManager\docutils\writers\__init__.py,
line 52, in write File
C:\PROGRA~1\WEBSITE\lib\python/Products/IssueManager\docutils\io.py,
line 264, in write File
C:\PROGRA~1\WEBSITE\lib\python/Products/IssueManager\docutils\io.py,
line 144, in encode UnicodeError: Latin-1 encoding error: ordinal not in
range(256) 

The text was cut-and-pasted from a Word document into a HTML textarea
and saved.  What can I do to fix this?

[1] http://www.zope.org/Members/morphex/IssueManager

Thanks,

Morten W. Petersen

Technologies: Zope, Linux, Python, HTML, CSS, PHP
    Homepage: http://www.nidelven-it.no
Phone number: (+47) 45 44 00 69

[Docutils-users] Re: support for character-level inline markup added to reStructuredText

[David A. <da...@bo...>]

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

[Docutils-users] support for character-level inline markup added to reStructuredText

[David G. <go...@py...>]

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-inline-markup>.
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

Re: [Docutils-users] AttributeError: Values instance has no attribute 'tab_width'

[David G. <go...@py...>]

Magnus Lycka wrote:
> I'm trying to use the pythonpoint thingie in the sandbox,
> but it seems parse() in parsers/rst/__init__() assumes that
> documents have a .tab_with attribute which isn't there...

That code hasn't been maintained.  If you get it working, a patch would 
be appreciated!  I'm sure Richard Jones (the original author) would be 
happy for you to take it over!

> Anyone know what this is all about?

This thread might help (not specifically on-topic, but the overview of 
how runtime settings work may give you a clue): 
<http://article.gmane.org/gmane.text.docutils.devel/18>.  I don't have 
time to check it out right now, sorry.

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

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

Re: [Docutils-users] When you really just need a <br/>?

[David G. <go...@py...>]

Mark McEahern wrote:
 > What's the most straightforward way to arrange text so that when you
 > generate it with reStructuredText's html.py, the output has a <br/> 
in it?
...
 > Such as when you're writing an address.

<http://docutils.sourceforge.net/spec/rst/directives.html#line-block>::

     line-block::

         Mark McEahern
	101 Whoville
	Who, McGoo

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

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

[Docutils-users] When you really just need a <br/>?

[Mark M. <ma...@mc...>]

What's the most straightforward way to arrange text so that when you
generate it with reStructuredText's html.py, the output has a <br/> in it?

I don't want to use::

  Something like
  this

because that'll wrap it in <pre class="literal-block"/> and then I have to
figure out how to make this stuff look the same as the stuff around it.

I like the fact that
normally something
skinny like this

comes out as a single paragraph.  But sometimes you just want to have one
line and then another with a <br/> inbetween.

Such as when you're writing an address.

Mark McEahern
101 Whoville
Who, McGoo

Make sense?

Thanks,

// m

-

Re: [Docutils-users] Re: FW: Another Problem with latex writer

[<eng...@ss...>]

On Mon, 17 Mar 2003, David Abrahams wrote:

> The latest problem is that text which needs to be verbatim (e.g. "^")
> causes problems when it appears in an \mbox{ ... }.  I don't know
> enough about LaTeX to fix it myself.  I've done a bunch of web
> searches and come up empty.  An example of what gets generated is:

now it uses a raised wedge-symbol (mathmode). i am not happy with it as the
font is wrong for mathmode (IMHO) NOT this also for "<>" characters.
but at least it is typeset.

committed
-- 
 BINGO: Das muessen wir noch kommunizieren
 --- Engelbert Gruber -------+
 SSG Fintl,Gruber,Lassnig   /
 A6410 Telfs Untermarkt 9  /
 Tel. ++43-5262-64727 ----+

Re: [Docutils-users] AttributeError: Values instance has no attribute 'tab_width'

[Magnus L. <ma...@th...>]

At 02:23 2003-03-18 +0100, Magnus Lycka wrote:
>I'm trying to use the pythonpoint thingie in the sandbox,
>but it seems parse() in parsers/rst/__init__() assumes that
>documents have a .tab_with attribute which isn't there...

Sorry, that should have been "document.settings.tab_width"
in parsers/rst/__init__.py. And yes, I should go to sleep
now...

The document is created with "docutils.utils.new_document(parser)"
which means (I think) that document.settings =
frontend.OptionParser().get_default_values()

Print document.settings show:

docutils.optik.Values({'_destination': None, 'output_encoding':
'utf-8', 'footnote_backlinks': 1, 'halt_level': 4, 'dump_pseudo_xml':
None, 'generator': None, '_source': None, 'language_code': 'en',
'source_link': None, 'input_encoding': None, 'expose_internals':
None, 'source_url': None, 'dump_transforms': None, 'toc_backlinks':
'entry', 'datestamp': None, 'warning_stream': None, 'dump_internals':
None, 'debug': None, 'report_level': 2, 'dump_settings': None})

The only other place than this part of rst/__init__.py where I
find tab_width is as a local variable in statemachine.string2lines...

Hm...

>Anyone know what this is all about?
>
>...\sandbox\richard\pythonpoint>pythonpoint.py example_slides.txt
>
>Traceback (most recent call last):
>   File "...\sandbox\richard\pythonpoint\pythonpoint.py", line 347, in ?
>     main(sys.argv[1])
>   File "...\sandbox\richard\pythonpoint\pythonpoint.py", line 336, in main
>     parser.parse(input, document)
>   File "...\site-packages\docutils\parsers\rst\__init__.py", line 116, in 
> parse
>     inputlines = docutils.statemachine.string2lines(
>AttributeError: Values instance has no attribute 'tab_width'
>
>I'm using the CVS trunk and ActivePython 2.2 on Win2k.




-- 
Magnus Lycka, Thinkware AB
Alvans vag 99, SE-907 50 UMEA, SWEDEN
phone: int+46 70 582 80 65, fax: int+46 70 612 80 65
http://www.thinkware.se/  mailto:ma...@th...

[Docutils-users] AttributeError: Values instance has no attribute 'tab_width'

[Magnus L. <ma...@th...>]

I'm trying to use the pythonpoint thingie in the sandbox,
but it seems parse() in parsers/rst/__init__() assumes that
documents have a .tab_with attribute which isn't there...

Anyone know what this is all about?

...\sandbox\richard\pythonpoint>pythonpoint.py example_slides.txt

Traceback (most recent call last):
   File "...\sandbox\richard\pythonpoint\pythonpoint.py", line 347, in ?
     main(sys.argv[1])
   File "...\sandbox\richard\pythonpoint\pythonpoint.py", line 336, in main
     parser.parse(input, document)
   File "...\site-packages\docutils\parsers\rst\__init__.py", line 116, in 
parse
     inputlines = docutils.statemachine.string2lines(
AttributeError: Values instance has no attribute 'tab_width'

I'm using the CVS trunk and ActivePython 2.2 on Win2k.


-- 
Magnus Lycka, Thinkware AB
Alvans vag 99, SE-907 50 UMEA, SWEDEN
phone: int+46 70 582 80 65, fax: int+46 70 612 80 65
http://www.thinkware.se/  mailto:ma...@th...

[Docutils-users] Re: FW: Another Problem with latex writer

[David A. <da...@bo...>]

The latest problem is that text which needs to be verbatim (e.g. "^")
causes problems when it appears in an \mbox{ ... }.  I don't know
enough about LaTeX to fix it myself.  I've done a bunch of web
searches and come up empty.  An example of what gets generated is:

\mbox{typedef~mpl::list{\_}c{$<$}int,0,1,-2,0,0,0,0{$>$}~acceleration;~//~l/(t{\verb|^|}2)}\\

which causes:

    ! Missing $ inserted.
    <inserted text> 
                    $
    l.356 ...0{$>$}~acceleration;~//~l/(t{\verb|^|}2)}
                                                      \\
    ? 

If you remove "\verb|^|", everything works.

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

Re: [Docutils-users] Re: FW: Another Problem with latex writer

[<eng...@ss...>]

On Mon, 17 Mar 2003, David Abrahams wrote:

> eng...@ss... writes:
>
> > you were a little greedy, this one::
> >
> >   text = re.sub(r'[^{][\\]', r'{\textbackslash}', text)
> >
> > will replace any the backslash AND the preceeding character (except for a
> > brace).
>
> Oops.
>
> > AND there need to be two backslashes.
>
> I'm pretty sure that's wrong: note that they're raw strings.  Did you
> test the result?

yes, i used your snippet
BUT, there was no literal backslash i just recognized that it said
  "	extbackslash" where it shouldnt.

for (my) peaceful sleep i added two lines::

      ::

        using namespace mpl::placeholders;
        mpl::a_line_with\tbackslash
        mpl::a_line_without backslash

which results in ::

   namespace.  In this book we will usually assume that you have
   written
   \begin{ttfamily}\begin{flushleft}
   \mbox{using~namespace~mpl::placeholders;}\\
   \mbox{mpl::a{\_}line{\_}with{\textbackslash}tbackslash}\\
   \mbox{mpl::a{\_}line{\_}without~backslash}
   \end{flushleft}\end{ttfamily}

which looks reasonable to me.

being an ignorant i did not know what this r's meant.
after some trying::

  # assume a c-code line
  # printf("%d\t%s\n",count,message);
  line = open("code.c").readline()
  # >>> line
  # 'printf("%d\\t%s\\n",count,message);'

now to replace all backslashes with TB either or::

  re.sub('\\\\','TB',line)
  re.sub(r'\\','TB',line)

means we have two backslashes in line (\\t) and te regexp for
this is two backslashes '\\' is only one r'\\' gives two.
and for getting '{\textbackslash}'::

  re.sub(r'\\','\\textbackslash',line)

BUT then we have the string ::

  'printf("%d\textbackslasht%s\textbackslashn",count,message);'

which does not have a backslash but an escaped letter t, and prints
as ::

  printf("%d      extbackslasht%s extbackslashn",count,message);

the problem is one cannot enter a single backslash even in a rawstring,
r'\' does not work.

cheers

-- 
 BINGO: assertively disseminate unique opportunities
 --- Engelbert Gruber -------+
 SSG Fintl,Gruber,Lassnig   /
 A6410 Telfs Untermarkt 9  /
 Tel. ++43-5262-64727 ----+

Re: [Docutils-users] customize for literature book

[David G. <go...@py...>]

William Dode wrote:
> I use the cvs version, is there a lot of difference with the release ?

Yes, the CVS code is much ahead of the last release.  We're overdue for a
new release.

-- David Goodger

Re: [Docutils-users] Re: FW: Another Problem with latex writer

[David A. <da...@bo...>]

eng...@ss... writes:

> you were a little greedy, this one::
>
>   text = re.sub(r'[^{][\\]', r'{\textbackslash}', text)
>
> will replace any the backslash AND the preceeding character (except for a
> brace). 

Oops.

> AND there need to be two backslashes.

I'm pretty sure that's wrong: note that they're raw strings.  Did you
test the result?


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

Re: [Docutils-users] customize for literature book

[William D. <wi...@fl...>]

David Goodger <go...@py...> writes:

> William Dode wrote:
> > (incredible 30 developers on this project !!!).
> 
> Not so incredible.  Almost everybody who contributes becomes a developer.
> Sometimes I offer, sometimes they ask.  The doors are wide open.
> 
> > I don't like to put it in the text when they can be put automaticaly.
> > I thought making a special html writers or use an external script
> > after the writers.
> 
> Looking at the article you cite, a specialized writer may be necessary.  It
> seems that very publisher has a different article structure.  However, I'd
> recommend a *pre*-processing script, *before* Docutils, to automate
> insertion of non-breaking spaces and other character processing (like
> turning "<<" into the &laquo; guillemet symbol).
> 
> > Just a litle question : how to don't have space with a replace ? (and
> > also with [#]) ?
> > Python |tm| work but Python|tm| will not work.
> 
> That's one of the "issues still to resolve":

I use the cvs version, is there a lot of difference with the release ?

> 
> >> There are a couple of issues still to resolve.  See
> >> <http://article.gmane.org/gmane.comp.python.documentation/418> for details.
> 
> Specifically, I think the "\ " escape sequence idea works nicely.  So it
> would be "Python\ |tm|".  It's ugly, but it works.  Or it will, once
> implemented (soon).

Fine, it's not ugly, specialy when i can put it in a pre-processor !

> 
> >>> - how can i have a new type of paragraph (like a right-indented for
> >>> citation between title and text) : i begin to look at adding a
> >>> directive...
> >> 
> >> I can't say without seeing an example; can you provide one?  A directive may
> >> be the correct option.
> > 
> > http://atheles.org/editeur.php?ref_editeur=&main=lyber&ref_lyber=273
> > 
> > there is a title, a subtitle (long line), a citation on the right (exergue).
> > 
> > if i could do .. exergue:: after i can manage it easily with stylesheet.
> 
> Interesting word, "exergue".  My French-English dictionary translates it to
> "exergue" also in English, which means "the space beneath the device on a
> coin or medal, which lists the date and/or place of minting".  My old "Micro
> Robert En Poche" wasn't very helpful either, since my French is rusty.
> 
> The "exergue" appears to me to be a block quote used to introduce an article
> (does it appear anywhere else?).  A directive could do it, or a
> bibliographic field (":exergue: ..."), or just have your custom Writer (or a
> transform) recognize the first block quote after the document title.
> Another idea that was brought up recently was for a directive to add a
> "class" attribute to arbitrary objects.  Something like this::
> 
>     =====
>     Title
>     =====
> 
>         .. class:: exergue
> 
>         This is the block quote "exergue"...
> 
>     Main text here...
> 
> Then you'd end up with <block_quote class="exergue">...</> and your
> stylesheet can select on the class.  The "class" directive hasn't been
> implemented yet.

Ok, a customized directive for general purpose and this class directive
for exceptions. It's fine.

> 
> >>> - is interpreted text a way to customize ?
> >> 
> >> Yes, depending on what you want to do.  It's currently in development and
> >> discussion.  Please provide examples if you want more specific answers.
> > 
> > For example, if i want a special font or color for foreigns word in the middle
> > of a paragraph. Somethings like that :foreign:`bonjour`
> 
> Yes, that's what interpreted text is for.

Ok, now it's time for me to dig into the source and try...

Thanks, 

-- 
William Dode - http://flibuste.net

Re: [Docutils-users] customize for literature book

[David G. <go...@py...>]

William Dode wrote:
> (incredible 30 developers on this project !!!).

Not so incredible.  Almost everybody who contributes becomes a developer.
Sometimes I offer, sometimes they ask.  The doors are wide open.

> I don't like to put it in the text when they can be put automaticaly.
> I thought making a special html writers or use an external script
> after the writers.

Looking at the article you cite, a specialized writer may be necessary.  It
seems that very publisher has a different article structure.  However, I'd
recommend a *pre*-processing script, *before* Docutils, to automate
insertion of non-breaking spaces and other character processing (like
turning "<<" into the &laquo; guillemet symbol).

> Just a litle question : how to don't have space with a replace ? (and
> also with [#]) ?
> Python |tm| work but Python|tm| will not work.

That's one of the "issues still to resolve":

>> There are a couple of issues still to resolve.  See
>> <http://article.gmane.org/gmane.comp.python.documentation/418> for details.

Specifically, I think the "\ " escape sequence idea works nicely.  So it
would be "Python\ |tm|".  It's ugly, but it works.  Or it will, once
implemented (soon).

>>> - how can i have a new type of paragraph (like a right-indented for
>>> citation between title and text) : i begin to look at adding a
>>> directive...
>> 
>> I can't say without seeing an example; can you provide one?  A directive may
>> be the correct option.
> 
> http://atheles.org/editeur.php?ref_editeur=&main=lyber&ref_lyber=273
> 
> there is a title, a subtitle (long line), a citation on the right (exergue).
> 
> if i could do .. exergue:: after i can manage it easily with stylesheet.

Interesting word, "exergue".  My French-English dictionary translates it to
"exergue" also in English, which means "the space beneath the device on a
coin or medal, which lists the date and/or place of minting".  My old "Micro
Robert En Poche" wasn't very helpful either, since my French is rusty.

The "exergue" appears to me to be a block quote used to introduce an article
(does it appear anywhere else?).  A directive could do it, or a
bibliographic field (":exergue: ..."), or just have your custom Writer (or a
transform) recognize the first block quote after the document title.
Another idea that was brought up recently was for a directive to add a
"class" attribute to arbitrary objects.  Something like this::

    =====
    Title
    =====

        .. class:: exergue

        This is the block quote "exergue"...

    Main text here...

Then you'd end up with <block_quote class="exergue">...</> and your
stylesheet can select on the class.  The "class" directive hasn't been
implemented yet.

>>> - is interpreted text a way to customize ?
>> 
>> Yes, depending on what you want to do.  It's currently in development and
>> discussion.  Please provide examples if you want more specific answers.
> 
> For example, if i want a special font or color for foreigns word in the middle
> of a paragraph. Somethings like that :foreign:`bonjour`

Yes, that's what interpreted text is for.

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

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

Re: [Docutils-users] customize for literature book

[William D. <wi...@fl...>]

David Goodger <go...@py...> writes:

> William Dode wrote:
> > Am I in the good place ?
> 
> Yes, this is fine.  The docutils-develop list and Python's Doc-SIG list also
> carry relevant discussions.

I just subscribe to docutils-develop (incredible 30 developers on this
project !!!).

> 
> > Do you think reStructuredText could help us ?
> >
> > I develop in python so it's sure that i will use it for my own
> > documentation. But what about non-developer users ?
> 
> Yes, reStructuredText could help you, but please realize that it's still
> under development.  There are many rough edges and features that have yet to
> be implemented (see <http://docutils.sf.net/spec/notes.html#to-do>).  As
> long as the functionality you want is already implemented, non-developer use
> is no problem.

What i've seen and try for now is near enough. And following the
development is a pleasure.

> 
> If you're interested in sponsoring further development, I'm available.  See
> my signature.

I think editors need tools like yours, but they begin to understand it very very
slowly... But be sure i'll mention you where i'll use your tools.

> 
> > If yes, i've some questions about customization :
> > - where can i automatize the typography ? (like &nbsp; before : ; ?...)
> 
> What language are you publishing in?  In English we never put a space before
> trailing punctuation.

In french. We need nbsp before : ; ? !. We need also special quotes << >>

> 
> In any case, unless convincing arguments appear, I don't think
> reStructuredText will have any special character processing: no
> "&nbsp;"-style character entities.  Docutils and reStructuredText use
> Unicode internally and use Python's codec system for encoding and decoding
> UTF-8, Latin-1, etc.  Simply insert a non-breaking space directly into your
> source text, and tell Docutils what encoding you're using.

I don't like to put it in the text when they can be put automaticaly.
I thought making a special html writers or use an external script
after the writers.

> 
> > - how can i write special caracters (tm, (c)...) ?
> 
> As above, insert the actual characters into your text.

It's not every time easy since we use html forms.

> 
> In a recent Doc-SIG discussion, David Priest was asking to be able to use
> XML character entities ("&nbsp;"-style).  I don't think that's appropriate
> for reStructuredText, but he was unable to use UTF-8 encoded text files for
> practical reasons, so he came up with an alternate scheme.  He will use a
> "substitution table file" of this form::
> 
>     .. exclamation point:
>     .. |excl| replace:: !

Good idea !

Just a litle question : how to don't have space with a replace ? (and
also with [#]) ?
Python |tm| work but Python|tm| will not work.

> 
> There are a couple of issues still to resolve.  See
> <http://article.gmane.org/gmane.comp.python.documentation/418> for details.
> 
> > - how can i have a new type of paragraph (like a right-indented for
> >   citation between title and text) : i begin to look at adding a
> >   directive...
> 
> I can't say without seeing an example; can you provide one?  A directive may
> be the correct option.

http://atheles.org/editeur.php?ref_editeur=&main=lyber&ref_lyber=273

there is a title, a subtitle (long line), a citation on the right (exergue).

if i could do .. exergue:: after i can manage it easily with stylesheet.

> 
> > - is interpreted text a way to customize ?
> 
> Yes, depending on what you want to do.  It's currently in development and
> discussion.  Please provide examples if you want more specific answers.

For example, if i want a special font or color for foreigns word in the middle of a
paragraph. Somethings like that :foreign:`bonjour`

bye

-- 
William Dode - http://flibuste.net

Re: [Docutils-users] customize for literature book

[David G. <go...@py...>]

William Dode wrote:
> Am I in the good place ?

Yes, this is fine.  The docutils-develop list and Python's Doc-SIG list also
carry relevant discussions.

> Do you think reStructuredText could help us ?
>
> I develop in python so it's sure that i will use it for my own
> documentation. But what about non-developer users ?

Yes, reStructuredText could help you, but please realize that it's still
under development.  There are many rough edges and features that have yet to
be implemented (see <http://docutils.sf.net/spec/notes.html#to-do>).  As
long as the functionality you want is already implemented, non-developer use
is no problem.

If you're interested in sponsoring further development, I'm available.  See
my signature.

> If yes, i've some questions about customization :
> - where can i automatize the typography ? (like &nbsp; before : ; ?...)

What language are you publishing in?  In English we never put a space before
trailing punctuation.

In any case, unless convincing arguments appear, I don't think
reStructuredText will have any special character processing: no
"&nbsp;"-style character entities.  Docutils and reStructuredText use
Unicode internally and use Python's codec system for encoding and decoding
UTF-8, Latin-1, etc.  Simply insert a non-breaking space directly into your
source text, and tell Docutils what encoding you're using.

> - how can i write special caracters (tm, (c)...) ?

As above, insert the actual characters into your text.

In a recent Doc-SIG discussion, David Priest was asking to be able to use
XML character entities ("&nbsp;"-style).  I don't think that's appropriate
for reStructuredText, but he was unable to use UTF-8 encoded text files for
practical reasons, so he came up with an alternate scheme.  He will use a
"substitution table file" of this form::

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

There are a couple of issues still to resolve.  See
<http://article.gmane.org/gmane.comp.python.documentation/418> for details.

> - how can i have a new type of paragraph (like a right-indented for
>   citation between title and text) : i begin to look at adding a
>   directive...

I can't say without seeing an example; can you provide one?  A directive may
be the correct option.

> - is interpreted text a way to customize ?

Yes, depending on what you want to do.  It's currently in development and
discussion.  Please provide examples if you want more specific answers.

> thanks for the answer and for the great works you did !

You're welcome.

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

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

[Docutils-users] customize for literature book

[William D. <wi...@fl...>]

Hi,

I work for a book editor and we plan to put the book online.
It's not complex documentation books, but more literature.

We look first at docbook, but it's too much work to translate the
current text (xpress) and to customize the stylesheet.

We have also a newspaper to put online, so we'll need to make articles
ready for web quickly and easily. 

Do you think reStructuredText could help us ?

I develop in python so it's sure that i will use it for my own
documentation. But what about non-developer users ?

Am I in the good place ?

If yes, i've some questions about customization :
- where can i automatize the typography ? (like   before : ; ?...)
- how can i have a new type of paragraph (like a right-indented for
  citation between title and text) : i begin to look at adding a
  directive...
- how can i write special caracters (tm, (c)...) ?
- is interpreted text a way to customize ?

thanks for the answer and for the great works you did !

-- 
William Dode - http://flibuste.net

Re: [Docutils-users] footnote numbering?

[David G. <go...@py...>]

David Abrahams wrote:
> I'm a bit confused about how footnote numbers are chosen.
> 
> http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/*checkout*/boost/boost/libs/pyt
> hon/doc/PyConDC_2003/bpl.txt?rev=HEAD&content-type=text/plain
> 
> Shows that my first and second numbered footnotes. [#1] and [#2], are
> coming out as 3 and 4.  Whaaaa?

Actually, your footnotes [#1], [#2], and [#3] are coming out as 4, 5, and 6,
respectively.  I assume that a third footnote was added shortly after your
message.  Notice a pattern forming?

The "#" in footnotes & references indicates auto-numbering.  [#label] form
of footnotes is called auto-labelled.  The label is used to link footnote
references to the footnotes themselves (so that the order doesn't matter),
and to allow multiple references to each footnote.  Ordinary internal
references are also supported for footnote labels::

    Here's a footnote reference: [#fnref]_.
    Here's another: [#fnref]_ (same number).
    Here's a regular reference: fnref_.

    .. [#fnref] Here's the footnote.

The first two references are turned into numbers (either superscripted or in
brackets), the last one is left as "fnref".

If you use numbers as the footnote reference labels, those numbers cannot be
used for footnote numbers -- they share a namespace.  If you want to use
those specific numbers, don't use auto-numbering: use [1], [2], [3] instead.
This deserves a mention in the spec.

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

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

Re: [Docutils-users] Re: FW: Another Problem with latex writer

[<eng...@ss...>]

On Thu, 13 Mar 2003, David Abrahams wrote:

> David Abrahams <da...@bo...> writes:
>
> >
> > Sorry, I'm having a hard time understanding anything you're saying
> > here, but latex just got much worse for our application, since we
> > have curly braces in our literal blocks.  Lines like this don't work
> > out too well:
> >
> >     \mbox{}}
>
> OK, I fixed a lot of bugs; here is the patch

thanks a lot.

you were a little greedy, this one::

  text = re.sub(r'[^{][\\]', r'{\textbackslash}', text)

will replace any the backslash AND the preceeding character (except for a
brace). AND there need to be two backslashes.

i commited to cvs.

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

Re: [Docutils-users] Re: FW: Another Problem with latex writer

[<eng...@ss...>]

On Thu, 13 Mar 2003, David Abrahams wrote:

> eng...@ss... writes:
>
> >> Which in turn is displayed as:
> >>
> >>     In keeping with our quest for polymorphism, lambda is also a unary
> >> metafunction returning a metafunction
> >>     class. In other words, we could have written
> >>     template <class X>
> >>     struct times4
> >>     : twice<\textbf{typename mpl::lambda<mpl::plus<_1,_1> >::type}, X>
> >>     {};
> >>
> >> Note the appearance of TeX directives in the output.
> >
> > because its inside verbatim, julien used obeyspace asf. but this never worked
> > for me. i modified it using an mbox with ttfamily, but tt seams to have no
> > bold style.
> >
> > in CVS.
> >
> >> I'm beginning to wonder about using this toolchain to get from
> >> ReST->PDF.  Maybe ReST->DocBook->PDF is a better bet.
> >
> > sure if you have docbook installed, why not.
> >
> > i am thinking about not removing the stryle.tex but moving as much as possible
> > into it, so it will function like the css.
>
> Sorry, I'm having a hard time understanding anything you're saying
> here, but latex just got much worse for our application, since we
> have curly braces in our literal blocks.  Lines like this don't work
> out too well:
>
>     \mbox{}}

sorry bout that.

the latex writer
================

posibilities
------------

1. produce a latex article: means use latex atitle,date,author.

   pro: latex supports more languages
   con: the docinfo would be printed inconsistent.

2. use latex as a page layout mechanism.

3. the latex_writer does only markup translations.
   e.g. when producing python documentation a special latex
   documentclass is used, with special markups for member-variables, ...

   the writer in the currentversion is useless for this (albeit
   the rest-input would need some special markup too).

problems arise simply from the fact, that
the latex-writer currently is used for pdfs with hyperlinks and
for hardcopies.


-- 
 BINGO: assertively disseminate unique opportunities
 --- Engelbert Gruber -------+
 SSG Fintl,Gruber,Lassnig   /
 A6410 Telfs Untermarkt 9  /
 Tel. ++43-5262-64727 ----+

[Docutils-users] Re: FW: Another Problem with latex writer

[David A. <da...@bo...>]

David Abrahams <da...@bo...> writes:

>
> Sorry, I'm having a hard time understanding anything you're saying
> here, but latex just got much worse for our application, since we
> have curly braces in our literal blocks.  Lines like this don't work
> out too well:
>
>     \mbox{}}

OK, I fixed a lot of bugs; here is the patch

[Docutils-users] Re: FW: Another Problem with latex writer

[David A. <da...@bo...>]

eng...@ss... writes:

>> Which in turn is displayed as:
>>
>>     In keeping with our quest for polymorphism, lambda is also a unary
>> metafunction returning a metafunction
>>     class. In other words, we could have written
>>     template <class X>
>>     struct times4
>>     : twice<\textbf{typename mpl::lambda<mpl::plus<_1,_1> >::type}, X>
>>     {};
>>
>> Note the appearance of TeX directives in the output.
>
> because its inside verbatim, julien used obeyspace asf. but this never worked
> for me. i modified it using an mbox with ttfamily, but tt seams to have no
> bold style.
>
> in CVS.
>
>> I'm beginning to wonder about using this toolchain to get from
>> ReST->PDF.  Maybe ReST->DocBook->PDF is a better bet.
>
> sure if you have docbook installed, why not.
>
> i am thinking about not removing the stryle.tex but moving as much as possible
> into it, so it will function like the css.

Sorry, I'm having a hard time understanding anything you're saying
here, but latex just got much worse for our application, since we
have curly braces in our literal blocks.  Lines like this don't work
out too well:

    \mbox{}}


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

[Docutils-users] footnote numbering?

[David A. <da...@bo...>]

I'm a bit confused about how footnote numbers are chosen.

http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/*checkout*/boost/boost/libs/python/doc/PyConDC_2003/bpl.txt?rev=HEAD&content-type=text/plain

Shows that my first and second numbered footnotes. [#1] and [#2], are
coming out as 3 and 4.  Whaaaa?

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