Re: [Docutils-users] indentaion in literal blocks

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

Brett g Porter wrote:
> I'm trying to document a C struct that's like:
> 
> ::
>     {
>         int field1;
>         int field2;
>     }
> 
> by keeping the code in literal blocks (in reality, it's a rather
> large struct, and not every member needs annotation, something like:
> 
> ::
>     {
>         int field1;
> 
> This is a clever note about field1
> 
> ::
> 
>         int field2;
> 
> this is another witticism
> 
> ::
>     }
> 
> ...but the indentation for the literal ``int field2;`` is not
> consistent (because it doesn't have the curly braces to give it that
> indentation context any more.
> 
> Suggestions for how to accomplish what I'm trying?

First, don't forget that you need a blank line after the "::" (it must
be alone or at the end of a paragraph).

The simplest way I can think of is to use some text to mark the left
edge of your literal block.  I'd choose ellipsis ("..."), since it
indicates "continuing...":

    ::

        ...
            int field2;

    this is another witticism

    ::

        ...
        }

Or the entire thing could be bordered on the left:

    ::

        |   {
        |       int field1;
        |       int field2;
        |   }

(When splitting up the block, preserve the border bars.)

Or even line numbers:

    ::

        13: {
        14:     int field1;
        15:     int field2;
        16: }

Another way would be to use the "parsed-literal" directive:

    .. parsed-literal::
       \
           int field2;

The backslash establishes the left edge but disappears after parsing.
You have to be careful with parsed-literals though, becuase any inline
markup *is* parsed.

Finally, a runtime setting (set via directives and/or command-line
options) could be introduced to establish fixed indentation levels.
The parser could then assume, for example, that Literal blocks always
begin 4 spaces to the right of the surrounding text.  This would
require implementation of course.  The quickest way to implementation
is to submit a patch!

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/