Re: reStructuredText module

[Philipp Gesang <philipp.gesang@alumni.uni-heidelberg.de>]

[-- Attachment #1.1: Type: text/plain, Size: 5578 bytes --]

···<date: 2013-03-12, Tuesday>···<from: Bill Meahan>···

> Philipp Gesang wrote:
> >···<date: 2013-03-11, Monday>···<from: Bill Meahan>···
> >>Am I correct in thinking the rst module does not process the "class"
> >>and "container" directives?
> >When I wrote the module I was working with the reST spec [0] and
> >the syntax reference [1]. It’s been a while, but afair I
> >implemented the spec completely (with the limitations described
> >in the manual). It does not, to my knowledge, define the
> >directives you mention and I don’t know what they’re supposed to
> >do.
> >
> >(Btw. like much of the spec, “container” and “class” sound
> >suspiciously HTML-specific. If that is true, they address one
> >output markup which happens to be -- not Context! I might find
> >the time to add a simple wrapper for the container thingy (to
> >boxes or framed?). However, I doubt that it’s possible to
> >replicate the behavior of HTML divs + CSS without a larger effort
> >[2]. In this case it might be preferable to have docutils
> >generate some XML and directly typeset the result with Context.)
> >
> >Best regards
> >Philipp
> 
> The .class and .container direectives are certainly there with *ML in mind but I think there might be analog situatins in ConTeXt.
> 
> .. class::  classname
> 
> 	blah, blah, blah
> 
> exists to stick a class name on the following element for styling with an external stylesheet of some sort. CSS/CSS3 are probably the primary examles but other XML-bases markus apply just as well
> 
> .. class::classname
> 
> 	blab, blab, blab
> 
> could yield
> 
>   <p class=classname>blab, blab, blab</p>
>   <h2 class=classname>blab. blab, blab</h2>
> 
> or anything else that can take a class name attribute.

From its description [0], the “class” directive appears to be
next to meaningless outside an HTML context. It’s supposed to set
“classes”. The doctree spec [1] explicitly states that “The
classes attribute's contents should be ignorable.”

To my knowledge, the closest thing in Context to CSS classes is
the “setups=” parameter. All macros don’t accept it, though, so
I can’t think of a general way of handling it. The list of macros
where it applies would have to be hardcoded ...

Docutils’ latex2 writer -- the reference implementation, mind
you -- btw. doesn’t take the “class” directive seriously at all:
it handles paragraphs but ignores it e.g. for section heads.

> .. container:: containername
> 
>   Foo, bar, baz
> 
>   bunch of stuff
> 
> yields
> 
>   <div class=containername>
> 
> 	foo, bar, baz
> 
> 	bunch of stuff
> 
>   </div>
> 
> .. container:: probably maps to something like
> \frame[containername]

> although frames as such cannot cross page boundaries. Perhaps
> there is (or could be) a more suitable construct. I'm trying to
> be exemplary not directive. :)

Fyi [2]: “container” is docutils for “div”. How’s a “div”
supposed to look? That depends on your browser (not the spec!),
and the HTML version being used (XHTML 1.1 for python2-docutils).
What does that mean for non-HTML targets? Apparently nothing:
again, docutils ignore the directive when writing LaTeX (and man
pages, for that matter).

Nevertheless, I added some code to handle container directives:
at the moment they simply map to macros of the same name.
Existence of the macro is tested for at runtime, so you can place
the definitions in your preamble. Example:

·································································

This is a paragraph.

.. container:: xyzzy

    whatever

    foo **bar** baz

This is another paragraph.

·································································

This will generate the output:

·································································

\startparagraph
This is a paragraph.
\stopparagraph

\ifcsname xyzzy\endcsname%
  \csname xyzzy\endcsname%
  {whatever foo {\sc bar} baz}%
\else
  {whatever foo {\sc bar} baz}%
\fi


\startparagraph
This is another paragraph.
\stopparagraph

·································································

So if there’s no \xyzzy, the contents are treated as a simple
group. Unnamed containers default to \framed. Let me know what
you think. The code is at:

  https://bitbucket.org/phg/context-rst/get/0df50df9c8fb.zip

> ConTeXt environment files are certainly analogus to CSS files and are used with the same end goals in mind.
> 
> "styling" markup elements through "class=" or equivalent is
> rapidly becoming the order of the day for a wide variety of
> documents. Certainly (X)HTML, epub2, epub3, ODT, DOCX and an
> increasing horde of others are either there or heading there very
> soon.

Sure. I have no problem with that as long as it stays
implementation-agnostic.

Thanks for the feedback.
Philipp



[0] http://docutils.sourceforge.net/docs/ref/rst/directives.html#class
[1] http://docutils.sourceforge.net/docs/ref/doctree.html#classes
[2] http://docutils.sourceforge.net/docs/ref/rst/directives.html#container


> 
-- 
()  ascii ribbon campaign - against html e-mail
/\  www.asciiribbon.org   - against proprietary attachments

[-- Attachment #1.2: Type: application/pgp-signature, Size: 198 bytes --]

[-- Attachment #2: Type: text/plain, Size: 485 bytes --]

___________________________________________________________________________________
If your question is of interest to others as well, please add an entry to the Wiki!

maillist : ntg-context@ntg.nl / http://www.ntg.nl/mailman/listinfo/ntg-context
webpage  : http://www.pragma-ade.nl / http://tex.aanhet.net
archive  : http://foundry.supelec.fr/projects/contextrev/
wiki     : http://contextgarden.net
___________________________________________________________________________________