headers
G. Milde | 1 Jun 2007 11:53
Picon

Re: rst2latex doesn't like deep section level .

On 31.05.07, grubert <at> users.sourceforge.net wrote:
> On Thu, 31 May 2007, G. Milde wrote:
> >
> > OTOH, \paragraph and \subparagraph section headings are (in the standard
> > layout styles) followed by the paragraph text *on the same line*, even if
> > it is separated from the section header by a blank line.
> >
> > However, with a trailing \leavevmode, the paragraph text starts on a new
> > line. This is a layout decision I would rather see unchanged or changed
> > in the stylesheet (via a \renewcommand{\subparagraph}{...}) than hard
> > wired.

> but the way paragraph and subparagraph are used as section titles one
> might expect that the text starts on a new line.

Not necessarily. Starting content on the same line is a way to mark the
lower level of the section heading in the LaTeX standard layout styles
(article, report, book, ...). 

The problem is to find a consistent markup of section titles that

* provides clear visual differentiation of the section level and 
* does not make high-level section titles too big (or bold)

under the constraint that latex output is targeted at printedr documents,
typically black-and-white.

One special LaTeX method to address this problem is the adding of the
"chapter" section level at the top end in report and book styles.
(Continue reading)

Permalink | Reply | 0 comments |
headers
G. Milde | 1 Jun 2007 12:33
Picon

Re: code-block directive

On 30.05.07, Alan G Isaac wrote:
> On Wed, 30 May 2007, David Goodger wrote:

> >     .. code-block:: python 
> >        while indented: 
> >            print "Python code here" 

> Is a ``code-block`` directive like this destined soon for reST?  

If I got David right, this is the reST syntax that will be used for
inclusion of source code that should be parsed and output with syntax
highlight by docutils.

> Is that better than an explicit ``literal`` directive?

Yes. (it is shorter (and IMO nicer) and backwards compatible to the
majority of existing `highlighting extensions`_.

> (It doesn't exist yet, right? Not documented anyway.)

It does *not* exist in the core docutils but is already used by many
`highlighting extensions`_.

You can use it in your documents right away and translate it to HTML or
LaTeX with the `pygments enhanced docutils front ends`_.

Once syntax highlight support becomes a standard docutils feature, the
uncha documents should be translable with the standard front ends without
need for change. However, there might be the need for a different
style-sheet than the one provided at the link above.
(Continue reading)

Permalink | Reply | 0 comments |
headers
G. Milde | 1 Jun 2007 13:13
Picon

Re: code-block semantics

On 31.05.07, David Goodger wrote:
> On 5/31/07, Alan G Isaac <aisaac <at> american.edu> wrote:
> > ::
> >
> >     .. include:: mycode.py
> >        :literal:
> >        :class: listing python
> >
> > is not equivalent to allowing (for example)::
> >
> >     .. include:: mycode.py
> >        :code-block: python

> That is correct.

If I got it right, the first example corresponds to::

    :class: listing python

    ::

       # file: mycode.py
       print "hello world"

The parser will convert it to a "literal_block" doctree element
without parsing and attach the class info.

The current standard latex writers should ignore the class information.

However, it would be possible to create a latex writer that is `aware` of
(Continue reading)

Permalink | Reply | 0 comments |
headers
G. Milde | 1 Jun 2007 14:07
Picon

Re: code-block semantics

On 31.05.07, Alan G Isaac wrote:
> On Thu, 31 May 2007, David Goodger apparently wrote: 
> > What's the practical difference between these?  ...
> > <code_block language="python">
> > <literal_block classes="code-block python"> 

> The problem, unless I misunderstand, is that such names of classes are 
> completely arbitrary and have no semantic content (in the context of
> Docutils).

This is only partially correct: class names have no semantic
content for the docutils *parser* but might have semantic content for
a subset or all of docutils *writers*.

The practical difference between the above examples is that 

* in the first case all docutils writers need to be updated to handle a
  <code_block> doctree element.

* in the second case, writers are "free" to ignore the class information
  (and should already be programmed to do so).

This is why I prefer the second implementation proposal.  

> Isn't there a distinction between the following?

> - keeping responsibilities separate *in* Docutils
> - allowing (not requiring) some responsibilities to be 
>   passed outside of Docutils
(Continue reading)

Permalink | Reply | 29 comments |
headers
Alan Isaac | 1 Jun 2007 15:51
Picon
Favicon

Re: code-block semantics

On Fri, 1 Jun 2007, "G. Milde" wrote: 
> This is only partially correct: class names have no semantic 
> content for the docutils parser but might have semantic content for 
> a subset or all of docutils writers. 

But this really obscures the issue I'm discussing, it seems to me.
Any class name I introduce presumably has semantic content 
for me, and sure I can create a new writer to recognize that 
semantic content, but this is really beside my point.

My point is that code blocks are a common use case, that 
they have an associated language, and that it makes sense 
for Docutils to embody these semantics (*rather* than just
saying "oh well, its just a literal block, add a class if you wish").

> * in the first case all docutils writers need to be updated to handle a 
>   <code_block> doctree element. 

Surely writers are written to be robust to newly defined 
elements??  Otherwise anytime a new element is introduced 
this will break all Docutils writers.  (By robust, I simply 
mean that there is a standard practice for element substitution in 
such instances.)

> * in the second case, writers are "free" to ignore the class information 
>   (and should already be programmed to do so). 
> This is why I prefer the second implementation proposal. 

This again raises my previous question.
I also do not understand your *implementation* proposal.
(Continue reading)

Permalink | Reply | 28 comments |
headers
G. Milde | 1 Jun 2007 16:07
Picon

code-block directive

On 30.05.07, David Goodger wrote:
> On 5/30/07, G. Milde <milde <at> users.berlios.de> wrote:

> I think the syntax highlighting should be done by a directive, while
> being parsed by the parser.  There's no need to delay processing (by a
> transform).  The syntax should be something like this:

>     .. code-block:: python

>        while indented:
>            print "Python code here"

Looks good to me. Clean, clear, and compatible with many existing extensions.

> > Is there a way to do this as "plug-in" (Analog to the examples in
> > http://docutils.sf.net/docs/howto/rst-directives.html)?

> I don't know what you mean by this.

An working example of the "code-block" directive is implemented in
`rst2html-pygments`_ following a receipe in
http://pygments.org/docs/rstdirective/ which seems to be based on the
howto in http://docutils.sf.net/docs/howto/rst-directives.html. It uses
the function::

  directives.register_directive('code-block', pygments_directive)

to implement the directive where the `pygments_directive` function is,
however, writer-specific. If I understand it right, it injects "raw"
content targeted at a specific writer into the document tree.
(Continue reading)

Permalink | Reply | 5 comments |
headers
David Goodger | 1 Jun 2007 17:24
Favicon

Re: code-block directive

On 6/1/07, G. Milde <milde <at> users.berlios.de> wrote:
> Would it be possible to write a front-end script analog to
> rst2html-pygments_ that implements "the right way" of
> sourcecode parsing and uses pygments to
> produces a "rich" literal-block doctree element.

Yes.

> In other words, how could I "plug-in" the code from the
> `proof of concept`_ into docutils so that it will process
> an input file and not just a sample string?

Exactly the same way.  The only difference is that the new directive
will return a "literal_block" node (the other directive returned a
"raw" node).

> .. _proof of concept:
>    http://pylit.berlios.de/features/pygments_with_docutils.py

I get 403 Forbidden on that.

--

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

-------------------------------------------------------------------------
This SF.net email is sponsored by DB2 Express
Download DB2 Express C - the FREE version of DB2 express and take
control of your XML. No limits. Just data. Click to get it now.
http://sourceforge.net/powerbar/db2/
(Continue reading)

Permalink | Reply | 0 comments |
headers
G. Milde | 1 Jun 2007 17:30
Picon

Re: code-block semantics

On  1.06.07, Alan Isaac wrote:
> On Fri, 1 Jun 2007, "G. Milde" wrote: 

> My point is that code blocks are a common use case, that 
> they have an associated language, and that it makes sense 
> for Docutils to embody these semantics 

Agreed.

> (*rather* than just saying "oh well, its just a literal block, add a
> class if you wish").

This was my receipt for bypassing the parsing by the docutils reader as
proposed by David for the content of a "code-block" directive.

> I also do not understand your *implementation* proposal.
> Please elaborate.

After finding out that the raw content of a literal block is stored in
the document tree as 'raw_source' attribute by the `proof-of-concept`_
script, I could imagine a custom latex-writer that undoes the
parsing. It would

* check "literal-block" doctree elements for "code-block" in the 'class'
  argument values,

* if found 

  + eventually replace the parsed content of the element with the
    content of its 'raw_source' argument
(Continue reading)

Permalink | Reply | 14 comments |
headers
Alan G Isaac | 1 Jun 2007 17:44
Picon
Favicon

Re: code-block semantics

On Fri, 1 Jun 2007, "G. Milde" apparently wrote: 
> After David's statement that parsing of a code-block 
> should happen in the docutils reader, I assume this as 
> existent part of a specification of a future ``.. 
> code-block::`` directive. 

Yes.  I did not have enough context when I used that name.
I apologize for any resulting confusion.

> I don't see the need for an additional non-parsing 
> directive. And I see the proposal of a non-parsing 
> directive under the name "code-block" as confusing. 

But what do you think about my two requests (in my last
message)?  Are these problematic or reasonable?  And my 
final question?

Thank you,
Alan Isaac

-------------------------------------------------------------------------
This SF.net email is sponsored by DB2 Express
Download DB2 Express C - the FREE version of DB2 express and take
control of your XML. No limits. Just data. Click to get it now.
http://sourceforge.net/powerbar/db2/
Permalink | Reply | 11 comments |
headers
Alan G Isaac | 1 Jun 2007 17:44
Picon
Favicon

Re: code-block directive

> On 30.05.07, David Goodger wrote: 
>> I think the syntax highlighting should be done by 
>> a directive, while being parsed by the parser.  There's 
>> no need to delay processing (by a transform).  The syntax 
>> should be something like this: 
>>     .. code-block:: python 
>>        while indented: 
>>            print "Python code here" 

On Fri, 1 Jun 2007, "G. Milde" apparently wrote: 
> Looks good to me. Clean, clear, and compatible with many 
> existing extensions. 

Two user requests as you go this direction:

1. support this for the ``include`` directive.  E.g., ::

    .. include:: mycode.py
       :code-block: python

2. Allow docutils parsing for syntax highlighting to be
   turned off.
   (Yes, this is another attempt to get a literal block
   in a code-block element, but it seems like a very
   reasonable way given the project here, no?)
   Maybe something like

    .. code-block:: python
       :literal:
(Continue reading)

Permalink | Reply | 3 comments |

Gmane