long lines get cut off in pdf documentation
Alex Ghitza
Hash: SHA1
Hi,
This comes up in the pdf versions of the various documentation files:
the tutorial, the reference manual, the programming manual, the
constructions file.
When you have a long-ish line in a verbatim environment, and it exceeds
the width of the page, it gets cut off. For an example (there are
many), search for "capped relative precision" in tut.pdf or tut.tex.
To solve this, it might be easiest to use a latex package for source
code environments like Listings, see
http://www.ctan.org/tex-archive/macros/latex/contrib/listings/
It does line-breaking, and it has a whole lot of other fancy cool features.
One problem is that it is released under the Latex Project Public
License, which is more restrictive than (and hence incompatible with)
GPL, see
http://www.gnu.org/philosophy/license-list.html
but maybe the maintainer of Listings can be persuaded to relicense it?
Another possibility would be to make our own customized verbatim
environment...
Thoughts?
Alex
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.7 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org
iD8DBQFHoTXqdZTaNFFPILgRAh+XAJ4oceOOVxCpLEbn7BYmiXqvJaEXLQCdEMDT
5XubqKJprKTtp7+cIJw46vc=
=aaoK
-----END PGP SIGNATURE-----
Jason Grout
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> Hi,
>
> This comes up in the pdf versions of the various documentation files:
> the tutorial, the reference manual, the programming manual, the
> constructions file.
>
> When you have a long-ish line in a verbatim environment, and it exceeds
> the width of the page, it gets cut off. For an example (there are
> many), search for "capped relative precision" in tut.pdf or tut.tex.
>
> To solve this, it might be easiest to use a latex package for source
> code environments like Listings, see
> http://www.ctan.org/tex-archive/macros/latex/contrib/listings/
> It does line-breaking, and it has a whole lot of other fancy cool features.
>
> One problem is that it is released under the Latex Project Public
> License, which is more restrictive than (and hence incompatible with)
> GPL, see
> http://www.gnu.org/philosophy/license-list.html
> but maybe the maintainer of Listings can be persuaded to relicense it?
>
> Another possibility would be to make our own customized verbatim
> environment...
>
> Thoughts?
>
Do we need to include the listings package in Sage? I have the listings
package in my system tex distribution already (texlive on ubuntu, but I
think I have the optional tex packages installed).
Jason
Alex Ghitza
Hash: SHA1
Very good point. I also have it in my tex distribution on gentoo
by default.
Alex
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.7 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org
iD8DBQFHoTm6dZTaNFFPILgRArEpAJ9Bkg7M44Zpj6DTeKxtWFNXhH5T+wCeLPDE
FfLaOgnoaXj0wnv4CDK9fCY=
=FATK
-----END PGP SIGNATURE-----
root
>the tutorial, the reference manual, the programming manual, the
>constructions file.
>
>When you have a long-ish line in a verbatim environment, and it exceeds
>the width of the page, it gets cut off. For an example (there are
>many), search for "capped relative precision" in tut.pdf or tut.tex.
>
>To solve this, it might be easiest to use a latex package for source
>code environments like Listings, see
>http://www.ctan.org/tex-archive/macros/latex/contrib/listings/
>It does line-breaking, and it has a whole lot of other fancy cool features.
>
>One problem is that it is released under the Latex Project Public
>License, which is more restrictive than (and hence incompatible with)
>GPL, see
>http://www.gnu.org/philosophy/license-list.html
>but maybe the maintainer of Listings can be persuaded to relicense it?
>
>Another possibility would be to make our own customized verbatim
>environment...
For Axiom I use noweb which handles inline code well.
And it has the feature that you can extract and execute the code
as well as latex the document.
Tim
William Stein
>
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> Hi,
>
> This comes up in the pdf versions of the various documentation files:
> the tutorial, the reference manual, the programming manual, the
> constructions file.
>
> When you have a long-ish line in a verbatim environment, and it exceeds
> the width of the page, it gets cut off. For an example (there are
> many), search for "capped relative precision" in tut.pdf or tut.tex.
>
> To solve this, it might be easiest to use a latex package for source
> code environments like Listings, see
> http://www.ctan.org/tex-archive/macros/latex/contrib/listings/
> It does line-breaking, and it has a whole lot of other fancy cool features.
>
> One problem is that it is released under the Latex Project Public
> License, which is more restrictive than (and hence incompatible with)
> GPL, see
> http://www.gnu.org/philosophy/license-list.html
> but maybe the maintainer of Listings can be persuaded to relicense it?
>
> Another possibility would be to make our own customized verbatim
> environment...
>
> Thoughts?
Are options are:
(1) Fix the original tex so that it is word wrapped. This would
involve modifying
the file
devel/doc/ref/update_script.py
so that long lines are automatically word wrapped when the reference manual
is assembled out of the source code. We would have to do this by hand for
tut.tex, const.tex, etc.
(2) Use some sort of listings latex package, as suggested above.
The license issue in (2) is moot as Jason Grout points out. Whether (2) will
work or not is very unclear to me. Sage uses the Python documentation
framework,
which involves using heavily customized latex2html and perl scripts. It's
possible (2) just won't work with them. I don't know. Another potential issue
with 2 is that the automatic word wrapping might be stupid in such a
way that one
can't just ALWAYS 100% of the time cut and paste whatever is in the word wrapped
listing environments and get something that works. If this is the
case, then (2) is
not an option. With (1) we can make sure it is the case, since we
have total control.
-- William