Lore should give a reasonable error when encourtering headings that contain links

[rwall]

Currently they work when generating html, but fail when generating html with the following unenlightening traceback:

See:

•  https://buildbot.twistedmatrix.com/builders/documentation/builds/2919/steps/process-docs/logs/stdio

  Traceback (most recent call last):
    File "<string>", line 22, in <module>
    File "twisted/python/_release.py", line 596, in build
      self.buildTeX(inputDir)
    File "twisted/python/_release.py", line 521, in buildTeX
      [child.path for child in howtoDir.globChildren("*.xhtml")])
    File "twisted/python/_release.py", line 309, in lore
      lore.runGivenOptions(options)
    File "twisted/lore/scripts/lore.py", line 129, in runGivenOptions
      walker.generate()
    File "twisted/lore/process.py", line 53, in generate
      self.df(fullpath, linkrel)
    File "twisted/lore/default.py", line 46, in <lambda>
      df = lambda file, linkrel: latex.convertFile(file, spitter)
    File "twisted/lore/latex.py", line 461, in convertFile
      processFile(spitter, fin)
    File "twisted/lore/latex.py", line 454, in processFile
      spitter.visitNode(dom)
    File "twisted/lore/latex.py", line 75, in visitNode
      getattr(self, 'visitNode_'+node.tagName, self.visitNodeDefault)(node)
    File "twisted/lore/latex.py", line 80, in visitNodeDefault
      self.visitNode(child)
    File "twisted/lore/latex.py", line 75, in visitNode
      getattr(self, 'visitNode_'+node.tagName, self.visitNodeDefault)(node)
    File "twisted/lore/latex.py", line 80, in visitNodeDefault
      self.visitNode(child)
    File "twisted/lore/latex.py", line 75, in visitNode
      getattr(self, 'visitNode_'+node.tagName, self.visitNodeDefault)(node)
    File "twisted/lore/latex.py", line 80, in visitNodeDefault
      self.visitNode(child)
    File "twisted/lore/latex.py", line 75, in visitNode
      getattr(self, 'visitNode_'+node.tagName, self.visitNodeDefault)(node)
    File "twisted/lore/latex.py", line 80, in visitNodeDefault
      self.visitNode(child)
    File "twisted/lore/latex.py", line 75, in visitNode
      getattr(self, 'visitNode_'+node.tagName, self.visitNodeDefault)(node)
    File "twisted/lore/latex.py", line 204, in visitNodeHeader
      spitter.visitNodeDefault(node)
    File "twisted/lore/latex.py", line 80, in visitNodeDefault
      self.visitNode(child)
    File "twisted/lore/latex.py", line 75, in visitNode
      getattr(self, 'visitNode_'+node.tagName, self.visitNodeDefault)(node)
    File "twisted/lore/latex.py", line 88, in visitNode_a
      return self.visitNode_a_href(node)
  AttributeError: HeadingLatexSpitter instance has no attribute 'visitNode_a_href'
  program finished with exit code 1
  

[exarkun]

I'm not sure what bug you're reporting here. Links are not allowed in Lore document headings. Please describe the issue more completely if you think one exists.

[tom.prince]

I'm fine with marking this as wontfix, but in that case, should we deprecate lore, if we aren't going to maintain it (or at least indicate that fact somehow?

Links are supported in headings, when generating html, just not latex. If they aren't supported in latex, then rather than failing with a traceback with an AttributeError, a error message understandable to an end-user should be emitted.

[tom.prince]

I guess #4211 is related.

[glyph]

Replying to tom.prince:

I'm fine with marking this as wontfix, but in that case, should we deprecate lore, if we aren't going to maintain it (or at least indicate that fact somehow?

exarkun didn't say anything about deprecating lore. He asked you to more clearly describe the issue. As long as lore is in the repository, I think people should feel free to file bugs and submit patches for them.

Links are supported in headings, when generating html, just not latex. If they aren't supported in latex, then rather than failing with a traceback with an AttributeError, a error message understandable to an end-user should be emitted.

Links work in headings when generating HTML. That does not mean they are supported, i.e. intended to work. It would be better to have them fail in HTML too.

So you're proposing changing the description of this ticket to improve error reporting so that something comprehensible pointing at the problematic part of the document is emitted rather than at some Python code? Sounds reasonable to me.

[tom.prince]

This

<exarkun> rwall: If you're going to propose taking up Lore maintenance and starting new feature development on it, then I think you need to be explicit about that. Lore's situation is currently that is is unmaintained and most people would rather see it abandoned completely, not expanded.

suggested otherwise.

[exarkun]

Please raise this in one of the development discussion forums. If there's some agreement that Lore is the path forward, then we can start having tickets for changing it.

[exarkun]

To clarify slightly (particularly with respect to glyph's earlier comments on this ticket, which I missed reading before my last comment), I am rejecting this Lore feature as unnecessary for Twisted's current documentation needs. However if there is genuine interest in enhancing Lore (specifically: obsoleting the lore2sphinx conversion tool), then I'm open to reconsidering that.

Basically, this ticket is a demonstration of "stumble around in the dark" development in action. We don't need more of that (and I know I'm as guilty as anyone else). If someone wants to turn on a light, great. Otherwise, everyone out of the basement and find something more valuable on which to spend your time.