Opened 12 years ago

Closed 11 years ago

#1366 defect closed duplicate (duplicate)

TwistedQuotes documentation references external source files

Reported by: Jean-Paul Calderone Owned by: Moshe Zadka
Priority: high Milestone:
Component: core Keywords: documentation
Cc: Glyph, Jean-Paul Calderone, Moshe Zadka, phenyx Branch:
Author:

Description


Change History (4)

comment:1 Changed 12 years ago by Jean-Paul Calderone

When generating the book, these source files are not included.  This leads to
link warnings (and broken links) in book.tex.

The precedent for this use-case seems to be to include a copy of the referenced
source inline in the html, which seems bad to me.

Warnings from tex are visible on the doc builder, eg:

http://twistedmatrix.com/buildbot/full-2.3/builds/1059/step-process-docs/1

And typically look like:

WARNING: LaTeX Warning: Reference
`doc/core/howto/listings/TwistedQuotes/__init__.py' on
 page 30 undefined on input line 15.
WARNING: LaTeX Warning: Reference
`doc/core/howto/listings/TwistedQuotes/quoters.py' on 
page 30 undefined on input line 16.
WARNING: LaTeX Warning: Reference
`doc/core/howto/listings/TwistedQuotes/quoteproto.py' 
on page 30 undefined on input line 17.
WARNING: LaTeX Warning: Reference
`doc/core/howto/listings/TwistedQuotes/plugins.tml' on
 page 30 undefined on input line 18.
WARNING: LaTeX Warning: There were undefined references.

comment:2 Changed 12 years ago by phenyx

Possible solution is to latex-prettyprint any non-html examples using the
listings package, or something like it - as long as everything is more or less
pythonic, it should be okay.

The example files could then be put in sections in an appendix to the main
document and cross-references would work properly.

comment:3 Changed 12 years ago by Glyph

Moshe, you are the most expertest latex person here, I think - can you take this
over?  I suspect that phenyx is correct about the appendix but I haven't written
anything serious with latex since USENIX.

comment:4 Changed 11 years ago by Jean-Paul Calderone

Resolution: duplicate
Status: newclosed

#2530 is a duplicate of this, with a patch attached, so I'm letting that supercede this.

Note: See TracTickets for help on using tickets.