David Goodger | 2 Oct 06:29 2005

XML serialization change for list-value attributes

Today I implemented a change to how list-valued attributes are
serialized by the Docutils-XML and pseudo-XML writers (revision 3915).
I haven't seen a message on docutils-checkin about it, possibly
because of issues that BerliOS is currently having.  For this reason
and as a general notification, I'm describing the change here.

There are 5 node/element attributes that have lists as attributes:
ids, classes, names, dupnames, and backrefs.  All but "backrefs" are
common attributes; all elements can have these attributes.
Previously, when serialized, list values were simply joined by spaces.
Now, embedded spaces and backslashes are backslash-escaped so that
tools can see the difference between spaces embedded in values and
spaces used to separate multiple values.  This encoding was proposed
in a 2005-09-09 docutils-develop post (subject: "Re: Parsing XML") by
Felix Wiemann.

For example, after parsing and applying transforms to this input:

    .. _chained:
    .. _internal hyperlink:

    This paragraph referenced.

this is the result:

    <target refid="chained">
    <target refid="internal-hyperlink">
    <paragraph ids="internal-hyperlink chained"
     names="internal\ hyperlink chained">
        This paragraph referenced.
(Continue reading)

Felix Wiemann | 3 Oct 18:15 2005
Picon
Picon

Re: The docutils Zen garden

Martin Blais wrote:

> Hey, just had an idea: we should set up something like the CSS zen
> garden -- the docutils Zen garden!

Fine with me (i.e. I'd be willing to invest some time) when we have more
stylesheets.  Submissions welcome!

--

-- 
For private mail please ensure that the header contains 'Felix Wiemann'.

"the number of contributors [...] is strongly and inversely correlated with the
number of hoops each project makes a contributing user go through."      -- ESR

-------------------------------------------------------
This SF.Net email is sponsored by:
Power Architecture Resource Center: Free content, downloads, discussions,
and more. http://solutions.newsforge.com/ibmarch.tmpl
Felix Wiemann | 3 Oct 18:21 2005
Picon
Picon

Re: features for 0.4

David Goodger wrote:

> Felix Wiemann wrote:
>
>> BTW, please let's not incorporate the proposed versioning policy for
>> now.  I'm not yet sure if it's viable to have a maintenance (bug-fix
>> only) branch
>
> What's the problem?  Now is the time to discuss this.

I'm fine with the policy and I currently don't see any points to
discuss, but I'm not sure if it will work in practice.  I.e. I'd rather
not spend too much time writing (detailed) docs which need to be
rewritten later.  Otherwise I'm fine with putting it into the docs.

> Any change to the docs can be reverted later, if there is a problem.

True.

--

-- 
For private mail please ensure that the header contains 'Felix Wiemann'.

"the number of contributors [...] is strongly and inversely correlated with the
number of hoops each project makes a contributing user go through."      -- ESR

-------------------------------------------------------
This SF.Net email is sponsored by:
Power Architecture Resource Center: Free content, downloads, discussions,
and more. http://solutions.newsforge.com/ibmarch.tmpl
(Continue reading)

Felix Wiemann | 3 Oct 20:18 2005
Picon
Picon

Re: Proposed extension(s) to role directive

Mark Nodine wrote:

>    <role_definition names="red" base-role="inline">
>        [...]
>    <paragraph>
>        colored 
>        <inline classes="red" custom-role="red">
>            text

You can't expect the writer to resolve the role reference, so that's not
the final representation in the doctree.

I think we can go without role_definition, and for the doctree we can
use the raw element:

<paragraph>
    colored
    <raw format="html">
        <font color="red">
    <raw format="latex">
        {\color{red}
    <inline classes="red">
        text
    <raw format="html">
        </font>
    <raw format="latex">
        }

So we do have a representation after all.  The problem is the reST
syntax.  We could add a new role, like "raw-formatting" from which to
(Continue reading)

David Goodger | 4 Oct 00:26 2005

Re: Re: Proposed extension(s) to role directive

> David Goodger wrote:
>> No, the problem is getting you to show us a concrete example of what
>> you mean!

[Mark Nodine]
> I thought I had given an example in my first email under the
> shot-down-because-unscalable category.

No, you gave an HTML output example only.

[... example omitted ...]

We don't need any new doctree elements (role_definition) to do this.
Roles themselves are purely a reST construct, and all roles are
resolved at parse time.  I don't see any reason why this should be any
different.

I was working on an alternative approach, but Felix beat me to the
post.  His directive syntax is better anyhow (putting the invariants
-- the prefix & suffix options -- up front).

The parser will call the role handler for the raw-formatting role,
which will create a new role handler for the "red" role.  So when the
role is used (e.g. in "colored :red:`text`"), the "red" role handler
(a callable object) is simply called.

As for the name, perhaps "generated-raw", along the lines of CSS2
generated content?  "raw-wrap", "raw-wrapped", "wrapped-raw", or
"raw-wrapper"?

(Continue reading)

Mark Nodine | 4 Oct 17:37 2005

Re: Re: Proposed extension(s) to role directive

David Goodger wrote:
> This is the output Felix came up with:
> 
> [Felix Wiemann]
> > <paragraph>
> >     colored
> >     <raw format="html">
> >         <font color="red">
> >     <raw format="latex">
> >         {\color{red}
> >     <inline classes="red">
> >         text
> >     <raw format="html">
> >         </font>
> >     <raw format="latex">
> >         }
> 

+1.

> It matches what I came up with, except for the "<inline
> classes="red">text</>" in the middle.  Is this strictly necessary, and
> do we want it?  Perhaps we do, for other unspecified output formats.

+1.

> > We could alternatively or additionally add a role (let's call it
> > "surrounded") which does the same without raw content, like ::
> >
> >     .. role:: parenthesized(surrounded)
(Continue reading)

Mark Nodine | 4 Oct 17:43 2005

Whatever happened to parsed-literal?

In the snapshot of 2005/08/15, there were no longer any 
unit tests for the parsed-literal directive.  Is it
still supported?  Or is it just another name for line-block?
If the latter is true, how do you control start-of-line 
spacing (to get things to line up in a monospaced font)?

	--Mark

-------------------------------------------------------
This SF.Net email is sponsored by:
Power Architecture Resource Center: Free content, downloads, discussions,
and more. http://solutions.newsforge.com/ibmarch.tmpl
Felix Wiemann | 4 Oct 19:30 2005
Picon
Picon

Re: Whatever happened to parsed-literal?

Mark Nodine wrote:

> In the snapshot of 2005/08/15, there were no longer any unit tests for
> the parsed-literal directive.

There never were tests for the parsed-literal directive (except for a
test in test_writers/test_latex2e.py).  I just added a functional test
for "parsed-literal".  Thanks for pointing this out!

> Is it still supported?

Yes, it is, definitely.

> Or is it just another name for line-block?

No; the line block is not monospaced, for example, and as you mentioned,
line blocks don't support character-wise indentation.

--

-- 
For private mail please ensure that the header contains 'Felix Wiemann'.

"the number of contributors [...] is strongly and inversely correlated with the
number of hoops each project makes a contributing user go through."      -- ESR

-------------------------------------------------------
This SF.Net email is sponsored by:
Power Architecture Resource Center: Free content, downloads, discussions,
and more. http://solutions.newsforge.com/ibmarch.tmpl
Felix Wiemann | 4 Oct 19:37 2005
Picon
Picon

Re: Proposed extension(s) to role directive

David Goodger wrote:

> As for the name, perhaps "generated-raw", along the lines of CSS2
> generated content?  "raw-wrap", "raw-wrapped", "wrapped-raw", or
> "raw-wrapper"?

IMO "raw-wrapped" (or "raw-wrap") are the most descriptive names.

> Felix Wiemann wrote:
>
>> <paragraph>
>>     colored
>>     <raw format="html">
>>         <font color="red">
>>     <raw format="latex">
>>         {\color{red}
>>     <inline classes="red">
>>         text
>>     <raw format="html">
>>         </font>
>>     <raw format="latex">
>>         }
>
> It matches what I came up with, except for the "<inline
> classes="red">text</>" in the middle.  Is this strictly necessary,

Probably not.

> and do we want it?

(Continue reading)

Mark Nodine | 6 Oct 21:51 2005

Hyperlink transition table

Is the hyperlink transition table in nodes.py up to date?

Here it is

        ====  =====  ========  ========  =======  ====  =====  =====
         Old State    Input          Action        New State   Notes
        -----------  --------  -----------------  -----------  -----
        ids   types  new type  sys.msg.  dupname  ids   types
        ====  =====  ========  ========  =======  ====  =====  =====
        --    --     explicit  --        --       new   True
        --    --     implicit  --        --       new   False
        None  False  explicit  --        --       new   True
        old   False  explicit  implicit  old      new   True
        None  True   explicit  explicit  new      None  True
        old   True   explicit  explicit  new,old  None  True   [#]_
        None  False  implicit  implicit  new      None  False
        old   False  implicit  implicit  new,old  None  False
        None  True   implicit  implicit  new      None  True
        old   True   implicit  implicit  new      old   True
        ====  =====  ========  ========  =======  ====  =====  =====

Specifically, if the directives.txt file is processed strictly
according to this transition table, it should generate an error
about a duplicate target "contents" (assuming I'm interpreting
the table correctly).  First it has an implicit "contents"
target generated by the topic created by the contents directive
(since no alternative name was given in the argument of the
directive), which should move it to state "new False".  Later,
there is an explicit ".. _contents:" target, which should hit
row 4 ("old False") in the table, update to state "new True"
(Continue reading)


Gmane