Re: [Docutils-develop] stylesheet and embed-stylesheet

[Guenter M. <mi...@us...>]

On 2009-10-02, David Goodger wrote:
> On Fri, Oct 2, 2009 at 06:00, Guenter Milde <mi...@us...> wrote:
>> Dear David,

>> regarding the stylesheet option handling I see an inconsistency between the
>> documentation in BUGS.txt:

>>  The "stylesheet" setting (a URL, to be used verbatim) should be
>>  allowed to be combined with "embed_stylesheet".  The stylesheet data
>>  should be read in using urllib.  There was an assumption that a
>>  stylesheet to be embedded should exist as a file on the local
>>  system, and only the "stylesheet_path" setting should be used.

>>  -- goodger 30. Jul 2005

>> and config.txt:

>>  embed_stylesheet
>>    Embed the stylesheet in the output HTML file.  The stylesheet file
>>    must specified by the stylesheet_path__ setting and must be
>>    accessible during processing.

>>  -- goodger 11. Dec 2008

> What inconsistency? That embed_stylesheet requires stylesheet_path and
> not the URL-specifying stylesheet path? That's because config.txt
> documents the current state of the code, while BUGS.txt (like
> docs/dev/todo.txt) describes what ought to be or could be. 

However, the state of the code is such, that ::

   rst2html --stylesheet=/usr/local/styles/foo.css --embed-stylesheet

just works.

This might be described with

    The stylesheet file must specified by a path and must be accessible
    during processing.

while the current description in config.txt seems to reflect the attitude
stated in the "more on stylesheets for html4css1" thread:

   On 11.12.08, David Goodger wrote

   The fact that the --stylesheet option/setting does currently work with
   --embed-stylesheet is a **bug**. It should be fixed, not made worse.
   

>> Did the pre-2005 assumption resurface?

> I'm not entirely comfortable "fixing" that bug. I think it's
> reasonable to require any stylesheet to be present on a local
> filesystem for it to be embedded in an output file, and I think it's
> reasonable not to fetch remote files with urllib (we don't need that
> complexity, or that risk).

> I'll add the above to the bug and mark it as "requires discussion".

Discussion
----------

1. Is the current state of the code 
   
   a) a BUG or 
   
   b) just not properly documented (and maybe a missing feature)?

2. If it is a BUG, shall we:

   a) test and report ::
   
        if stylesheet and embed_stylesheet:
	   reporter = ...
	   
      (But what level should this be given, considering that it
      currently "just works" if the argument is a filesystem path.)
      
   b) support fetching stylesheets also with non-path URLs (maybe just
      local).
   

My preference is 1.b), because I do not see why a configuration like

   stylesheet: /usr/local/styles/mystyle.css
   embed-stylesheet: no
   
should trigger an error if I want to embed the chosen default with

   rst2html --embed-stylesheet

and force me to use

   rst2html --embed-stylesheet --stylesheet-path=/usr/local/styles/mystyle.css

Günter