Re: [Docutils-develop] roadmap for html writers

[Tony N. <to...@gi...>]

On Mon, Mar 16, 2015 at 9:08 AM, David Goodger <go...@py...> wrote:

> On Sun, Mar 15, 2015 at 4:20 PM, Guenter Milde <mi...@us...> wrote:
> > Dear David, dear Docutils developers,
> >
> > On 2015-03-13, Tony Narlock wrote:
> >
> >> What's the current state of html_base?
> >
> > It is a "brand new"¹ writer that needs some more "road testing" before we
> > can put it on productive use.
> >
> > ¹ It is based on the "html-strict" writer that lived in the sandbox for
> >   several yeas and has been used by me without problems in this time,
> >   but, e.g., never been tested with IE.
> >
> >   Also, I don't know whether there was something lost or broken in the
> >   process of moving and re-structuring the writers and the CSS
> stylesheets.
> >
> >> * Should html_base be changed to the default?
> >
> > The other way round: the default might be changed to point to html_base
> (see
> > below).
> >
> >> * Should an argument be added to specify a Writer by name?
> >
> > All writers can already now be imported by their specific name as well
> as by
> > aliases defined in ``docutils.writers._writer_aliases``.
> >
> >> For ./tools/rst2html.py and ./tools/rst2html5.py:
> >
> >> * Should they be consolidated into one with the option to specify Writer
> >> through arguments?
> >
> > I'd rather go for a set of front ends, an additional option would
> > complicate things a lot.  (The command line options are collected from
> > the various docutils components. We get a "hen and egg" problem.)
> >
> >
> > My proposal for the future development is as follows:
> >
> > * release 0.12 with
> >
> >   - 3 HTML writers:
> >
> >       html4css1 (alias html),
> >       xhtml11 (alias xhtml),
> >       html-base (alias html5).
>
> I caution very strongly against exposing the base HTML module to
> production use. Better to keep it an abstract implementation, extended
> by the various concrete implementations. If the base module is
> concrete, we risk incompatibilities with specific flavors of HTML that
> import from the base. If I'm wrong, please explain why. Wouldn't it be
> better to have an "html5" writer that also imports from base_html?
> Initially, it would be a very thin wrapper, but I expect that as HTML
> evolves, that will change.
>
> >   - 4 front ends:   rst2html1css2.py, rst2xhtml.py, rst2html5.py,
> rst2html.py
>
> What is "rst2html1css2.py"? I suspect a typo, since HTML 1 is ancient.
> And that name is just too long; drop the "css2" part. Too specific.
>
> Is there anything specific to one version of CSS or another in the
> HTML output generated? I'm not talking about the .css stylesheets, or
> the templates, but the actual HTML generated by the Docutils code.
> There's nothing precluding anyone from adding some CSS2 in the
> templates or stylesheets they combine with the output of rst2html.py,
> is there? We should drop the over-specific naming.


Take a look at rst2xhtml11.py, rst2html5.py, rst2html.py. The only
difference I see is description and writer_name. Is that enough to justify
a separate file being made?

What if we just used rst2html.py as front end for all the html writers and
have a writer_name argument? Perhaps an environmental variable
(DOCUTILS_HTML_WRITER_NAME?) could also be used for users/servers that want
to save their go-to writer on their shell.

According to what I understand so far, perhaps we're at the level of
abstraction where we should be going the opposite direction, consolidating
the front end (X)HTML writers into rst2html.py?


> >   - the current default: keep html4css1 as "standard HTML writer" that is
> >     as expansion of the "html" alias and used by rst2html.py.
> >
> > * announce a future change of the default to the new "html-base" writer.
> >
> >   - users/projects wanting to do the change on their on pace, should now
> >     change to calling html4css1 instead of html rsp. rst2html1css2.py
> >     instead of rst2html.py
> >
> >   - users/projects wanting to test or switch to the new writers, can do
> this
> >     already by importing html-base, xhtml or html5 writers.
> >
> > * After some time for road testing, feedback and adjustments, a new
> release
> >   can change the default. Especially, we need feedback from the
> "downstream
> >   projects" like rst2web and Sphinx.
> >
> >   The "html" default writer should be generic and keep using syntax that
> is
> >   compatible with xhtml1.0 (transitional) ("polyglot" documents).
> >
> >   A separate "html5" writer can inherit from html_base and make use of
> new
> >   elements in HTML 5 (e.g. <aside> for footnotes and sidebar).
> >
> >
> > Dear David and Engelbert: I am especially interested in your opinion
> towards
> > such a big move.
>
> I'd like to see the specific mapping of front-ends to modules they'll
> import.
>
> --
> David Goodger <http://python.net/~goodger>
>
>
> ------------------------------------------------------------------------------
> Dive into the World of Parallel Programming The Go Parallel Website,
> sponsored
> by Intel and developed in partnership with Slashdot Media, is your hub for
> all
> things parallel software development, from weekly thought leadership blogs
> to
> news, videos, case studies, tutorials and more. Take a look and join the
> conversation now. http://goparallel.sourceforge.net/
> _______________________________________________
> Docutils-develop mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-develop
>
> Please use "Reply All" to reply to the list.
>