User Tools

Site Tools


chaosbook:howto:proofreading

This is an old revision of the document!


chaosbook

How to edit and complete chapter chapname.tex

Edits fall into three general classes:

  • trivial ones about wordings and grammar: implement without comments (svn keeps track of them)
  • less trivial ones about suggested revisions of the order of discussions and so on: if you rewrote a block of text, mark the edits something like this (so the other people can easily see what you did by scanning through the file):
  %%NW:                         in the line preceeding  a small edit, and
  %%NW:start edit
  ... block of text ...
  %%NW:finish edit
  • places where you think the exposition is unclear: use comment enviroment, such as
  \NW{This makes no sense to me, or am I in love?} (if you are Niall).

Editing protocol

  • the source LaTeX is in chapter/chapname.tex
  • update the date in \Chapter{chapname}{22apr2007}{Blah blah}
  • brief motivational preface
  • edits:
    • while a major rewite is in progress, keep (do not delete) the previous text in the public version of the book
          \PublicPrivate{
          Old Text stays here...
                               }{ % switch \PublicPrivate
          until New Text is finalized
                               }% end \PublicPrivate
  • when you remove equation, figure, table, section, remark, example, \index{} etc., check the ENTIRE manuscript for references to the edited item, update them
  • follow ChaosBook conventions whenever possible, rather then introducing new symbols. Define a frequently used symbols by a def.tex macro. That helps harmonize notation across ChaosBook.
  • add \index{} entry in the text for any important concept
  • \example{}{}: illustrative examples, preferably “physical” applications, can refer to literature
  • add relevant tables
  • Fig/fig*.eps - the biggest problem: we need quality figures, lots of them
  • FigSrc/*/ save the figure source program in the appropriate subdirectory
  • \Resume: Summary of the key results
  • \Remarks: scholarly remarks, all pointers to the literature (no references in the text proper, this is a self contained textbook)
  • refsChapname.tex: references, Physical Review style. Bracket the unused ones by the \PublicPrivate{ }{place ref here}, do not delete them.
  • chapter/appendChapname.tex: appendices, if appropriate
  • Problems/exerChapname.tex: exercises
  • Problems/soluChapname.tex: solutions
  • add soluChapname to Problems/solutions.tex
  • run through a spell checker (American rather than Queen's or Central European spelling)
  • finish all parts of the chapter (mother does not work here)

Notational coherence and proper cross-referencing with the rest of the textbook should be ensured as far as possible.

Style and notation

ChaosBook follows the Physical Review Style and Notation Guide; pdf version.

  • Style: if in doubt, apply the Gibson filter.
  • logarithms:
    • \ln if base e
    • \log_{10} if base 10
    • \log if base does not matter

References

  • each chapter has its references, so cited by [chapter.citation], for example: “as noted by Newton [17.26].”
    • reference format. Include the article title if you have it.
    • order references by the order they are cited in the chapter. Rename the reference if reused in another chapter.

bibTeX conventions

  • 8-) In order to fix my issue with journal abbreviations I used a function in my reference management software (JabRef) that lets you toggle between abbreviated and full journal names based on a text file of entries. There is a default list of scientific that you can download from their website which I have complemented with some extra fluids journals (journals.txt).
  • As far as “master CNS bibfile” I meant halcrow.bib… I have been following the P's “bibTex rules”. That is why I was wondering if there was some efficient way to check for overlap. Not so much with having the same paper twice (which really wouldn't change things if you just wrote over the old one) but having two papers with the same bibtex name. I wanted to know if it was possible to check for this automatically. I'll take a look at bibjoin and see what it does… D. Borrero 2009-04-21
  • svn repository gibson/bibtex/05bibTools.txt has the exhaustive list of bibTeX tools known to us. Someone (in a fit of good citizenship) might want to copy that list to here, where everyman can access it.
  • There is no 'master CNS bib file' If we create one, I suggest using the one from svn repository halcrow/bibtex/halcrow.bib, which is the most up-to-date one.
  • rule #1 - have only one bibtex file for all of your papers and the thesis
  • rule #2 - never change the bibtex name of a reference - this tends to create errors in other articles, and is a royal pain to track down. If you are merging several bib files, it's cheaper to have the same reference entered several times under different names than trying to harmonize several papers using the same *.bib — Predrag Cvitanovic 2009-04-20

How did you fix the abbreviations problem? You can find many useful bibtex (and other) scripts here: ftp.math.utah.edu/pub. bibjoin might do the trick for you.

:-? Ok! Fixed the journal abbreviations problem… Still trying to figure out how to merge bib files without messing up everybody's references in the case of overlap.

  • If you found sources other than the ones above (on this wiki already), please add them. — Predrag Cvitanovic 2009-04-20

:?: Does anybody have the *.bst format or macros to convert a generic .bib file to Phys. Rev. E's preferred format (i.e., appropriate journal abbreviations, more than two authors going to first author, et al., etc)? I have also been putting off merging my bib file with the master CNS bib file because I don't know how to check for any overlap and I don't want to mess up somebody's stuff. Does anybody know how to do this efficiently? Any help in these matters would be greatly appreciated. – Daniel Borrero 2009-04-16 14:28 EST

(last edit — Predrag Cvitanovic 2009-04-15)

~~DISCUSSION~~

chaosbook/howto/proofreading.1240337731.txt.gz · Last modified: 2009/04/21 11:15 by dborrero