Re: [lxml-dev] Generating PDF documentation
Hi, Marcin Kasperski wrote:
If there are no objection, I'll just add the generated PDF to the source release, that's not even 1MB more.
I'd suggest distributing PDF separately (and linking it from the website so it is easily available). PDFs aren't compressing too well.
The PDF gzips from 900KB down to 600KB, so that's not too much in addition. On the other hand, many people just use easy_install or a buildout to grab the tar.gz, so they won't benefit from the docs at all. We currently have a source distribution of a bit less than 2MB. Most of that is generated HTML documentation (gzipped 1.1MB, mainly the API docs). If we removed everything that easy_install doesn't use, maybe even the test suites, I guess we would be down to some 600KB, including the generated C source. We could still provide a complete tar.gz for download, maybe next to the plain source on PyPI, or just from the lxml homepage. It's harder to do, though, as I don't think distutils supports this without a little setup.py tweaking. Any opinions on this?
And - especially - some people who do not use source release may find use for PDF ;-)
Sure, I didn't say it wouldn't show up on the web page. Stefan
Stefan Behnel wrote:
Marcin Kasperski wrote:
especially - some people who do not use source release may find use for PDF ;-)
Sure, I didn't say it wouldn't show up on the web page.
I uploaded the PDF docs for lxml 2.1beta1 here: http://codespeak.net/lxml/dev/lxmldoc-2.1beta1.pdf It's now built automatically with my normal web site upload. Any patches to improve doc/mklatex.py are welcome. Stefan
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Stefan Behnel wrote:
Hi,
Marcin Kasperski wrote:
If there are no objection, I'll just add the generated PDF to the source release, that's not even 1MB more. I'd suggest distributing PDF separately (and linking it from the website so it is easily available). PDFs aren't compressing too well.
The PDF gzips from 900KB down to 600KB, so that's not too much in addition.
On the other hand, many people just use easy_install or a buildout to grab the tar.gz, so they won't benefit from the docs at all.
We currently have a source distribution of a bit less than 2MB. Most of that is generated HTML documentation (gzipped 1.1MB, mainly the API docs). If we removed everything that easy_install doesn't use, maybe even the test suites, I guess we would be down to some 600KB, including the generated C source. We could still provide a complete tar.gz for download, maybe next to the plain source on PyPI, or just from the lxml homepage. It's harder to do, though, as I don't think distutils supports this without a little setup.py tweaking.
Any opinions on this?
+1 for leaving the docs, etc. in the source dist (*especially* the test suite code). Tres. - -- =================================================================== Tres Seaver +1 540-429-0999 tseaver@palladion.com Palladion Software "Excellence by Design" http://palladion.com -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.6 (GNU/Linux) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org iD8DBQFICjEb+gerLs4ltQ4RAtOLAJ0TGL+7oYOYP3ITdlOXq/fTVXuecQCgodBq OQfh8NAQYVE44uVUqMN9vh4= =ZZoD -----END PGP SIGNATURE-----
Tres Seaver wrote:
+1 for leaving the docs, etc. in the source dist (*especially* the test suite code).
:) I didn't mean to close down the source or something, just considering a way to adapt to the fact that many downloads of lxml happen automatically through easy_install, so most people won't even see that there is more in there than the installable code. The idea was to make a stripped down distribution the *default* download from PyPI, not the *only* download. But I think this would lead to more confusion than it helps anyone. Stefan
Stefan Behnel wrote:
Stefan Behnel wrote:
Marcin Kasperski wrote:
especially - some people who do not use source release may find use for PDF ;-) Sure, I didn't say it wouldn't show up on the web page.
I uploaded the PDF docs for lxml 2.1beta1 here:
http://codespeak.net/lxml/dev/lxmldoc-2.1beta1.pdf
It's now built automatically with my normal web site upload.
Any patches to improve doc/mklatex.py are welcome.
This looks cool. Quite interesting to see we have almost 200 pages of documentation now (not counting the changelogs). That's impressive! My suggestion for the stylesheet would be to use whitespace between paragraphs, instead of what it does now, indenting the paragraphs. I find that easier to read. There also seems to be a jumping of the left margin on alternate pages. Perhaps this is nice if you print it? I don't see this in many PDFs I see though, and it makes it a bit harder to read on the screen. Regards, Martijn
Hi Martijn, Martijn Faassen wrote:
My suggestion for the stylesheet would be to use whitespace between paragraphs, instead of what it does now, indenting the paragraphs.
Done.
There also seems to be a jumping of the left margin on alternate pages. Perhaps this is nice if you print it?
The LaTeX document class was set to "book", which automatically alternates left and right pages. The "report" class is better here. Stefan
Hi, Martijn Faassen wrote:
This looks cool. Quite interesting to see we have almost 200 pages of documentation now (not counting the changelogs). That's impressive!
I also got epydoc into generating the API documentation in LaTeX now. Actually, the biggest problem was how to include it in the existing document without breaking the document structure. That means we're at 435 pages now. :) Stefan
That means we're at 435 pages now. :)
I'd strongly consider publishing two separate PDFs. 435 is a bit too much to print and API refs are less useful in print than tutorials and design docs. -- ---------------------------------------------------------------------- | Marcin Kasperski | If Staff, Scope and Schedule are all fixed, | http://mekk.waw.pl | managers will have no options, other than | | prayer. (Martin) ----------------------------------------------------------------------
Marcin Kasperski schrieb:
The LaTeX document class was set to "book", which automatically alternates left and right pages. The "report" class is better here.
There are no \part's in report.
Yes, there are. Look for "part" in this file, for example: http://ftp.funet.fi/pub/TeX/TeX-3.14/latex/report.sty The differences between document classes are really small, and "report" is almost like "book", except for the things that make a difference here. Stefan
Marcin Kasperski schrieb:
That means we're at 435 pages now. :)
I'd strongly consider publishing two separate PDFs. 435 is a bit too much to print and API refs are less useful in print than tutorials and design docs.
True. What about just moving the generated stuff to the end of the PDF? That way, you can print the file up to page X (somewhere around 200) if you want to print it, but you'd still have everything in one file to carry around and do a text search. Stefan
Yes, there are. Look for "part" in this file, for example:
Sorry if so.
The differences between document classes are really small, and "report" is almost like "book", except for the things that make a difference here.
IIRC there are also things like forcing part start on the odd page etc. Whatever - surely one can start from any of those classes and tune it. The main problem is what is the expected result ;-) Some things to consider: (purely look&feel) - more aestethic title page (ideas welcome, things like underlined title in big letters on the lower part of the page come to min) - more aestethic chapter and part titles - some font tuning (there are a few fonts which look better than computer modern) - more aestethic footers (content) - information ordering and chapter/titles review (see the table of contents, there is chapter lxml containing section lxml, What's new in lxml 2.0 is in first part while detailed change history on the end, some discussion about ElementTree compatibility i between performance and FAQ and before the first tutorial etc etc) - (?) index (of crucial terms) -- ---------------------------------------------------------------------- | Marcin Kasperski | You have the right to peace, fun, and | http://mekk.waw.pl | productive and enjoyable work. (Beck) | | ----------------------------------------------------------------------
"Stefan Behnel" <stefan_ml@behnel.de> writes:
Marcin Kasperski schrieb:
That means we're at 435 pages now. :)
I'd strongly consider publishing two separate PDFs. 435 is a bit too much to print and API refs are less useful in print than tutorials and design docs.
True. What about just moving the generated stuff to the end of the PDF? That way, you can print the file up to page X (somewhere around 200) if you want to print it, but you'd still have everything in one file to carry around and do a text search.
Table of contents will still be polluted, plus ... partial printing is amazingly error-prone (the fact that printed page numbers mismatch with PDF-browser page numbers is one of the factors). IMO it would be nice to have two PDF - lxml Developer Guide (or so) and lxml Reference. As a sidenote: I am not sure whether 'Changes' chapter is at all needed in PDF, this is 30 pages of information nobody is likely to read. -- ---------------------------------------------------------------------- | Marcin Kasperski | Communication takes place between people, | http://mekk.waw.pl | documents are secondary. (Booch) | | ----------------------------------------------------------------------
Marcin Kasperski wrote:
partial printing is amazingly error-prone (the fact that printed page numbers mismatch with PDF-browser page numbers is one of the factors).
That can be fixed.
IMO it would be nice to have two PDF - lxml Developer Guide (or so) and lxml Reference.
I don't see that need. Be it a 200 page document or one with 400 pages, people will only read the parts they are interested in. And if the page numbers match the print range, I'm just fine with providing a single download instead of risking that people might want to look things up on the train and only notice then that they forgot to download the second PDF.
As a sidenote: I am not sure whether 'Changes' chapter is at all needed in PDF, this is 30 pages of information nobody is likely to read.
People who must consider backwards compatibility might care. Stefan
Marcin Kasperski wrote:
- more aestethic title page (ideas welcome, things like underlined title in big letters on the lower part of the page come to min)
I added a logo for now, but there's more that can be done, sure.
- information ordering and chapter/titles review (see the table of contents, there is chapter lxml containing section lxml, What's new in lxml 2.0 is in first part while detailed change history on the end, some discussion about ElementTree compatibility i between performance and FAQ and before the first tutorial etc etc)
That might be something worth changing on the web page menu, too. See doc/docstructure.py
- (?) index (of crucial terms)
That's a hard one. The information is not there in the ReST files. Stefan
participants (4)
-
Marcin Kasperski -
Martijn Faassen -
Stefan Behnel -
Tres Seaver