chaosbook:howto:proofreading
Differences
This shows you the differences between two versions of the page.
| Next revision | Previous revision | ||
|
chaosbook:howto:proofreading [2009/03/30 04:58] predrag created |
chaosbook:howto:proofreading [2010/02/02 07:55] (current) |
||
|---|---|---|---|
| Line 3: | Line 3: | ||
| ====== How to edit and complete chapter chapname.tex ====== | ====== 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 ===== | ||
| - | * chapter/chapname.tex source TeX | + | * the source LaTeX is in chapter/chapname.tex |
| - | * enter date into | + | * update the date in \Chapter{chapname}{22apr2007}{Blah blah} |
| - | \Chapter{chapname}{22apr2007}{Blah blah} | + | |
| * brief motivational preface | * brief motivational preface | ||
| * edits: | * edits: | ||
| - | * keep original text in the public version of the book | + | * while a major rewite is in progress, keep (do not delete) the previous text in the public version of the book |
| \PublicPrivate{ | \PublicPrivate{ | ||
| Line 17: | Line 30: | ||
| }% end \PublicPrivate | }% end \PublicPrivate | ||
| - | * when you remove equation, figure, table, section, remark, example, etc., check the ENTIRE manuscript for references to the edited item, update them | + | * 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 frequently used symbols by a def.tex macros. That helps harmonize notation across ChaosBook. | + | * 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. |
| - | * \index{} entries in the text for all important concepts | + | * add \index{} entry in the text for any important concept |
| - | o check that you have not inadverently removed any | + | * \example{}{}: illustrative examples, preferably "physical" applications, can refer to literature |
| - | * \example{}{}: illustrative examples, preferably "physical" applications, can refer to literature | + | * add relevant tables |
| - | * tables | + | * Fig/fig*.eps - the biggest problem: we need quality figures, lots of them |
| - | * Fig/ figures*.eps - the bigest problem: we need quality figures, lots of them | + | * FigSrc/*/ save the figure source program in the appropriate subdirectory |
| - | * FigSrc/*/: figure source programs in appropriate subdirectory | + | * \Resume: Summary of the key results |
| - | * \Remarks section: all pointers to the literature (no references in the text proper, this is a self contained textbook) | + | * \Remarks: scholarly remarks, all pointers to the literature (no references in the text proper, this is a self contained textbook) |
| - | * \Resume: Summary of the key results | + | * refsChapname.tex: references, Physical Review style. Bracket the unused ones by the \PublicPrivate{ }{place ref here}, do not delete them. |
| - | * refsChapname.tex: references (the Physical Review conventions - please bracket the unused ones by the \Preliminary{ } brackets, do not delete them) | + | * chapter/appendChapname.tex: appendices, if appropriate |
| - | * chapter/appendChapname.tex: appendices, if appropriate | + | * Problems/exerChapname.tex: exercises |
| - | * Problems/exerChapname.tex: exercises | + | * Problems/soluChapname.tex: solutions |
| - | * Problems/soluChapname.tex: solutions | + | * add soluChapname to Problems/solutions.tex |
| - | o add soluChapname to solutions.tex | + | * run through a spell checker (American rather than Queen's or Central European spelling) |
| - | * save (do not delete) text that will go into future versions: | + | * finish __all parts__ of the chapter (mother does not work here) |
| - | \PublicPrivate{% | + | |
| - | ... public text ... | + | |
| - | }{% switch to Private: | + | |
| - | ... text for future versions ... | + | |
| - | }% end \PublicPrivate | + | |
| - | * run through a spell checker (American rather than Queen's or Central European spelling) | + | |
| Notational coherence and proper cross-referencing with the rest of the textbook should be ensured as far as possible. | Notational coherence and proper cross-referencing with the rest of the textbook should be ensured as far as possible. | ||
| + | ===== Style and notation ===== | ||
| - | Edits fall into three general classes: | + | ChaosBook follows the [[http://authors.aps.org/STYLE/|Physical Review Style and Notation Guide]]; |
| - | - trivial ones about wordings and grammar: impelent without comments | + | [[http://forms.aps.org/author/styleguide.pdf|pdf version]]. |
| - | - less trivial ones about suggested revisions of the order of discussions and so on: mark the edits | + | |
| - | - places where I 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). | + | |
| - | Here is the protocol for making changes: | + | * Style: if in doubt, apply the Gibson filter. |
| - | add something like | + | * logarithms: |
| + | * <latex>\ln</latex> if base //e// | ||
| + | * <latex>\log_{10}</latex> if base //10// | ||
| + | * <latex>\log</latex> if base does not matter | ||
| - | %%NW: in the line preceeding a small edit, and | + | ===== References ===== |
| - | %%NW:start edit | + | * each chapter has its references, so cited by [chapter.citation], for example: "as noted by Newton [17.26]." |
| - | ... block of text ... | + | * [[http://authors.aps.org/STYLE/ms.html#footnotes|reference format]]. Include the article title if you have it. |
| - | %%NW:finish edit | + | * order references by the order they are cited in the chapter. Rename the reference if reused in another chapter. |
| + | * [[http://authors.aps.org/STYLE/style_jabbr.html|journal names are abbreviated]] | ||
| + | * [[http://www.slac.stanford.edu/spires/hep/refs/|spires]] (elem. particle physics) guide | ||
| + | |||
| + | ==== 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 ({{gtspring2009:journals.txt|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... //[[daniel.borrero@physics.gatech.edu|D. Borrero]] 2009-04-21// | ||
| + | |||
| + | |||
| + | * {{gtspring2009:pc.jpg}} 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@physics.gatech.edu|Predrag Cvitanovic]] 2009-04-20// | ||
| + | |||
| + | {{gtspring2009:siminos.png?24}} How did you fix the abbreviations problem? You can find many useful bibtex (and other) scripts here: [[http://ftp.math.utah.edu/pub/|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. | ||
| + | * {{gtspring2009:pc.jpg}} If you found sources other than the ones above (on this wiki already), please add them. --- //[[predrag.cvitanovic@physics.gatech.edu|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. -- //[[dborrero@gatech.edu|Daniel Borrero]] 2009-04-16 14:28 EST// | ||
| + | |||
| + | |||
| + | |||
| + | (last edit --- //[[predrag.cvitanovic@physics.gatech.edu|Predrag Cvitanovic]] 2009-04-15//) | ||
| - | if you rewrote a block of text. This way the other person can easily see | ||
| - | what you did by scanning through the file | ||
| ~~DISCUSSION~~ | ~~DISCUSSION~~ | ||
chaosbook/howto/proofreading.1238414327.txt.gz · Last modified: 2009/03/30 04:58 by predrag
Page Tools
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 3.0 Unported
