Re: [Docutils-develop] Column number for directive content / nodes in general

[Guenter M. <mi...@us...>]

Dear Mickey, dear docutils developers,

On 2021-11-16, Guenter Milde via Docutils-develop wrote:
> On 2021-10-24, Mickey Endito via Docutils-develop wrote:

...

>> Some thoughts:

>> system_messages is annoying.  It has 'line' and 'source' "doctree-attributes"
>> (e.g. `node['line']`) *and* also a `line` python-instance-attribute
>> (e.g. `node.line`).  

> The "line" attribute in <system_message> doctree elements stores document
> content (source/line info regarding the reported problem's origin should
> be part of, e.g., the XML rendering of the document tree).

> In other doctree elements, the "line" is auxiliary meta-data, used to
> generate a system_message if problems arise.

I had a closer look to the two "flavours" of element attributes:
in https://docutils.sourceforge.io/docs/user/config.html#expose-internals
they are called internal/external attributes:

"External" attributes correspond to the XML element attributes.
"Internal" attributes are Python class instance attributes.

>From nodes.Node, all Element instances inherit the "internal" elements
`parent`, `source`, `line`, and `document` (implemented as property).

All Docutils doctree elements support the external attribute "source"
(but only <document>, <system_message> and some instances of <literal_block>
actually use the "source" attribute).
<system_message> additionally declares the external attribute "line".

>> The bad news is they do not correlate at all.

This is a bug. When both, internal and external attribute are present and
not None, they should always have the same value.

In my tests, the "line" number difference was just 1 and both, internal
and external "lines" were "source-relative" line numbers. This looks like a
0-based vs. 1-based enumeration issue.

Can you provide a minimal example for "no correlation at all"?


I wonder, if adding optional "source" and "line" arguments to
nodes.Element.__init__() may simplify the code required for bookkeeping.
If not None, these would be values for self.source and self.line.

The conversion from "absolute" line number to source-relative line number
could be triggered by another optional argument "absline", say.

nodes.system_message.__init__() could then additionally set self['source']
and self['line'].

Günter