I am working on a reply to this one as well. Please hold off for now, thanks.
On Thu, Dec 11, 2008 at 11:33, G. Milde <milde@...> wrote:
> On 11.12.08, David Goodger wrote:
>> On Wed, Dec 10, 2008 at 08:14, Guenter Milde <milde@...> wrote:
>> > On 2008-12-09, David Goodger wrote:
>> >> On Tue, Dec 9, 2008 at 07:19, Guenter Milde <milde@...> wrote:
> Dear David,
> thanks for your response. I am trying to get your point and find a
> common language. Due to my different background and native language
> this might be problematic sometimes, please be patient.
>> If the specified stylesheet is not accessible when the HTML is
>> deployed, that is a usage error. It is not up to Docutils to try to
>> prevent that.
> Exactly. The stylesheet must be at the specified location when you *view*
> the HTML, not when you *generate* it. Therefore Docutils cannot and will
> not check its presence during HTML export.
> OTOH, style-library-search depends on checking the presence of a file.
> This is why I planned to use style-search only for embedded stylesheets.
> As a future extension one could consider a scheme to check and complete
> relative paths with a stylesheet search (defaulting to the given path if
> the stylesheet is not found in any of the library dirs).
>> I think I see the problem. Look at the documentation for --stylesheet:
>> A comma-separated list of CSS stylesheet URLs, used verbatim.
>> The key is "verbatim".
> I agree with your definition of "verbatim".
> But, "used verbatim", to me means:
> with --link-stylesheet:
> the URL is inserted verbatim in the HTML file
> and used by the browser to access the specified file.
> with --embed-stylesheet:
> the URL is used verbatim by Docutils to access the specified file,
> read it and embed its content into the output document.
>> The fact that the --stylesheet option/setting does currently work with
>> --embed-stylesheet is a **bug**. It should be fixed, not made worse.
> What would you gain from preventing this combination?
> A proper fix would be to allow any URL (not just file paths), to access and
> embed the stylesheet file.
>> But for the HTML writer, the paths given to --stylesheet are to be
>> used as URLs only, verbatim. Relative paths are simply relative URLs.
>> They are **not** filesystem paths. That's what --stylesheet-path is
> Any (UNIX) file system path is a valid URL. In any 'file:<path>' URL,
> <path> is a filesystem path. This was an intentional choice by the
> designers of the URL syntax.
>> I think the LaTeX writer implementation and docs are very much confused
> IMO, the problem is that
> 1. the implementation with
> 2 mutually exclusive, overwriting options and
> 1 toggle (embed_stylesheet)
> is inconsistent and therefore hard to explain.
> 2. with --embed-stylesheet, the distinction between --stylesheet and
> --stylesheet path does not make sense, as Docutils inserts neither
> URL nor path but the *content* of the style-file into the generated
> 3. the HTML writer documentation is (or was) unclear, so when the LaTeX
> writer copied the HTML writer implementation and docs, it inherited
> (and maybe added to) this confusion, as even without full
> understanding it "just works".
>> >> --stylesheet-path=rel/path/to/stylesheet.css
>> > Similar to the current (undocumented) behaviour, the path is assumed to
>> > be relative to os.getcwd().
>> Let's document that behavior.
> This is now done in config.txt (but still missing in the --help output).
>> > with embed-stylesheet == True, it does not matter if you use
>> > --stylesheet or --stylesheet-path!
>> And that's a bug. Let's fix the bug, and not use its existence as
>> justification for additional complexity.
> My intention is to remove complexity.
>> > (Therefore, the "--stylesheet-path is recommended" hint in the
>> > description of --embed-stylesheet is not clear to me. Did I miss
>> > something?)
>> What description are you talking about?
> `rst2html.py --help`:
> --embed-stylesheet Embed the stylesheet(s) in the output HTML file. The
> stylesheet files must be accessible during processing
> (--stylesheet-path is recommended). This is the
> To me, *is recommended* (in an aside to the statement that a file must
> be accessible to be embedded) does by no means imply that using
> --stylesheet instead is considered wrong usage. As the generated
> document is exactly the same, I do not see any sense in this
>> And I'm still not convinced that we need anything more. This
>> discussion only shows what a can of worms it is.
> To me, the discussion shows that the current state of implementation and
> documentation is far from optimal.
> I agree that this should be fixed before new features can be added.
>> > the call to
>> > relative_path(relative_to, settings.stylesheet_path)
>> > in utils.get_stylesheet_reference_list() could be made conditional on
>> > embed_stylesheet == False.
>> I need to think about this more.
> How about the appended patch?
>> >> ... the docs for the latex2e writer versions of
>> >> --stylesheet and --stylesheet-path make no sense to me.
>> Please rethink in light of the above. In the HTML writer, the
>> semantics of the two are very different (--stylesheet == verbatim!),
> The --stylesheet argument is used verbatim in the LaTeX writer as well.
> The difference is that with LaTeX, you can only use a subset of URLs:
> file paths.
> This is clarified in the updated docs, see config.txt in the SVN.
> For the HTML writer, a corresponding entry could be:
> Like stylesheet__, but a file URL is expanded relative to the working
> directory [#pwd]_ , and rewritten to be relative to the output file (if
> there is a common part in the given path and the output file path).
>> I still do not agree with the entire premise though, that a
>> path-search algorithm should be added. Before working on the
>> implementation details any further, please concentrate on showing a
>> compelling use case. Convince me.
> Last time, you wrote that code convinces more than words...
> I will try to explain my vision in a followup.
> Lets fix the current state first.
> The following patch to utils.py and the html writer implement in my view
> a clearer logic of stylesheet handling by "disentangling" the aquisation
> and rewriting of stylefile references.
> Exec: svn 'diff' 2>&1
> Dir: /home/milde/Code/Python/docutils-svn/docutils/docutils/
> Index: utils.py
> --- utils.py (Revision 5812)
> +++ utils.py (Arbeitskopie)
> @@ -448,17 +448,24 @@
> return settings.stylesheet
> -def get_stylesheet_reference_list(settings, relative_to=None):
> +# Return 'stylesheet' or 'stylesheet_path' arguments as list.
> +# The original settings arguments are kept unchanged: you can test
> +# with e.g. ``if settings.stylesheet_path:``
> +# Differences to ``get_stylesheet_reference``:
> +# * return value is a list
> +# * no re-writing of the path (and therefore no optional argument)
> +# (if required, use ``utils.relative_path(source, target)``
> +# in the calling script)
> +def get_stylesheet_list(settings):
> Retrieve list of stylesheet references from the settings object.
> if settings.stylesheet_path:
> assert not settings.stylesheet, (
> 'stylesheet and stylesheet_path are mutually exclusive.')
> - if relative_to == None:
> - relative_to = settings._destination
> - return [relative_path(relative_to, sheet)
> - for sheet in settings.stylesheet_path.split(",")]
> + return settings.stylesheet_path.split(",")
> elif settings.stylesheet:
> return settings.stylesheet.split(",")
> @@ -596,7 +603,7 @@
> if self.file is not None:
> print >>self.file, filename
> def close(self):
> Close the output file.
> Index: writers/html4css1/__init__.py
> --- writers/html4css1/__init__.py (Revision 5812)
> +++ writers/html4css1/__init__.py (Arbeitskopie)
> @@ -253,19 +253,18 @@
> self.head_prefix_template % (lcode, lcode)])
> self.head = self.meta[:]
> + # stylesheets
> + styles = utils.get_stylesheet_list(settings)
> + if settings.stylesheet_path and not(settings.embedded_stylesheet):
> + styles = [utils.relative_path(settings._destination, sheet)
> + for sheet in styles]
> if settings.embed_stylesheet:
> - stylelib = os.path.join(os.getcwd(), 'dummy')
> - styles = utils.get_stylesheet_reference_list(settings, stylelib)
> - self.stylesheet = [self.embedded_stylesheet
> - % open(stylesheet).read()
> - for stylesheet in styles]
> - else:
> - styles = utils.get_stylesheet_reference_list(settings)
> + self.stylesheet = [self.embedded_stylesheet % open(sheet).read()
> + for sheet in styles]
> + else: # link to stylesheets
> self.stylesheet = [self.stylesheet_link % self.encode(stylesheet)
> for stylesheet in styles]
> self.body_prefix = ['</head>\n<body>\n']
> # document title, subtitle display
> self.body_pre_docinfo =