[Docutils-users] docutils.nodes.Node's source and line attributes

[Brecht Machiels]

Hello,

I'm using reStructuredText as an input format for RinohType [1]. Since I want to provide useful warning/error messages, I rely on the source, tagname and line attributes of the Node instances to point the user to the relevant location in the source file.

I have noticed that not all Node instances have non-None source and/or line attributes. For example, the following nodes (among others) in the quickstart.txt [2] have missing data:
* literal_block at line 119: document is None
* enumerated_list at line 143: both document and line are None
* bullet_list at line 179: both document and line are None
* literal_block at line 193: document is None
* literal_block at line 236: document is None

Some other literal_block nodes do have document set though.

Is this normal behavior? I don't remember if I found out about source/line by reading the documentation or by reading nodes.py. I can't seem to find a description the docs at this moment.

For now, if document is None, I (recursively) try to get the document from the parent node. Same for line.

[1] http://www.mos6581.org/introducing-rinohtype
[2] http://docutils.sourceforge.net/docs/user/rst/quickstart.txt

Best regards,
Brecht

[David Goodger]

Post by Brecht Machiels
Hello,
I'm using reStructuredText as an input format for RinohType [1]. Since I want to provide useful warning/error messages, I rely on the source, tagname and line attributes of the Node instances to point the user to the relevant location in the source file.
* literal_block at line 119: document is None
* enumerated_list at line 143: both document and line are None
* bullet_list at line 179: both document and line are None
* literal_block at line 193: document is None
* literal_block at line 236: document is None
Some other literal_block nodes do have document set though.
Is this normal behavior?

Those attributes were originally meant for development and debugging
purposes. They are not guaranteed to be present on all elements,
although it would be nice if they were. You may consider it a bug.
Feel free to submit a bug report. Patches are welcome.

Post by Brecht Machiels
I don't remember if I found out about source/line by reading the documentation or by reading nodes.py. I can't seem to find a description the docs at this moment.

"source" is documented in
http://docutils.sourceforge.net/docs/ref/doctree.html#attribute-reference
"line" is not documented at all.

Post by Brecht Machiels
For now, if document is None, I (recursively) try to get the document from the parent node. Same for line.
[1] http://www.mos6581.org/introducing-rinohtype
[2] http://docutils.sourceforge.net/docs/user/rst/quickstart.txt
Best regards,
Brecht

[Brecht Machiels]

Post by David Goodger

Post by Brecht Machiels
Hello,
I'm using reStructuredText as an input format for RinohType [1]. Since I want to provide useful warning/error messages, I rely on the source, tagname and line attributes of the Node instances to point the user to the relevant location in the source file.
* literal_block at line 119: document is None
* enumerated_list at line 143: both document and line are None
* bullet_list at line 179: both document and line are None
* literal_block at line 193: document is None
* literal_block at line 236: document is None
Some other literal_block nodes do have document set though.
Is this normal behavior?

Those attributes were originally meant for development and debugging
purposes. They are not guaranteed to be present on all elements,
although it would be nice if they were. You may consider it a bug.
Feel free to submit a bug report. Patches are welcome.

I have created a new ticket to track this bug: https://sourceforge.net/p/docutils/bugs/245/
As this is a fairly important feature for RinohType, I will probably get around to fixing this sometime soon.

I've had a quick look at the docutils code. It seems that the source and line attributes are set in the different methods corresponding to the different rST elements (states.py). I think it would be better to set these attributes at a higher lever, independent of the rST element type. However, I'm not sure where this should be implemented.

Best regards,
Brecht