FAQ.txt

1.	OK, I have downloaded this stuff.  What do I do now?

	A.	Type "make" from the top-level directory.  If all goes
		well, this will produce a file named "perfbook-2up.pdf",
		which prints two virtual pages per physical page.

2.	The Makefile cannot find pdflatex.  What is it and where can I
	find it?

	A.	The "pdflatex" package is a variant of Don Knuth's
		digital typesetting program.  On Ubuntu Maverick,
		installing the following set of packages suffices:

			texlive-latex-base texlive-latex-extra psutils
			texlive-publishers-doc texlive-fonts-extra
			texlive-math-extra texlive-publishers
			texlive-science texlive-bibtex-extra latex2html
			gnuplot-x11 xfig inkscape

		Other systems might provide similarly named packages.
		For example, Doug Miller noted that the following list
		of teTeX components worked for him on RHEL5:

			tetex tetex-afm tetex-dvips tetex-latex latex2html
			texinfo tetex-fonts tetex-doc tetex-xdvi

		For another example, Frederic Weisbecker reports that
		the following packages allows perfbook to be built on
		Fedora 19:

			texlive-latex texlive-collection-latexextra
			psutils texlive-math* texlive-bibtex latex2html
			xfig latex2html xfig (and maybe also gnuplot-latex
			texlive-publishers-doc texlive-fonts-extra
			texlive-science).

3.	I cannot build perfbook, and the perfbook.log file complains
	about some obscure package being missing.  What do I do?

	A.	Please see #2 above.

4.	When I try to build perfbook, it hangs after printing a line
	reading "pdflatex 1".  How can I fix this?

	A.	On UNIX-like systems, including Linux, type control-D.
		The look at the end of the perfbook.log file (or the
		perfbook-1c.log file if you were building single-column).
		The error message at the end of the log file should
		indicate the source of the problem.

		The build scripts are supposed to make this unnecessary,
		so if it happens, please let me know.  Please send me the
		perfbook.log output (or perfbook-1c.log output, depending
		on which you were building) so that I can fix the scripts.

5.	Why the heck did you use this strange-looking text-based
	ca. 1980s typesetting package instead of something more
	modern, like OpenOffice?

	A.	Although latex takes a bit of getting used to, its
		automatic handling of bibliographies, tables of contents,
		figures, and tables is extremely useful for large documents.
		In addition, its text-based nature is much more compatible
		with modern source-code-control systems such as "git".

		Finally, the more-modern WYSIWYG text formatters tend
		to get a bit cranky when working with hundreds-of-pages
		documents.

6.	Where can I purchase a hardcopy of this book?

	A.	You can use any of a number of web-based printing
		services, for but one example, lulu.com.  Images suitable
		for cover art may be found in CoverFront.jpg and
		CoverBack.jpg in the cartoons directory.

		In addition, edition-level releases will be made more
		readily available in printed form.

7.	This book doesn't mention my favorite parallel-programming
	tools, languages, and algorithms.  Plus its Makefile and
	Latex formatting are imperfect.  What is up with that?

	A.	Please see the following question.

8.	Can I contribute?

	A.	Of course!!!  The contribution process is similar to that
		of the Linux kernel and of the Samba project.  See the
		Documentation/SubmittingPatches file in a Linux source tree.

		Please put a "Signed-off-by:" line in your patches,
		for an example see: http://lkml.org/lkml/2007/1/15/219.

		This "Signed-off-by:" line has a very specific meaning as
		follows:

		---------------------------------------------------------

		By making a contribution to this project, I certify that:

		1.	The contribution was created in whole or in part
			by me and I have the right to submit it under
			the open source license indicated in the file; or

		2.	The contribution is based upon previous work
			that, to the best of my knowledge, is covered
			under an appropriate open source License and I
			have the right under that license to submit that
			work with modifications, whether created in whole
			or in part by me, under the same open source
			license (unless I am permitted to submit under
			a different license), as indicated in the file; or

		3.	The contribution was provided directly to me by
			some other person who certified (a), (b) or (c)
			and I have not modified it.

		4.	The contribution is made free of any other party's
			intellectual property claims or rights.

		5.	I understand and agree that this project and the
			contribution are public and that a record of the
			contribution (including all personal information
			I submit with it, including my sign-off) is
			maintained indefinitely and may be redistributed
			consistent with this project or the open source
			license(s) involved.

		---------------------------------------------------------

		This is similar to the DCO used for the Linux kernel,
		with the addition of #4.  This says that you wrote
		the contribution yourself, as opposed to having (say)
		copied it from somewhere.  If multiple people authored
		a contribution, each should have a "Signed-off-by:" line.

9.	May I have permission to translate this book to my native
	language?

	A.	Of course!  In any case, this permission is implicitly
		granted by the choice of the Creative Commons
		Attribution-Share Alike 3.0 United States license for
		the text and GPL for the code.

		Please keep in mind that all translations must preserve
		the licenses.

		A project translating the book to Chinese is well underway,
		and there are rumors of other translation efforts as well.

		People who have worked on the Chinese translations
		include: 谢宝友(xie.baoyou172958@zte.com.cn,scxby@163.com),
		鲁阳(luyang.co@gmail.com), 陈渝(wilbur512@gmail.com),
		Cheedoong Drung (cn-boy@china.com.cn), and 王贺涛
		<wanghetaop@163.com>.  Please contact them to contribute
		to their good work.

		See http://code.taobao.org/p/perfbook/src/ for more
		information on Cheedoong Drung's and 王贺涛's effort.
		For a PDF of the translation by 谢宝友, 鲁阳, and 陈渝,
		please see:

		http://kernel.org/pub/linux/kernel/people/paulmck/perfbook/perfbook-cn.2011.10.18a.pdf

10.	I am working on a translation.  What do I need to do to get my
	name of the list in #8 above?

	A.	Send me at least one chapter of your translated work
		in machine-readable form, preferable PDF.

11.	May I please have permission to sell hardcopies of my translated
	version of this book?

	A.	Yes, in fact, you already have permission, thanks to the
		Creative Commons and GPL licenses in use.  I do request
		that you send me one copy of the translated work
		(hardcopy if available), but that is a request made
		from professional courtesy, and is not in any way a
		requirement for the permission that you already have
		under the Creative Commons and GPL licenses.

12.	I hate Quick Quizzes!!!  Could you please get rid of them?

	A.	Quite a few people like them a lot, so they will be
		staying.  However, you can easily produce a copy of the
		book that omits the Quick Quizzes by editing the Makefile
		and qqz.sty files in the top-level directory.

		One approach is to make the "\QuickQuiz" command in
		qqz.sty be a no-op and to add line to the Makefile that
		transforms "perfbook_flat.tex" by removing the Quick
		Quizzes, each of which starts with the line "\QuickQuiz{}"
		and ends with the line "} \QuickQuizEnd".

		This transformation should happen after the invocation
		of "utilities/extractqqz.sh" in the "perfbook_flat.tex"
		Makefile rule.	This would remove the inlined Quick
		Quizzes from the running text, but retain the chapter
		containing the answers.  It should be possible to move
		each chapter's Quick Quizzes to the end of that chapter,
		but that would require more work and is left as an
		exercise to the reader.

		It is possible to move the quizzes to the ends of the
		chapters, with the answers still at the end of the book,
		or any of a number of other transformations.  "Just a
		small matter of scripting."

		More seriously, one of the advantages of making a book
		available under Creative Commons and GPL is that it
		enables similar transformations and remixes.  That said,
		one of the advantages of the current form of the Quick
		Quizzes is that this promotes faster and better learning.