Re: [Docutils-develop] Annoying stylesheet warning with rst2html.py

[Martin B. <mar...@gm...>]

On 9/8/05, David Goodger <go...@py...> wrote:
> [Martin Blais]
> > Something was changed with rst2html.py that rubs the wrong way: I
> > don't know exactly what came out of the long flurry of stylesheet
> > options emails on the list, but the fact that now rst2html.py spits
> > out a warning because I did not specify a stylesheet makes no sense
> > to me::
> >
> > docutils.txt:: (WARNING/2) No stylesheet path or URI given.  Use the
> > --stylesheet or --stylesheet-path option to specify the location of
> > default.css (in the tools/stylesheets/ directory of the Docutils
> > distribution).
> >
> > If I don't specify a stylesheet, it's obviously because I don't want
> > a stylesheet.
>=20
> Ah, but a stylesheet is required.  That's been in the FAQ for a long
> time, and I've just clarified it in docs/user/tools.txt.  If you
> really don't want a stylesheet, --stylesheet=3D'' does the job.
>
> It boils down to this: without a stylesheet, the generated HTML
> doesn't render correctly.  Many users haven't been using a stylesheet
> properly, and Docutils hasn't been telling them they should've been
> using one, so it was decided to make settings.embed_stylesheet default
> to on/1.  An embedded_stylesheet setting of on/1 with no stylesheet
> defined is an error.

Then why not embed the default stylesheet by default?

Too bad it produces a large HTML file this way, but such if the nature
of the produced HTML the writer produces (it requires a stylesheet to
render right).


> > You should not force the user to specify --stylesheet=3D
> > just in order to get a clean conversion (i.e. no warning).
>=20
> I don't much like this solution either ("required options", natch),
> but I can't think of a better one.

(above)

> > I don't want to create a docutils.conf file just to convert a
> > document either.  And for those people who want stylesheets, they
> > will look for them when they realize their document has none.
>=20
> They don't though.

Hmmm, that's their problem, isn't it?


> > It used to be broken (default.css would be automatically set).  As
> > far as I'm concerned, it is still broken: I have to specify a
> > non-option just to avoid getting a useless warning.
>=20
> What's the alternative then?  How can we fix the problem, so it's no
> longer broken?  I'd say we've chosen the lesser of two evils.
>=20
>     Errors should never pass silently.
>     Unless explicitly silenced.
>=20
> > I get caught every time
>=20
> Do this then:
>=20
>     $ cat >> ~/.docutils <<'EOF'
>     [general]
>     stylesheet:
>     EOF
>=20
> Or suggest a better alternative.  Don't rant ;-)

Again, embed the default stylesheet by default.

Required options make no sense.
I fail to see how a required option should not be an argument instead.
If you really want such a required option, then the usage of
rst2html.py should become:

  rst2html.py <stylesheet> <input.txt> <output.html>:

But IMO the default embedding would be better.

cheers,