#152 s5defs.txt included from slide-shows.txt may affect other files in Docutils documentation

[Dmitry Shachnev]

While working on reproducible builds effort in Debian, we noticed that sometimes built .html files in Docutils’ own documentation contain <span class="incremental"> on one build and <cite> in the same place on another build.
See for example this diff.

The reason is that slide-shows.txt includes s5defs.txt which has this line:

.. default-role:: incremental

As the tools/buildhtml.py script does not reset the default role between processing files, all files that are built after slide-shows.txt will get incremental as the default role.

A patch to fix (by explicitly resetting the default role) this is attached. Another possible fix would be modifying tools/buildhtml.py to reset the state between processing files.

[Günter Milde]

Looking at reStructuredText Directives__ I see:

The "default-role" directive sets the default interpreted text role, [...] For example, after setting the default role like this:

    .. default-role:: subscript

any subsequent use of implicit-role interpreted text in the document will use the "subscript" role

This indicates the scope of the role-change should be limited to the document.

My understanding of buildhtml.py is, that it generates separate documents out of the *.txt files in a directory. This means the correct fix would be to re-set the default role in buildhtml.py.

__ http://docutils.sourceforge.net/docs/ref/rst/directives.html#setting-the-default-interpreted-text-role

[Dmitry Shachnev]

Will you fix it, or you want a patch?

There is also this comment in the DefaultRole code:

 # @@@ should this be local to the document, not the parser?

However I don’t know how to fix it more generally (for projects that don’t use buildhtml.py).

[Günter Milde]

Does the following patch help?

Dir: /usr/local/src/docutils-svn/docutils/docutils/parsers/rst/

Index: __init__.py
===================================================================
--- __init__.py (Revision 8241)
+++ __init__.py (Arbeitskopie)
@@ -189,6 +189,9 @@
               inputstring, tab_width=document.settings.tab_width,
               convert_whitespace=True)
         self.statemachine.run(inputlines, document, inliner=self.inliner)
+        # restore the "default" default role after parsing a document
+        if '' in roles._roles:
+                del roles._roles['']
         self.finish_parse()

[Dmitry Shachnev]

Yes, that helps. Thanks!

[Günter Milde]

Applied in rev. 8257. Thank you for reporting.

[Dmitry Shachnev]

Thanks! Small nitpick that I noticed only now: the del roles._roles[''] line has too much indentation, +8 spaces instead of +4.