Re: [Docutils-users] Re: sidebar:: contents::

[David G. <go...@py...>]

[Felix Wiemann]
 > In general, on the topic of special classes:
 >
 > We can document certain classes as official and implement support in
 > all writers, and then it wouldn't be a hack anymore.

"Officially sanctioned hacks"?  ;-)

 > After all, we do have special classes, like the "contents" class of
 > topic elements, which may need to get interpreted by the writer.  So
 > there's nothing wrong with assigning a special meaning to certain
 > classes (in certain contexts).

It feels a bit dirty though.  A bit of a "bad smell".

 > In this particular case (the "sidebar" class used with a TOC), I'd
 > say it is OK that the class is only interpreted by the HTML writer.
 > I cannot think of an occasion where I saw something like a "sidebar"
 > with text floating around in a typeset document.

I have, many times, and I'm pretty sure you have too, even if you
don't realize/remember it.  Sidebars are often used in magazine
articles and popular non-fiction books like how-to books; I'm sure
there are other cases also.

 > What about creating a docs/users/writers/ directory and putting all
 > writer documentation there (latex2e.txt, html4css1.txt)?

Users don't know or care about writers.  docs/users/tools/ perhaps, or
just docs/users/rst2html.txt etc., extending docs/users/tools.txt.
Any new documentation is welcome, especially user-oriented docs.

 >> What does the LaTeX writer do now?
 >
 > The current rendering of sidebars is a centered grey box with 90%
 > width, without text floating around it, which seems quite
 > reasonable.

That's one possible rendering.  It ought to be customizable via the
LaTeX stylesheet.  Is it?

 > However, a thing which *is* bad is allowing table of contents in
 > sidebars.
 >
 > The reason is that in this case the sidebar does not carry meaning
 > ("parallel document outside of the flow of the main text") but style
 > ("on the right, with text floating around").  That's a bad thing (in
 > terms of design).

I disagree.  That style is simply the HTML manifestation of the
meaning.

 > Someone who writes ::
 >
 >     .. sidebar::
 >
 >        .. contents::
 >
 > presumably does not want to get the table of contents in some grey
 > box (which is how sidebars are currently rendered in LaTeX) when
 > using LaTeX output.

I think your presumption is presumptuous.  Why wouldn't that rendering
be acceptable?  It seems reasonable to me.  And if that particular
rendering isn't desired, another could be imposed by the stylesheet.

 > Instead, while the author wants a floating TOC in HTML, when
 > generating a typeset document with LaTeX he will probably be
 > perfectly fine with a normal TOC.
 >
 > So ::
 >
 >     .. contents::
 >        :class: sidebar
 >
 > would indeed be the appropriate way of describing a sidebar-TOC in
 > reST, because the style information ("sidebar") is not contained in
 > a logical reST element (a sidebar directive) but in the class
 > attribute.

That's very roundabout logic.  If an author wants a TOC in a sidebar,
they should get the real thing, not a pale substitute of a hack.

 > Thus I propose prohibiting TOCs in sidebars (while still allowing
 > topics in sidebars)

-1.  I don't think this special case is special enough to bother.  A
Docutils TOC is implemented as a topic, and now topics are allowed
inside sidebars, and that's OK.

Docutils-generated TOCs vs. LaTeX-native TOCs is another issue.  I
seem to have found a bug in
docutils.writers.latex2e.LaTeXTranslator.visit_topic:

     def visit_topic(self, node):
         self.topic_classes = node['classes']
         if self.use_latex_toc:
             self.body.append('\\tableofcontents\n\n\\bigskip\n')
             self.topic_classes = []
             raise nodes.SkipNode

Should the '\\tableofcontents' be added unconditionally?  There are
non-TOC topics as well, topics without 'contents' in the classes
attribute.

Currently, if a "contents" directive is added, a TOC topic containing
a bullet list is generated, and then later the LaTeX writer ignores
it.  Either the writer should ignore the topic completely (with "raise
nodes.SkipNode", but *only* if it's a topic whose classes attribute
contains 'contents'), or the Docutils TOC should never be generated in
the first place.

--
David Goodger <http://python.net/~goodger>