Docutils: Documentation Utilities

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 03/28/2014 02:26 AM, engelbert gruber wrote:
> if it is a onetime conversion, you could use the roles as
> described and make a conversion tool.

perhaps I'm do not see big picture. Doesn't that involve parsing
entire documents searching and replacing [] with :: ? In my case I
have documents that have escaped [] or ones inside non-parsable blocks
etc. (like preformatted blocks) so for me to "guess" which ones to
convert I still have to parse documents, no?

> wikilinks would mean, that any word has to be tested for camelcase
> and if so made a href ?

Luckily previous wiki engine (ZWiki) was using [Foo] notation for
Wikilinks. So I don't have to look for camelcase. However I do need to
look for chunks like above [Foo] in parts of the documents where they
are allowed and convert them.
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/

iD8DBQFTNckIyDrVuGfS98QRAj6AAJ9cHhwxrYK2sIvGcvWQLhRvKVyTiwCgiVSh
hhssDzPw4+Jaj9wiI7JlPxk=
=wtf+
-----END PGP SIGNATURE-----

-- 
    This communication is intended for the use of the recipient to whom it
    is addressed, and may contain confidential, personal, and or privileged
    information. Please contact us immediately if you are not the intended
    recipient of this communication, and do not copy, distribute, or take
    action relying on it. Any communications received in error, or
    subsequent reply, should be deleted or destroyed.
---

if it is a onetime conversion, you could use the roles as described
and make a conversion tool.

wikilinks would mean, that any word has to be tested for camelcase and if
so made a href ?

On 27 March 2014 20:58, Dmitry S. Makovey <dmitry@...> wrote:

> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> On 03/27/2014 03:34 AM, elena.valhalla@... wrote:
> > On 2014-03-26 at 19:40:19 -0600, Dmitry S. Makovey wrote:
> >> So far my google searches failed to come up with clean
> >> implementation of RST [pre/post] processing allowing me to add
> >> support for Wiki-like links. The stuff I found normally
> >> post-processes resuting HTML which is neither clean no kosher if
> >> you ask me :) Which brings me here.
> >
> > I've added something similar in one of my WIP by creating a custom
> >  role of the form::
> >
> > :wi:`Title|url`
> >
> > which works as a wiki-like link but is easier to manage using
> > standard docutils stuff than the usual ``[Title|url]`` of most
> > wikies.
> >
> > The implementation is proof of concept with no error checking etc.
> >  (and it is part of a mostly abandoned project), but here you can
> > see how I've done it: in rest.py_ I define a role function and
> > register it as a role and then simply run publish_file.
> >
> > .. _rest.py:
> >
> http://git.home.trueelena.org/gitweb/?p=software/wi.git;a=blob;f=wi/rest.py
> >
> >
> thanks. I was contemplating "roles" but my usecase is where I have a
> large pre-existing library of .rst files with WikiLinks in them that I
> would like to process. Doing "simple" regular expressions I already
> stepped on quite a few edge cases, since I was trying to [re]parse the
> document myself instead of relying on docutils' capabilities. That is
> why I'm looking to hook into docutils machinery just prior to final
> rendering and tweaking some nodes (actually their text). Assuming it's
> similar to DOM it should be easy to do.
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1
> Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/
>
> iD8DBQFTNILkyDrVuGfS98QRAu7AAJ9tGTeD+Glgurn+tXk4v9U4vtxqXgCgobwW
> 1MCANXw6cO1vcyVJ0w+c+VM=
> =DW1y
> -----END PGP SIGNATURE-----
>
> --
>     This communication is intended for the use of the recipient to whom it
>     is addressed, and may contain confidential, personal, and or privileged
>     information. Please contact us immediately if you are not the intended
>     recipient of this communication, and do not copy, distribute, or take
>     action relying on it. Any communications received in error, or
>     subsequent reply, should be deleted or destroyed.
> ---
>
>
> ------------------------------------------------------------------------------
> _______________________________________________
> Docutils-develop mailing list
> Docutils-develop@...
> https://lists.sourceforge.net/lists/listinfo/docutils-develop
>
> Please use "Reply All" to reply to the list.
>

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 03/27/2014 03:34 AM, elena.valhalla@... wrote:
> On 2014-03-26 at 19:40:19 -0600, Dmitry S. Makovey wrote:
>> So far my google searches failed to come up with clean
>> implementation of RST [pre/post] processing allowing me to add
>> support for Wiki-like links. The stuff I found normally
>> post-processes resuting HTML which is neither clean no kosher if
>> you ask me :) Which brings me here.
> 
> I've added something similar in one of my WIP by creating a custom
>  role of the form::
> 
> :wi:`Title|url`
> 
> which works as a wiki-like link but is easier to manage using
> standard docutils stuff than the usual ``[Title|url]`` of most
> wikies.
> 
> The implementation is proof of concept with no error checking etc.
>  (and it is part of a mostly abandoned project), but here you can
> see how I've done it: in rest.py_ I define a role function and
> register it as a role and then simply run publish_file.
> 
> .. _rest.py:
> http://git.home.trueelena.org/gitweb/?p=software/wi.git;a=blob;f=wi/rest.py
>
> 
thanks. I was contemplating "roles" but my usecase is where I have a
large pre-existing library of .rst files with WikiLinks in them that I
would like to process. Doing "simple" regular expressions I already
stepped on quite a few edge cases, since I was trying to [re]parse the
document myself instead of relying on docutils' capabilities. That is
why I'm looking to hook into docutils machinery just prior to final
rendering and tweaking some nodes (actually their text). Assuming it's
similar to DOM it should be easy to do.
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/

iD8DBQFTNILkyDrVuGfS98QRAu7AAJ9tGTeD+Glgurn+tXk4v9U4vtxqXgCgobwW
1MCANXw6cO1vcyVJ0w+c+VM=
=DW1y
-----END PGP SIGNATURE-----

-- 
    This communication is intended for the use of the recipient to whom it
    is addressed, and may contain confidential, personal, and or privileged
    information. Please contact us immediately if you are not the intended
    recipient of this communication, and do not copy, distribute, or take
    action relying on it. Any communications received in error, or
    subsequent reply, should be deleted or destroyed.
---

On 2014-03-26 at 19:40:19 -0600, Dmitry S. Makovey wrote:
> So far my google searches failed to come up with clean implementation
> of RST [pre/post] processing allowing me to add support for Wiki-like
> links. The stuff I found normally post-processes resuting HTML which
> is neither clean no kosher if you ask me :) Which brings me here.

I've added something similar in one of my WIP by creating a custom 
role of the form::

   :wi:`Title|url`

which works as a wiki-like link but is easier to manage using standard 
docutils stuff than the usual ``[Title|url]`` of most wikies.

The implementation is proof of concept with no error checking etc. 
(and it is part of a mostly abandoned project), but here you can see 
how I've done it: in rest.py_ I define a role function and register 
it as a role and then simply run publish_file.

.. _rest.py: http://git.home.trueelena.org/gitweb/?p=software/wi.git;a=blob;f=wi/rest.py

-- 
Elena ``of Valhalla''

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hi,

So far my google searches failed to come up with clean implementation
of RST [pre/post] processing allowing me to add support for Wiki-like
links. The stuff I found normally post-processes resuting HTML which
is neither clean no kosher if you ask me :) Which brings me here.

I did pick up that there are Readers, Parsers and Writers and that I
can drop in Transforms. However I'm a bit puzzled as far as sequence
goes. I did find a couple of resources pointing in some direction:
http://docutils.sourceforge.net/sandbox/codeintro/codeintro.txt and
http://www.webwareforpython.org/downloads/Wiki/ . However the former
seems to be unfinished while latter is a bit complex to grok on it's own.

What I'm looking for is a sample code that loads RST file, transforms
certain elements, then outputs the result.

So what I'm thinking is (really pseudo-code here):

my_reader=MyReader
my_parser=MyParser
my_writer=MyWriter

my_transform=MyTransform

my_writer.default_transform=(my_transform,)

my_rst="""
Title
=====
something [WikiLinkHere]

"""

parts=publish_parts(my_rst,reader=my_reader,parser=my_parser,writer=my_writer)

So what I want is to process document tree after it has been parsed
and built and before it's converted to, say HTML. Which in essence may
mean that I could use defaults instead of my_reader and my_parser, but
I am unsure. I noticed that there is "default_priority" which seems to
control order... Is there some sample/simple code to digest on this
subject?

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/

iD8DBQFTM4GDyDrVuGfS98QRAi3IAJ46hcFmafKROvzVpo/0TZVO848DKQCeM3sl
8U4Pvhd8ct1knIHRJ2atSg8=
=4fXk
-----END PGP SIGNATURE-----

-- 
    This communication is intended for the use of the recipient to whom it
    is addressed, and may contain confidential, personal, and or privileged
    information. Please contact us immediately if you are not the intended
    recipient of this communication, and do not copy, distribute, or take
    action relying on it. Any communications received in error, or
    subsequent reply, should be deleted or destroyed.
---

On 25 March 2014 06:41, phryk <phryk@...> wrote:
> On Mon, 24 Mar 2014 14:29:46 -0500
> David Goodger <goodger@...> wrote:
>
>> You can catch parsing exceptions from your code, but you can't resume
>> parsing after that.
>
> Thanks David, that would be fine by me. But publish_parts doesn't seem
> to throw any exceptions. I'm not really sure where I would be able to
> catch the parsing exceptions. I'd be thankful for any clarification on
> this.

You need to look at "Docutils Configuration":
http://docutils.sourceforge.net/docs/user/config.html

Specifically, the "halt_level" and "traceback" settings:

halt_level

The threshold at or above which system messages are converted to
exceptions, halting execution immediately. If traceback is set, the
exception will propagate; otherwise, Docutils will exit.

traceback

Enable Python tracebacks when halt-level system messages and other
exceptions occur. Useful for debugging, and essential for issue
reports. Exceptions are allowed to propagate, instead of being caught
and reported (in a user-friendly way) by Docutils.

Also see:

The Docutils Publisher
http://docutils.sourceforge.net/docs/api/publisher.html

Docutils Runtime Settings
http://docutils.sourceforge.net/docs/api/runtime-settings.html

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

Re: A custom HTML writer.

FWIW, I had to hack up the output of the HTML writer to make quick-n-dirty
scripts for my Radio Play as described here:
http://blog.project-kronosphere.timehorse.com/2009/04/1-page-1-minute.htmland
my current customized web browser for rendering is on the public
portion of my private SVN repository (sorry, no Git yet as my radio scripts
use Keywords and Git no likey):
https://svn.timehorse.com/public-repos/trunk/Code/Python%20Web%20Server/webserver.py.
 I hacked the CSS too, but I don't have that on the public server at
the
moment.  My point is *not* do like me, because using regex to post-process
your HTML is a real hack, I'm the first to admit.  But if you want an
example of how to do this, feel free to use my server for a template.

Jeffrey.

On Mon, 24 Mar 2014 14:29:46 -0500
David Goodger <goodger@...> wrote:

> You can catch parsing exceptions from your code, but you can't resume
> parsing after that.

Thanks David, that would be fine by me. But publish_parts doesn't seem
to throw any exceptions. I'm not really sure where I would be able to
catch the parsing exceptions. I'd be thankful for any clarification on
this.

	-- phryk

On Mon, 24 Mar 2014 21:59:49 +0100
Ben <benoit.allard@...> wrote:

> Did you looked at
> https://github.com/michaelbeaumont/docutils-html5css3 ?

No, I didn't. I only found another project that seemed sort-of-dead.
Thanks. :)

On 2014-03-24, Jean Lauliac wrote:

> ---

> ** [bugs:#252] <tt> is obsolete in HTML5**

> **Status:** open
> **Group:** repository
> **Created:** Mon Mar 24, 2014 09:04 PM UTC by Jean Lauliac
> **Last Updated:** Mon Mar 24, 2014 09:04 PM UTC
> **Owner:** nobody

> The [inline
> litteral](http://docutils.sourceforge.net/docs/user/rst/quickref.html#inline-markup)
> markup in reStructuredText seems to generate `<tt>` HTML tags. This
> [has been
> deprecated](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/tt).
> A decent alternative would probably to use the `<code>` tag.

> How do you think this should be addressed? I can make the change to use
> `<code>` if approved.

There are a "literal" as well as "code" role and directive in rST, so I
don't think this is a good match.

What is the recommended HTML5 inline equivalent to a <pre> block?

Otherwise, a <span class="literal"> might be the way to go.

Günter

On Sunday, March 23, 2014, phryk <phryk@...> wrote:

> Hey there,
>
> I'm currently writing the software for my next website which I want
> to properly integrate restructured text.
>
>         My site is using HTML5, but I'm currently using the html4css1
>         writer. How do I implement my own one? Can I subclass from the
>         html4 one and just override anything that differs?

Did you looked at https://github.com/michaelbeaumont/docutils-html5css3 ?
It is an html5/css3 writer.

Regards,
Ben

On 2014-03-23, phryk wrote:
> Hey there,

> I'm currently writing the software for my next website which I want
> to properly integrate restructured text.

> I peeked at a bunch of docs and code but I'm still unsure about a few
> things:

> 	My site is using HTML5, but I'm currently using the html4css1
> 	writer. How do I implement my own one? Can I subclass from the
> 	html4 one and just override anything that differs?

Yes. You may have a look at the "html_strict" writer in the docutils sandbox
as an example or starting point. It comes with a supplemental CSS sheet
and an rst2html_strict.py front-end.

Günter

On 23 March 2014 11:41, phryk <phryk@...> wrote:
> Hey there,
>
> I'm currently writing the software for my next website which I want
> to properly integrate restructured text.
>
> I peeked at a bunch of docs and code but I'm still unsure about a few
> things:
>
>         My site is using HTML5, but I'm currently using the html4css1
>         writer. How do I implement my own one? Can I subclass from the
>         html4 one and just override anything that differs?

Yes, that's a valid approach. Take a look at the PEP writer or the S5
HTML writer to see how it has already been done.

>         Parsing errors only show up in the published output.

No, errors are output to stderr also. The level of reporting is
configurable. Some errors will cause the process to terminate. That's
also configurable.

>         This is the opposite of what I want to happen; I want
>         the output to render everything that didn't fail and
>         handle the errors myself (basically just flashing a few
>         messages).

I don't know what that means. How would you "handle the errors"?

You can catch parsing exceptions from your code, but you can't resume
parsing after that.

>         I stumbled upon "Reporter" classes, but I'm neither sure of
>         whether they are what I need nor of how to implement one.

You could implement a Reporter subclass that doesn't insert system
messages into the output. I'd recommend against it though, since if
you aren't very careful you'll end up masking errors.

Use the Source, Luke: docutils.utils.Reporter.

Also, although our docs may not be complete, please read the docs we do have:
http://docutils.sourceforge.net/docs/

See PEP 258 and the Hacker's Guide for an overview of Docutils (its
components and how they fit together), and everything under api/.

>         If I want to set the 'title'-attribute of an HTML 'img'-element,
>         can I do this with the image nodeclass supplied by docutils or
>         do I have to define my own one?

Your own what?
How will you obtain the "title" attribute content?

You can add attributes to an existing node object.
You can subclass the existing HTML writer.
You can reimplement the "image" directive (or implement an alternative).

Again: Use the Source, Luke.

ISTM that you need to start with an overall understanding of how
Docutils works. The questions you're asking don't make much sense to
me.

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

On Mon, 24 Mar 2014 20:28:36 +0530
Purnank <purnank@...> wrote:

> Hi Phryk,
> 
> I needed html5 compliant output for generation of my epub (
> http://eclipsebook.in/appendix/buy-ebook/).
> You can find my development delta at
> https://github.com/purnank/docutils-code-html5epub3

If I understand correctly, this is a fork of docutils? Shouldn't it be
possible to just implement an html5 writer? But I at least don't see
anything that I think is an html5 writer in docutils/writers…

Hi Phryk,

I needed html5 compliant output for generation of my epub (
http://eclipsebook.in/appendix/buy-ebook/).
You can find my development delta at
https://github.com/purnank/docutils-code-html5epub3

On Sun, Mar 23, 2014 at 10:11 PM, phryk <phryk@...> wrote:

> Hey there,
>
> I'm currently writing the software for my next website which I want
> to properly integrate restructured text.
>
> I peeked at a bunch of docs and code but I'm still unsure about a few
> things:
>
>         My site is using HTML5, but I'm currently using the html4css1
>         writer. How do I implement my own one? Can I subclass from the
>         html4 one and just override anything that differs?
>
>         Parsing errors only show up in the published output.
>         This is the opposite of what I want to happen; I want
>         the output to render everything that didn't fail and
>         handle the errors myself (basically just flashing a few
>         messages).
>         I stumbled upon "Reporter" classes, but I'm neither sure of
>         whether they are what I need nor of how to implement one.
>
>         If I want to set the 'title'-attribute of an HTML 'img'-element,
>         can I do this with the image nodeclass supplied by docutils or
>         do I have to define my own one?
>
>
> Greetings,
>
>         phryk
>
>
> ------------------------------------------------------------------------------
> Learn Graph Databases - Download FREE O'Reilly Book
> "Graph Databases" is the definitive new guide to graph databases and their
> applications. Written by three acclaimed leaders in the field,
> this first edition is now available. Download your free book today!
> http://p.sf.net/sfu/13534_NeoTech
> _______________________________________________
> Docutils-develop mailing list
> Docutils-develop@...
> https://lists.sourceforge.net/lists/listinfo/docutils-develop
>
> Please use "Reply All" to reply to the list.
>

-- 
~~~~~~~~~~~~~~~~~~~~~~
I started liking it, then it became a hobby.
Soon it became a necessity. Today, I am addict to it.

Hey there,

I'm currently writing the software for my next website which I want
to properly integrate restructured text.

I peeked at a bunch of docs and code but I'm still unsure about a few
things:

	My site is using HTML5, but I'm currently using the html4css1
	writer. How do I implement my own one? Can I subclass from the
	html4 one and just override anything that differs?

	Parsing errors only show up in the published output.
	This is the opposite of what I want to happen; I want
	the output to render everything that didn't fail and
	handle the errors myself (basically just flashing a few
	messages).
	I stumbled upon "Reporter" classes, but I'm neither sure of
	whether they are what I need nor of how to implement one.

	If I want to set the 'title'-attribute of an HTML 'img'-element,
	can I do this with the image nodeclass supplied by docutils or
	do I have to define my own one?

Greetings,

	phryk

2002	Jan	Feb	Mar	Apr (5)	May (27)	Jun (22)	Jul (72)	Aug (82)	Sep (86)	Oct (138)	Nov (100)	Dec (62)
2003	Jan (122)	Feb (147)	Mar (92)	Apr (82)	May (101)	Jun (153)	Jul (37)	Aug (34)	Sep (46)	Oct (46)	Nov (6)	Dec (38)
2004	Jan (64)	Feb (81)	Mar (36)	Apr (194)	May (329)	Jun (272)	Jul (68)	Aug (74)	Sep (150)	Oct (57)	Nov (62)	Dec (63)
2005	Jan (78)	Feb (30)	Mar (137)	Apr (78)	May (54)	Jun (122)	Jul (72)	Aug (110)	Sep (80)	Oct (75)	Nov (125)	Dec (79)
2006	Jan (100)	Feb (15)	Mar (41)	Apr (67)	May (30)	Jun (11)	Jul (14)	Aug (22)	Sep (20)	Oct (14)	Nov (11)	Dec (15)
2007	Jan (17)	Feb (16)	Mar (35)	Apr (21)	May (33)	Jun (50)	Jul (12)	Aug (7)	Sep (2)	Oct (6)	Nov (5)	Dec (2)
2008	Jan (14)	Feb (20)	Mar (35)	Apr (9)	May (57)	Jun (21)	Jul (42)	Aug (4)	Sep (13)	Oct (76)	Nov (40)	Dec (55)
2009	Jan (26)	Feb (15)	Mar (3)	Apr (67)	May (32)	Jun (39)	Jul (59)	Aug (31)	Sep (59)	Oct (64)	Nov (21)	Dec (10)
2010	Jan (21)	Feb (3)	Mar (116)	Apr (33)	May (6)	Jun (28)	Jul (21)	Aug (23)	Sep (146)	Oct (70)	Nov (31)	Dec (57)
2011	Jan (33)	Feb (22)	Mar (11)	Apr (21)	May (51)	Jun (47)	Jul (35)	Aug (26)	Sep (25)	Oct (34)	Nov (61)	Dec (51)
2012	Jan (75)	Feb (31)	Mar (26)	Apr (16)	May (24)	Jun (24)	Jul (31)	Aug (46)	Sep (36)	Oct (28)	Nov (37)	Dec (21)
2013	Jan (16)	Feb (56)	Mar (31)	Apr (44)	May (45)	Jun (29)	Jul (38)	Aug (18)	Sep (12)	Oct (16)	Nov (21)	Dec (11)
2014	Jan (13)	Feb (14)	Mar (28)	Apr (2)	May	Jun	Jul	Aug	Sep	Oct	Nov	Dec

Error: CSS did not load.
This may happen on the first request due to CSS mimetype issues. Try clearing your browser cache and refreshing.

Docutils: Documentation Utilities

docutils-develop — For developer discussions of the implementation.

Error: CSS did not load. This may happen on the first request due to CSS mimetype issues. Try clearing your browser cache and refreshing.

Docutils: Documentation Utilities

docutils-develop — For developer discussions of the implementation.

Error: CSS did not load.
This may happen on the first request due to CSS mimetype issues. Try clearing your browser cache and refreshing.