Re: [Docutils-users] policy for new directives (was Using blockquote element for quotes)

[William D. <wi...@fl...>]

David Goodger <go...@py...> writes:

> William Dode wrote:
>  > What is the policy to include new directives in the core ?
> 
> If they're generally useful, properly written and documented, send
> them in!  I need to fully understand what they are and do though.
> References to document standards help, such as The Chicago Manual of
> Style or the Docbook DTD.  There must be such standards for
> journalists and/or for French-language documentation.

I found them in docbook :

exergue = epigraph
chapeau = highlights
inter-titre = bridgehead

> 
>  > With a book publisher we explore what we could need that are not in
>  > the core of docutils, and finaly there is only :
> 
> Thanks for the links to examples.
> 
>  > exergue
>  > chapeau (litle text of introduction, not sub-title, longer)
> 
> How is "chapeau" different from "exergue"?  Do you have an example
> containing both?

exergue is like "to my mother" or something like that
chapeau is a bigger text of introduction

> 
> I suspect the "class" directive may be able to handle these cases
> easily.  There was an issue that was delaying the implementation of
> "class": what to apply it to?  Enclosing element, or preceding, or
> following?  I recently had an idea that may resolve the issue:
> 
>      Idea: if the "class" directive has no content, it applies to the
>      enclosing element; useful for structural elements & containers
>      (sections, block quotes, etc.).  With content, it applies to the
>      content; useful for body elements (paragraphs, lists, etc.).
> 
>      (From <http://docutils.sf.net/spec/notes.html#misc-class>)

But a generic class attribute will not change a lot from doing a
customized directive like i did (really easy).
In the opposite, class attribute will help to do differents rendering of
epigraph...

> 
>  > intertitre (text between two paragraph, but not sub-section, often
>  > used in newspaper)
> 
> This seems to correspond to the DocBook `bridgehead element
> <http://www.docbook.org/tdg/en/html/bridgehead-x.html>`_.  I don't see
> a problem adding a "bridge" or "bridgehead" element to the Docutils
> doctree.  The only question is, is it a structural element (like a
> section or transition) or is it a body element (like a paragraph)?  If
> a body element, it could occur anywhere, including inside block quotes
> and table cells.  If a structural element, it can only occur at the
> top level of sections.

I think it's more like a body element, just a different paragraph.

epigraph and highlights are generaly in begin of a section but i don't
see reason to don't let us use it everywhere.

like you will see in the code, exergue is generaly a
FixedTextElement. <pre>

> 
>  > So, do you think theses directives could be put in the core ?
> 
> Send me the code and examples and I'll take a look.

please comment on my code, i really don't know if it's "the good way"...

#
#
# CUSTOMIZED DIRECTIVES
#
#

from docutils import nodes

class exergue_node(nodes.General, nodes.FixedTextElement): pass
class intertitre_node(nodes.General, nodes.TextElement): pass
class chapeau_node(nodes.General, nodes.TextElement): pass


def exergue(name, arguments, options, content, lineno,
               content_offset, block_text, state, state_machine):
    if not content:
        warning = state_machine.reporter.warning(
            'Content block expected for the "%s" directive; none found.'
            % name, nodes.literal_block(block_text, block_text), line=lineno)
        return [warning]
    text = '\n'.join(content)
    text_nodes, messages = state.inline_text(text, lineno)
    node = exergue_node(text, '', *text_nodes)
    return [node] + messages

exergue.content = 1

def chapeau(name, arguments, options, content, lineno,
               content_offset, block_text, state, state_machine):
    if not content:
        warning = state_machine.reporter.warning(
            'Content block expected for the "%s" directive; none found.'
            % name, nodes.literal_block(block_text, block_text), line=lineno)
        return [warning]
    text = '\n'.join(content)
    text_nodes, messages = state.inline_text(text, lineno)
    node = chapeau_node(text, '', *text_nodes)
    return [node] + messages

chapeau.content = 1

def intertitre(name, arguments, options, content, lineno,
               content_offset, block_text, state, state_machine):
    if not content:
        warning = state_machine.reporter.warning(
            'Content block expected for the "%s" directive; none found.'
            % name, nodes.literal_block(block_text, block_text), line=lineno)
        return [warning]
    text = '\n'.join(content)
    text_nodes, messages = state.inline_text(text, lineno)
    node = intertitre_node(text, '', *text_nodes)
    return [node] + messages

intertitre.content = 1


#
#
# CUSTOMIZED HTML WRITER (INLINE)
#
#

import sys
import os
import time
import re
from types import ListType
import docutils
from docutils import nodes, utils, writers, languages

from docutils.writers import html4css1

class Writer(html4css1.Writer):

    supported = ('html_wilk')
    """Formats this writer supports."""


    def __init__(self):
        writers.Writer.__init__(self)
        self.translator_class = HTMLTranslator



class HTMLTranslator(html4css1.HTMLTranslator):

    def astext(self):
        return ''.join(self.body)
        return ''.join( self.body_pre_docinfo
                       + self.docinfo + self.body + self.body_suffix)


    def visit_exergue_node(self,node):
        self.body.append(self.starttag(node, 'pre', CLASS="exergue"))

    def depart_exergue_node(self,node):
        self.body.append('</pre>\n')

    def visit_chapeau_node(self,node):
        self.body.append(self.starttag(node, 'p', CLASS="chapeau"))

    def depart_chapeau_node(self,node):
        self.body.append('</p>\n')

    def visit_intertitre_node(self,node):
        self.body.append(self.starttag(node, 'p', CLASS="intertitre"))

    def depart_intertitre_node(self,node):
        self.body.append('</p>\n')



-- 
William Dode - http://flibuste.net