Re: [Docutils-users] simple conversion from reST to html -- remove heading backlinks

[The C. <cad...@gm...>]

On Nov 15, 2007 11:09 AM, David Goodger <go...@py...> wrote:
> Your code works just fine for me.
> Which version of Docutils, Python are you running, and what OS?

Thanks for the reply, David.

I'm using Ubuntu 7.10 (Gutsy). But I upgraded from the previous
version, upon which I think I installed docutils manually (not using
apt). During the upgrade to 7.10, if memory serves, I think there was
an issue, and I had to manuall rm the docutils modules to get things
to work. I may have botched things up.

$ dpkg -l | grep docut
ii  python-docutils            0.4-4    [snip]

$ rst2html -V
rst2html (Docutils 0.4.1 [repository])

$ python -V
Python 2.5.1

> Try running your text through the command-line version:
>
>     rst2html.py --dump-settings --link-stylesheet input.txt output.html
>
> Add --no-toc-backlinks and try again.  Compare the settings that are
> sent to stderr.

$ diff before after
56c56
<  'toc_backlinks': 'entry',
---
>  'toc_backlinks': False,


> It looks like the Docutils Configuration doc does have a typo though:
> it shouldn't specify 'none' but None or False (no quotes, note case).
> However, the way Docutils is coded, anything other than 'entry' or
> 'top' should have the same effect as None or False.  It shouldn't make
> a difference, but you could try changing
>
>                   'toc_backlinks': 'none'}
>
> to
>
>                   'toc_backlinks': None}
>
> I will fix the entry in Docutils Configuration.
>
> On 11/15/07, The Cadet <cad...@gm...> wrote:
> > it would be helpful if (somewhere) it said, "by
> > the way, you can also specify these as keys in a dict that you pass as
> > ``settings_overrides`` to docutils.core.publish.
>
> That's covered here:
> http://docutils.sourceforge.net/docs/api/runtime-settings.html
>
> The Docutils Configuration doc is aimed at non-developer users, but I
> will add a link to the doc above.

You might add at the top of the docutils configuration doc something
like, "This document is aimed at non-developers. However, the
information here is analogous to and can be directly applied to use of
the docutils API used by programmers. That is, any settings you can
set in your docutils configuration file (described below), can also be
set programmatically when passing arguments to
``docutils.core.publish_parts()``".

> > I've been guessing at what to put after ``'toc_backlinks':``, but
> > neither 0, 'none', nor 'false' seem to work.
>
> 0 ought to work too.  Note that 'false' is NOT a boolean false value
> in Python.  You want False (no quotes, capital F).
>
> > By the way, I'm glad that there seems to be pretty voluminous docs for
> > docutils, but I think they could be even better if they contained more
> > examples as well as pieces at the beginning of each doc saying
> > something like, "This document explains how to do thus and so. You'd
> > want to do that if you were trying to make docutils do
> > such-and-such.".
>
> Good idea.  Patches are welcome!

Unfortunately, as a fairly new user, it's very difficult to write doc
patches about software I don't yet understand. Chicken and egg.
However, I think input from new users is still valuable, because it
may give you an idea of what a new user perceives as missing or
unclear (documentation-wise). It's no fault of experienced developers
that they often forget what it's like to see a project's docs for the
first time.

> > Incidentally, it would be really handy if the ``rst2html`` tool had an
> > option to do exactly what I'm asking for above. Seems like a lot of
> > people would use it that way. Is there any particular reason there
> > isn't such an option? Or am I missing it? Just curious.
>
> rst2html is a tool for creating complete HTML documents.  There is no
> one portion which all users would want.  You want the 'fragment' part,
> others might want 'body' and 'title' separately, etc.  That's what the
> API is for.  And in most cases, portions are only needed from within
> code, not from the command line.
>
> Alternate answer: this is an open source project, and patches are welcome!

Are you interested in including an uber-simple
``rst2plainhtmlsnippet.py`` script with the docutils distribution?
Maybe something that could be a slightly-extended version of the code
I posted in my original message?

Note: the fact is that as reST gains popularity, various users (using
various languages) may want to be able to quickly and easily snap in a
way to convert reST snippets to clean html snippets. If rst2html had
an equivalent behaviour available, similar to the default behaviour of
Markdown.pl, then it would be a toss up for new users. They could pick
either and get a working (but lazy) solution in one line of code
(something like ``os.system('rst2plainhtmlsnippet input.txt
output.html')``). And that approach would work from Perl, PHP, Ruby,
whatever.

Sometimes I've heard this sort of thing discussed in terms of
"allowing users to just get their work done even if it might be
unsightly at times (a la Perl)", vs. "guiding users to only do things
by the book to keep things uniform (a la Python)". I'm not saying I
always agree with that comparison, but I think it's probably a big
reason why you find Perl scripts in every little weird crevice of the
Internet duct-taping things together.

Thanks.