Features Download

From: Felix Wiemann <Felix.Wiemann <at> gmx.net>
Subject: Re: [Docutils-checkins] r4307 - trunk/docutils/docs/dev/todo.txt
Newsgroups: gmane.text.docutils.devel
Date: Sunday 22nd January 2006 00:33:30 UTC (over 13 years ago)
David Goodger wrote:

> [email protected] wrote:
>> Modified:
>>    trunk/docutils/docs/dev/todo.txt
>> Log: turned "multiple output files" entry into a "generic data
>> handling" entry
> I don't see what one has to do with the other.
> What exactly do you mean by "multiple output files"?

More than one file coming out of a writer.  Examples:

HTML writer: HTML and CSS

S5-HTML writer: HTML, CSS, and S5 CSS/JS

A multi-page HTML writer: Many HTML files and CSS

HTML+AA writer: HTML, SVG, and CSS

The CSS stylesheet is not currently output by the HTML writer (i.e. no
CSS file is created) but only it is embedded or an existing file is
linked, but still the stylesheet handling is something that I'd want to
see handled by a general data file handler.

The CSS stylesheet could become a "data" object, which is either:

* Embedded into the HTML file (currently --embed-stylesheet),
* linked in its original location (currently --link-stylesheet), or
* created (e.g. in the same directory as the output HTML file) and
  linked from the HTML file (new option).

IMO there shouldn't be a difference between the handling of the S5 files
and the handling of the CSS file (except that the S5 files probably
cannot be embedded).

>>  It should be possible for a component to **emit or reference** data
>>  to be either **included or referenced** in the output document.
> This sentence doesn't make sense.  Can you express what you mean in
> a simpler way?

OK, I'll try to describe what I have in mind:

I want the following to be possible:

The HTML+AA writer generates an SVG data object and references it from
within the document (e.g. using an image node).  Or the HTML writer
creates a reference to an existing CSS stylesheet file.  We get a data
object like this:

# In the reST+AA parser; data is stored in the data object:
svgimage = data(data='...', name='aafigure-0.svg')
# In the HTML writer; data comes from an external file:
cssstylesheet = data(file='../docutils/writers/html4css1/html4css1.css',

Note that when instantiating data(file=...), the file is not read into
memory, because it might be a huge file and the file contents might not
be needed at all.

But otherwise there's no difference between whether the data is stored
in the object or an external file is referenced.  The data object
handles these two cases transparently.

When the data objects are to be written out, they can be either embedded
or linked.

# Write out the SVG file and link it using :
svgfilename = svgimage.get_filename()
# Or embed the SVG file (the ODT writer might do this):
svgdata = svgimage.get_data()

# Link the CSS file.
cssfilename = cssstylesheet.get_filename()
# Or write out the CSS file next to the output file and link it:
cssfilename = cssstylesheet.get_filename(force_copy=1)
# Or embed the CSS file.
cssstring = cssstylesheet.get_data()

data.get_data() will read the data from the input file if the data comes
from an external file and return the data as a string.
data.get_filename() will write the data to a file if the data does not
already come from an external file and return the file name.
data.get_filename(force_copy=1) will write the data to a new file
regardless of whether it comes from an existing external file or not and
return the file name.

New files are typically written next to the output file, but this can be
changed e.g. using a --aux-file-directory option.

The cool thing about this approach is that we can use the same input and
output code for CSS stylesheets, images, TeX stylesheets, or even S5
theme directories.  Otherwise we'd have to implement writing and/or
referencing more than one output file for each writer that needs it;
e.g. for the S5 writer, for the AA writer, and even for the HTML writer
which references its CSS file.  Even the comparably simple logic that
generates the CSS reference is complicated enough to have a bug
(absolute paths on Windows).  Thus, we should centralize all this logic
in the data object so that it doesn't have to be re-invented for every

Did I describe it better this time?  Should we add a reference to this
message to the to-do list entry, or do you want to extend the entry?

For private mail please ensure that the header contains 'Felix Wiemann'.

"the number of contributors [...] is strongly and inversely correlated with
number of hoops each project makes a contributing user go through."      --

This SF.net email is sponsored by: Splunk Inc. Do you grep through log
for problems?  Stop!  Download the new AJAX search engine that makes
searching your log files as easy as surfing the  web.  DOWNLOAD SPLUNK!
CD: 4ms